AI
How to Write a CLAUDE.md That Improves AI Output
August 20269 min read
A CLAUDE.md is a memory file that Claude Code reads into context automatically at the start of every session, before you type anything. It encodes the project knowledge a new teammate would need but cannot infer from the code alone, such as build and test commands, non-obvious conventions, and boundaries about what not to touch. It shapes the agent's behavior on every task.
Keep it to high-signal facts: the exact build, test, lint, and run commands, including how to test a single file; the non-obvious conventions the code follows but never states; a do-not list of files or commands to avoid; and pointers to deeper docs. Leave out anything that does not change the agent's behavior, because every line costs context on every session.
CLAUDE.md is hierarchical. A file in the project root is shared through the repo, a file in your home directory holds personal preferences across all projects, and a CLAUDE.md in a subdirectory applies when the agent works in that part of the tree. They layer together, and you can also import other files to keep each one focused.
The file is loaded into context on every single session, so its length is a recurring cost and long files dilute the model's attention. A CLAUDE.md that grows into a 500-line manual stops being read carefully by the model and stops being maintained by you. Keep the always-loaded file lean and push depth into referenced docs the agent opens only when relevant.
Use the init command to generate a starter file from your project, then curate it by hand. The generated draft is a useful skeleton, but the value comes from your judgment about what actually matters: the commands it missed, the gotcha that bit you last week, and the convention no linter enforces. A human-curated file consistently beats a purely auto-generated one.
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.