Describe your project once and get a clean CLAUDE.md (or AGENTS.md) that tells Claude Code your stack, commands, conventions and rules.
How to write a good CLAUDE.md
Claude Code starts every session with no memory of previous ones. A CLAUDE.md file in your repository fixes that: it is loaded into context automatically, so Claude knows how to run your tests, where things live and which rules to follow before it touches any code.
What to include
- Commands. Exact install, dev, test, lint and build commands. This is the highest-value section because Claude otherwise guesses.
- Structure. Only the directories that are not obvious from their names.
- Conventions. Rules that differ from defaults, such as the package manager, code style or how dates are stored.
- Hard limits. Things Claude must never do, such as editing generated files or running migrations unprompted.
What to leave out
Skip anything Claude can read from the code, long tutorials, and stale details that you will forget to update. A short, accurate file works better than a long one because every line costs context on every session. You can check how big your file is with the LLM token counter.
CLAUDE.md vs AGENTS.md
Both are plain markdown instruction files for coding agents. Claude Code reads CLAUDE.md; many other tools read AGENTS.md. Download the same content under either name, or keep both in sync if your team uses several tools.
Frequently asked questions
What is a CLAUDE.md file?
CLAUDE.md is a markdown file in your project that Claude Code reads at the start of every session. It stores durable instructions: how to build and test, how the code is organised, your conventions, and things Claude must not do.
Where do I put CLAUDE.md?
Put it in the root of your repository and commit it so your team shares it. Claude Code can also read a personal CLAUDE.md in your home .claude folder and additional files in subdirectories.
Can I use the same file as AGENTS.md?
Yes. The content is plain markdown. Other coding agents read AGENTS.md, so you can download the same text under that filename, or keep one as the source and reference it from the other.
How long should it be?
Keep it short and specific. Every line is loaded into context each session, so include only what Claude cannot work out from the code itself, such as commands, non-obvious rules and project-specific conventions.
Should I run /init instead?
Claude Code's /init command analyses your repository and drafts a file for you. This generator is useful when you want to write the file by hand before the code exists, or to standardise the format across projects.