Writing CLAUDE.md

Triggers automatically when relevant; invoke directly with /writing-claude-md or ask, e.g. "audit my CLAUDE.md".

Distilled from Anthropic's official Claude 5-era sources (as of 2026-07): the Claude Code docs (memory, best-practices, large-codebases), the claude.com posts "The new rules of context engineering for Claude 5 generation models" (2026-07-24) and "Steering Claude Code" (2026-06-18), and the platform.claude.com model-generation docs. Full source list at the bottom.

Why length and phrasing matter

CLAUDE.md is delivered as a user message after the system prompt — advisory context, not enforced configuration. Adherence is the thing you are engineering: short, specific, conflict-free files get followed; bloated ones get ignored. Anthropic names this failure "the over-specified CLAUDE.md" — when the file is too long, important rules get lost in the noise, and conflicting rules get picked between arbitrarily. Anthropic cut over 80% of Claude Code's own system prompt for the Claude 5 generation with no measured loss; verbose rulebooks now work against the model.

The contract — a CLAUDE.md passes when

[ ] each file is under 200 lines (official target)
[ ] every line passes the pruning test:
    "Would removing this cause Claude to make mistakes?" — if not, cut it
[ ] zero conflicts across the whole loaded set (all scopes, rules, imports) —
    conflicting rules are resolved arbitrarily, so one must go
[ ] zero lines from the Claude 5 remove list
    (see references/claude5-migration.md)
[ ] every piece of content sits in the right mechanism (routing table below)

Write behavior: present the routing plan (what moves where, what gets cut) before touching any file, then edit in place — and prefer a clean git tree, so every change lands as a reviewable, revertible diff.

Step 1 — Recon: read what actually loads

Inventory every file in the loaded set before judging any of them, because conflicts and duplication live between files:

• Managed policy CLAUDE.md (org-controlled, if present)
• User: ~/.claude/CLAUDE.md — personal, all projects
• Project: ./CLAUDE.md or ./.claude/CLAUDE.md — team-shared
• Local: ./CLAUDE.local.md — personal, gitignored
• Rules: .claude/rules/*.md and ~/.claude/rules/*.md — files without paths: frontmatter load at launch just like CLAUDE.md
• Everything reachable through @path imports (max 4 hops) — imports load in full at launch, so they count against the same budget
• Parent-directory CLAUDE.md files up the tree (all load at launch)

In an interactive session, /context shows which memory files actually loaded. Record per-file line counts as the baseline for the final report.

Step 2 — Route: put each piece where it loads correctly

The extraction signal for skills: a CLAUDE.md section has grown into a procedure rather than a fact, or the same instructions keep being re-pasted into chat.

Step 3 — Write or trim

Include (the non-derivable): bash/build/test commands Claude can't guess; code style rules that differ from language defaults; testing instructions and preferred runners; repository etiquette (branch naming, PR conventions); project-specific architectural decisions; required env vars and environment quirks; non-obvious gotchas.

Exclude (the derivable and the generic): anything Claude can figure out by reading code; standard language conventions; detailed API docs (link instead); frequently-changing information; tutorials; file-by-file codebase descriptions; self-evident practices like "write clean code". Folder hierarchies and naming conventions already carry this signal.

Altitude: mechanical facts stay maximally concrete and verifiable — "Run npm test before committing", "API handlers live in src/api/handlers/" — because vague versions of these underperform. Behavioral guidance stays at judgment level with a reason attached — "Write code that reads like the surrounding code: match its comment density, naming, and idiom" — because Claude 5-generation models generalize from the explanation, and exhaustive edge-case enumerations are the failure mode, not the fix.

Phrasing: say what to do rather than what to avoid, and give the reason instead of raising the volume — a one-clause rationale outperforms emphasis markers on current models, where aggressive language causes overtriggering. Structure with markdown headers and bullets; there is no required format.

Details, tables, and worked examples: references/include-exclude.md and references/examples.md.

Step 4 — Verify

[ ] wc -l on every file in the loaded set — each under 200
[ ] conflict scan: read the concatenated set as one document; flag any two
    rules a reasonable reader could follow in opposite directions
[ ] remove-list scan: grep for verification mandates, anti-laziness prompts,
    "be conservative" framing, ALL-CAPS emphasis, reasoning-echo instructions
    (patterns in references/claude5-migration.md)
[ ] /doctor (Claude Code v2.1.206+) — proposes trims; it cuts derivable
    content and keeps pitfalls, rationale, and non-default conventions
[ ] behavior test: for at least one changed instruction, observe whether
    Claude's behavior actually shifts — that is the ground-truth check

Step 5 — Prove

Report before/after per file: line counts, what moved where (skill, rule, hook, deleted), and which remove-list classes were cleared. A trim without this report is indistinguishable from content loss.

Maintenance rules

• Add an entry on repetition signals, never speculatively: Claude makes the same mistake a second time; a review catches something Claude should have known; you retype a correction from a previous session; a new teammate would need the same context.
• Re-audit after every major model release — workaround rules for an older model's limitation become pure overhead once the newer model handles it.
• Give the file an owner and review changes like code: every line loads for every engineer in the repo, every session.
• Test edits the way you'd test a prompt: by observing whether behavior shifts, not by whether the text reads well.

Reference files

• references/include-exclude.md — full include/exclude tables, specificity before/after pairs, the canonical minimal file, when-to-add triggers
• references/claude5-migration.md — the remove list for Claude 5-generation models, emphasis guidance, model-tier conditionality
• references/mechanics.md — load hierarchy, imports, compaction, tooling (/init, /doctor, /context, /memory), auto memory, monorepos, AGENTS.md
• references/examples.md — annotated before/after trims, good and bad files

Related skills

• skill-creator — authoring the skills that extracted procedures move into
• universal-loop — the execute-verify engine for running this audit
• compounding-engineering — the correction-to-rule pipeline that feeds legitimate CLAUDE.md entries

Sources (all official Anthropic, current as of 2026-07)

• code.claude.com/docs/en/memory · /best-practices · /large-codebases · /skills
• claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models (2026-07-24)
• claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more (2026-06-18)
• claude.com/blog/building-verification-loops-in-claude-code-with-skills (2026-07-22)
• platform.claude.com — prompting best practices, Claude 5 migration guide, Fable 5 / Opus 5 model pages, Agent Skills best practices
• anthropic.com/engineering/effective-context-engineering-for-ai-agents (2025-09-29)