CLAUDE.md is the highest-leverage file in any repo: it shapes how every agent behaves, on
every task, for every person who opens the project. A good one prevents mistakes across
hundreds of sessions. A bloated one gets ignored under context pressure, which is worse than
none because it creates false confidence.
This skill produces a short file that carries only what an agent cannot infer, plus the verification habits that protect someone who cannot evaluate an agent's output themselves.
When to use
- Starting a new project
- A repo has no
CLAUDE.md - An existing one has drifted past ~60 lines of actionable content, or has gone stale
- Setting up a project for someone who is not a professional developer
The one principle
Include only what an agent cannot derive by reading the code.
An agent can already read the directory tree, infer the framework, and see the types. It cannot know your Canvas course id, that a deploy needs a flag you learned the hard way, or that the staging database is the one that matters. Everything you write should fail this test: would removing this line cause a mistake? If not, cut it.
| Include | Exclude |
|---|---|
| Commands that cannot be guessed | Anything discoverable by reading code |
| Env vars, external ids, endpoints | Directory trees, type listings |
| Gotchas that cost hours | Generic framework docs (link instead) |
| Verification commands | Code snippets that go stale |
| Security boundaries | Empty placeholder sections |
| Current focus and next steps | Vague advice like "write clean code" |
Steps
- Check for an existing file. If one exists, read it and preserve anything non-inferable. Never discard hard-won gotchas while restructuring.
- Detect the project type from its files (
package.json,pyproject.toml, mostly.md, etc.) so the template's commands section fits reality. - Copy
assets/CLAUDE.md.templateto the repo root asCLAUDE.md. - Fill only the sections that have real content. Delete the rest. An empty
## Roadmapis noise; add it when there is a roadmap. - Verify every command you wrote by running it. A build command that does not work is worse than no build command, because the agent will trust it. This step is not optional.
- Add the guardrails section verbatim. It is the part that protects a non-expert user.
- Consider a hook for anything critical. A rule that lives only in
CLAUDE.mdwill be skipped in a long session. That is structural, not a discipline problem. If a rule really matters, wire it into a hook or a CI gate and reference it from the file.
Keep it short
Aim for under 60 lines of actionable content. Session logs and roadmaps at the bottom do not count toward that, since they sit in the part of the context agents attend to least.
When a file outgrows the limit, the culprit is almost never the session log. It is inline
runbooks: deployment steps, architecture notes, troubleshooting. Move each to docs/<topic>.md
and leave a five-line summary plus a link. Watch out for repos where docs/ is the publish
root (a docs site, GitHub Pages) — use internal/ there instead.
Maintenance
- Keep only the single most recent session-log entry. Older ones go to
docs/session-archive.mdor get deleted. - Add rules reactively, after a repeated failure. Not preemptively.
- Delete instructions the agent already follows without being told.
- Re-verify commands periodically. A stale command is a trap, not documentation.
Common mistakes
- Writing a directory tree an agent can generate itself
- Documenting the happy path but not the gotcha that actually costs time
- Putting a hard requirement in prose instead of a hook, then being surprised it was skipped
- Leaving placeholder sections that make the file look complete
- Copying commands from another project without running them here