---

name: claude-md-authoring description: Use when creating or improving a CLAUDE.md (or AGENTS.md) so coding agents follow project conventions. Covers what to include, what to leave out, and how to keep it from going stale.

CLAUDE.md Authoring

When to trigger

Setting up agent instructions for a repo, or fixing a CLAUDE.md that agents keep ignoring or that has drifted from reality.

Include what is non-obvious

A CLAUDE.md earns its place by encoding what an agent cannot infer from the code:

• The exact build, test, and typecheck commands, and which one the CI gate actually runs.
• Hard rules and their reason: a forbidden pattern, a required helper, a design contract. State the why so the agent applies it in new situations.
• Real pitfalls this repo has hit: the concurrent-build race, the dev-only auth bypass, the file watcher that misses new routes. These save an agent from re-discovering them the hard way.
• Where the living work lives: the TODO or QA file, the deploy verification step.

Leave out what the code already says

Do not restate the directory tree the agent can list, the framework version it can read from package.json, or generic best practices it already knows. Every stale line costs trust in the whole file.

Keep it true

• When a session discovers a durable rule, add it in the same change set. A learning left only in chat is lost.
• When a rule stops being true (a retired design system, a moved command), delete it. A wrong instruction is worse than a missing one.
• Prefer short, factual, grounded lines over prose. Agents act on rules, not essays.

Pitfalls

• A CLAUDE.md that describes an aspirational state instead of the current one makes the agent do the wrong thing confidently. Describe what is true today, mark what is retired.
• Burying the one critical rule in a wall of generic advice gets it skipped. Put hard rules up top and make them scannable.
• Never leave contradictory rules (an old design contract next to its replacement) without marking which one wins.