CLAUDE.md examples
What a useful CLAUDE.md contains, with the sections Claude Code actually follows on a real codebase.
Claude Code reads this file as memory
CLAUDE.md sits at the repository root. Claude Code loads it when a session starts. Nested CLAUDE.md files apply inside a directory. Treat the root file as the standing brief: stack, commands, boundaries, and how to tell that you are done.
A good example is boring. It says 'this is a FastAPI service, request bodies are Pydantic v2 models, tests are pytest, do not block the event loop.' It does not recap Claude's product documentation.
An example shape
Open with one paragraph that names the stack. Then a command list, a conventions list, and a short avoid list. End with done-when checks. If you want comments only where the why is non-obvious, say that once. Repeating it under every heading wastes the context window.
You can generate a first example for your stack and then delete anything the repo does not do. A Django project should not keep a FastAPI sentence just because the template had one.
Do it in this order
01
Generate a stack-specific draft
Start from a CLAUDE.md written for the framework you use.
02
Swap commands
Put the exact pytest, go test, or npm script the repo runs.
03
Cut anything untrue
Delete frameworks, folders, and linters you do not have.
04
Restart Claude Code
A running session will not pick up the new file.
Questions
Does CLAUDE.md replace AGENTS.md?
No. Claude Code reads CLAUDE.md. Several other agents read AGENTS.md. Many repos commit both, with the same rules.
How long should an example be?
Aim for a page. If you need more, split a nested CLAUDE.md into the folder that needs the extra rule.