How to Write a CLAUDE.md That Improves AI Output
CLAUDE.md best practices: what belongs in the memory file, where the files live, and how to keep it lean with progressive disclosure.
Matthews Wong
Software Engineer
August 20269 min read
BlogAI
Short answers to what readers ask most about this topic.
CLAUDE.md best practices: what belongs in the memory file, where the files live, and how to keep it lean with progressive disclosure.
Matthews Wong
Software Engineer
Key Takeaway
A CLAUDE.md is the memory file Claude Code loads into context at the start of every session, so it shapes the agent's behavior. A good one is short and high-signal: the build and test commands, the conventions that are not obvious from the code, and the mistakes to avoid, not a wiki the model has to wade through.
A CLAUDE.md is the highest-leverage file in an AI-assisted repo and the most commonly misused. It is loaded into the model's context automatically at the start of every session, which means two things at once: everything you put in it steers every task, and everything you put in it costs context on every task. The best ones respect both facts.
This guide covers what CLAUDE.md is, where the files live and how they combine, what actually belongs in one, and the failure mode, namely bloat, that quietly makes them worse. The same principles carry over to the emerging AGENTS.md convention other tools read, so the effort is not Claude-specific.
CLAUDE.md is a memory file: plain Markdown that Claude Code reads into context when a session begins, before you type anything. It is the place to encode the project knowledge a competent new teammate would need on day one but cannot infer from the code alone, such as how to build and test, which conventions to follow, and what not to touch.
The most useful way to think about it is as a standing prompt, not a document. That reframing leads to better choices:
CLAUDE.md is hierarchical. A file in the project root is shared with the team through the repo; a file in your home directory holds personal preferences that apply across every project; and a CLAUDE.md inside a subdirectory is picked up when the agent works in that part of the tree. They layer, so global rules, project rules, and module rules all reach the session together.
You can also compose files by importing others, which keeps each one focused:
# Project: billing-service
## Commands
- Build: pnpm build
- Test one file: pnpm vitest run path/to/file.test.ts
- Lint and fix: pnpm lint --fix
## Conventions
- Money is always integer cents, never floats.
- API handlers live in src/routes and return typed Result objects.
- Never edit generated files under src/db/schema.
## Gotchas
- The test DB must be running: docker compose up -d db
## More detail
@docs/architecture.mdRun the init command once to generate a starter CLAUDE.md from your existing project, then edit it down. The generated draft is a useful skeleton, but the value comes from your curation: the commands it missed, the gotcha that bit you last week, the convention no linter enforces.
A strong CLAUDE.md is mostly the things that are true about your project but invisible to someone reading a single file. In practice that is a short list.
The dominant failure mode is length. A CLAUDE.md that grows into a 500-line manual stops being read carefully, both by the model, which skims, and by you, who stops maintaining it. The discipline is to keep the always-loaded file short and push depth into files the agent pulls in only when relevant.
This is the same progressive-disclosure idea that skills use: a lean top level with pointers to detail. If a section is only relevant to one workflow, it belongs in a doc that workflow references, or in a skill, not in the file that loads on every single turn regardless of what you are doing.
Do not let CLAUDE.md fill with aspirations. Writing always write tests or follow clean architecture as vague commandments trains the model to treat the file as background noise it can skim. Keep every line specific and enforceable, and if a rule really matters, back it with a hook or a check rather than trusting the model to remember a sentence.
A CLAUDE.md is only as good as its accuracy, and accuracy decays. Treat the file as a living part of the codebase rather than a one-time setup step.
A great CLAUDE.md is short, specific, and true: a tight brief a sharp new hire could act on immediately, not an encyclopedia. Write down the commands, the non-obvious conventions, and the boundaries; push everything else behind a pointer; and keep it honest as the project moves. Get that right and every session starts from a better place, before you have typed a word.