claude-md

What this skill does

# CLAUDE.md Updater

Analyze session changes and propose targeted CLAUDE.md updates following Anthropic's best practices.

## Rules (strictly enforced)

1. **Never** add code examples or code blocks to CLAUDE.md — agents can read source code directly
2. **Keep CLAUDE.md concise** — target 200 lines for small/medium projects, up to 500 for large monorepos; every line must earn its place
3. **Write in imperative form** — "Run tests with `npm test`" not "Tests are run with `npm test`"
4. **Concrete over vague** — ban the words "properly", "correctly", "appropriate", "as needed", "ensure quality"
5. **Only document surprises** — skip anything an agent could infer from reading the code, package.json, or directory structure
6. **No sensitive data** — never include secrets, tokens, credentials, API keys, or internal URLs
7. **Always confirm with user** before writing any changes to CLAUDE.md

## Workflow

### Step 1 — Determine what changed

Gather information from three sources, in priority order:

**A. User-provided description** — If `$ARGUMENTS` is non-empty, treat it as the primary input describing what changed. Use it to frame the update. You may still run selective git commands from (B) to corroborate details, but the user's framing takes precedence.

**B. Git session changes** — When `$ARGUMENTS` is empty, or as a supplement to (A), run these commands (skip if not a git repo):

- `git branch --show-current` — current branch
- `git diff HEAD` — unstaged changes
- `git diff --staged` — staged changes
- `git log --oneline -10` — recent commits
- `git merge-base HEAD main` (or the default branch) — find where the branch diverged
- `git diff <merge-base>..HEAD` — all committed changes in this session

**C. Conversation context** — Always review the conversation for discussed decisions, patterns, tooling choices, or conventions that may not appear in diffs (e.g., "we decided to use Zod for validation", "prefer named exports").

Merge all sources. When the user description (A) conflicts with git (B), prefer the user's framing.

### Step 2 — Read existing CLAUDE.md

Look for `CLAUDE.md` at the project root. If found:

- Read the full file
- Note the current line count
- Identify existing sections and their content
- Flag any overlap with what the session changes might add

If no CLAUDE.md exists, note that a new file needs to be created.

### Step 3 — Identify update triggers

Evaluate the session diff against the trigger categories in the table below. For each category, determine if the changes warrant a CLAUDE.md entry.

If **no triggers fire** — tell the user "No CLAUDE.md update needed — these changes don't introduce anything that would surprise a future agent." and **stop**.

### Step 4 — Draft the update

**If creating a new CLAUDE.md**, use this section template (omit sections that have no content):

- Project Overview
- Tech Stack
- Commands
- Architecture
- Code Style
- Environment
- Gotchas

**If updating an existing CLAUDE.md**, draft only targeted additions or edits to existing sections. Do not rewrite sections that are unchanged.

Writing rules for all entries:

- One bullet per concept
- Start with imperative verb
- No sub-bullets or nested lists
- No code blocks (inline backticks for commands and names are fine)
- Maximum 2 lines per entry
- Check total line count stays within budget (200 for small/medium projects, up to 500 for large monorepos)

### Step 5 — Present for review

Show the complete draft to the user, then use `AskUserQuestion` with these options:

- **Header:** "CLAUDE.md"
- **Options:**
  - "Apply this update" — write the changes to CLAUDE.md
  - "Let me refine the draft" — user will provide edits before applying
  - "Skip — no update needed" — discard the draft and stop

### Step 6 — Write the file

Apply the approved changes to CLAUDE.md at the project root. After writing, confirm the action and report the final line count.

## Update Trigger Categories

| Category | Fires when | Does NOT fire when |
|---|---|---|
| **Commands** | New build/test/lint/deploy commands added, existing commands changed, new scripts in package.json | Existing commands used without changes |
| **Tech Stack** | New language, framework, or major dependency added; runtime version changed | Minor dependency updates, patch bumps |
| **Architecture** | New top-level directories, new module boundaries, new API patterns, significant structural refactors | Moving files within existing structure, renaming |
| **Code Style** | New lint rules enforced, new naming conventions established, new formatting config | One-off style fixes, auto-formatter runs |
| **Environment** | New env vars required, new services to run locally, new setup steps | Config value changes, port number tweaks |
| **Gotchas** | Non-obvious workarounds discovered, surprising behavior documented, platform-specific quirks | Obvious bugs that were fixed, temporary hacks removed |
| **Testing** | New test framework, new test commands, new coverage requirements, testing patterns established | Adding individual test files, fixing tests |
| **Project Overview** | Project purpose or scope changed significantly, new major feature area | README updates, minor scope adjustments |

## CLAUDE.md Quality Checklist

Before presenting the draft in Step 5, verify:

- No duplicate entries (check against existing content)
- No fragile absolute file paths (use relative paths or describe locations)
- No code blocks (only inline backticks)
- No vague words ("properly", "correctly", "as needed", "ensure")
- All commands are explicit and runnable
- All required environment variables are named
- Total line count is within budget (200 small/medium, up to 500 large monorepos)