In practice
Anthropic's docs describe CLAUDE.md files as "markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization." Each Claude Code session starts with a fresh context window, so the file is how knowledge carries over.
Where it lives sets who it applies to. The project file is ./CLAUDE.md or ./.claude/CLAUDE.md and is shared through source control. ~/.claude/CLAUDE.md holds your personal preferences for every project. ./CLAUDE.local.md holds private preferences for one project and is kept out of git.
Claude Code can also read AGENTS.md, the shared file other coding agents use. Since Claude Code v2.1.277, a repository with only an AGENTS.md works with no CLAUDE.md at all. When both exist, Claude reads the CLAUDE.md, so a CLAUDE.md that needs the shared rules imports them with @AGENTS.md on its first line.
It is context, not enforcement. Anthropic's docs say Claude treats it as context, not enforced configuration, and that specific, concise instructions are followed more consistently. It isn't a spec for one job, and it isn't auto memory, which is the notes Claude writes about itself.
How to start
- Run /init in Claude Code to generate a first CLAUDE.md from your codebase.
- Cut it to commands, conventions, project layout and things not to touch.
- Make each line checkable: "Run npm test before committing", not "Test your changes".
- Commit it, so the team shares one file.
- Add a line each time Claude repeats a mistake. Delete lines that stop being true.
Common mistakes
- Letting it grow past a page. Long files cost context and lower how well it is followed.
- Putting this week's priorities in it. They go stale within days.
- Keeping separate copies of the same rules for each agent. They drift.
Why it matters for product builders
Without it, you type the same correction every session. With it, a new session starts from the rules you already settled.
Anthropic's docs suggest adding to it when Claude makes the same mistake twice, or when a code review catches something Claude should have known about the codebase. Keep it short: the docs target under 200 lines per file.
What changes in AI-first products
The file is new with coding agents, so there is no older practice to compare it with. It is close to a README written for the agent.
It holds how you work. It does not hold what to build next. That changes every week and belongs in a plan every agent reads. Annsa holds that part: ranked priorities and specs with the evidence and Done When lines, which Claude Code, Cursor, Codex and Grok read over MCP.
See how Annsa does it: The spec →