AgentSkillsCN

ledger

审查并更新 Claude.md 文件——检查模板合规性、揭示缺失的需求/边界，并提出账本条目。

SKILL.md
--- frontmatter
name: ledger
description: Review and update Claude.md files — check template compliance, surface missing requirements/boundaries, and propose ledger entries.
context: fork

Ledger

Review and update Claude.md files against the Why/What/How template.

Template Reference

Read /cc reference claude-md.md for the full template before making any changes.

Claude.md Changes

!git diff HEAD --stat -- '**/Claude.md'

Modes

Review (default)

/ledger or /ledger path/to/dir

  1. •Read the Claude.md at the target path (default: nearest to cwd)
  2. •Check template compliance:
    • •Why section exists (min 1 sentence)
    • •What section exists with Requirements and/or Boundaries
    • •Ledger section exists (min 1 versioned entry)
  3. •Run git log --oneline -20 -- <dir> for the target directory
  4. •Identify:
    • •Architectural decisions in recent commits without ledger entries
    • •Requirements or Boundaries that may be stale based on recent changes
    • •Missing template sections
    • •Content that belongs at a different level of the hierarchy (too specific for parent, or duplicating parent in child)
  5. •Propose updates as diffs — one concept per diff

Backfill

/ledger backfill or /ledger backfill path/

  1. •Find all Claude.md files under the target path: git ls-files '**/Claude.md'
  2. •For each non-compliant file: a. Read full contents b. Extract implicit requirements and boundaries from existing HOW sections c. Draft Why/What sections with Requirements and Boundaries d. Add initial Ledger entry
  3. •Present all proposals grouped by file as diffs
  4. •Apply approved changes

Rules

  • •Only extract constraints that are intentional architectural decisions, not incidental implementation details
  • •Requirements use must and always
  • •Boundaries use never
  • •Ledger entries are keyed by the file's version number: - v1.1: Description of decision. Adding a ledger entry requires bumping the version; bumping the version requires a ledger entry. They enforce each other
  • •One entry per architectural decision in the commit — not per iteration step
  • •Short WHAT, then WHY when not obvious (for/because). Most entries under 10 words
  • •Never include HOW details — name the decision and motivation, not the implementation mechanics
  • •Amend existing entries when iterating before committing — the ledger matches what git shows (A→C, not A→B→C)
  • •Ledger records facts ("Replaced Nginx with Caddy"), not ongoing constraints — those go in Requirements or Boundaries
  • •One concept per change — don't restructure entire files in a single diff
  • •Preserve all existing content — restructure, don't delete
  • •When extracting from HOW sections: move the constraint to What, keep the implementation detail in How
  • •Read the full Claude.md file before proposing any edits — piecemeal edits without full context cause contradictions and repetition
  • •Never fabricate WHY in ledger entries — if the motivation is unknown, ask. "Chose X" requires knowing why X was chosen
  • •Ledger entries record decisions, not descriptions — don't repeat what the file already documents
  • •Ledger entries are one line — details belong in the file body or a deeper Claude.md, not the ledger
  • •Never include execution context in ledger entries — impact scores, importance ratings, and session metadata are meaningless outside the session
  • •Never place scope-specific entries in parent Claude.md files — a decision about backend belongs in the backend Claude.md, not root