What Is CLAUDE.md?
CLAUDE.md is Claude Code's project-scoped instruction file, loaded automatically at the start of every session. It carries project context, commands, code style, workflow rules, and accumulated gotchas, so the agent starts each session already knowing how your project works.
Key takeaways
- CLAUDE.md is loaded every session, so every line costs context every session. Curation is a maintenance task.
- The gotchas section appreciates in value: each hard-won environment fact recorded is a mistake no future session repeats.
- State the wrong answer alongside the right one where confusion recurs: "port 4242, never 3000" outperforms "port 4242".
- Mature CLAUDE.md files blur into memory systems; dated decision logs keep the history useful.
- It is functionally AGENTS.md for the Claude Code runtime; keep one canonical if you maintain both.
What it is
CLAUDE.md is Claude Code's project-scoped instruction file. It loads automatically at session start, which makes it the highest-frequency document in your repository: every agent session reads it before reading anything else. That property drives everything about how to write it.
What belongs in it
| Section | Contents | The test |
|---|---|---|
| Project context | What this is, who uses it, what must not break | Would a cold session make a wrong assumption without it? |
| Commands | Exact test, build, run commands with ports | Verified by running them |
| Code style | Rules linters don't enforce | Everything else is the linter's job |
| Workflow rules | "Failing test first", "never commit to main" | Stated as imperatives |
| Gotchas | Environment quirks and their workarounds | Each one is a mistake no future session repeats |
| Decisions log | Dated one-liners: what and why | Dated, or it's folklore |
The gotchas section is the one that appreciates. A line like "port 4242, never 3000" costs nothing to write and saves a debugging session every time it fires; note that it names the wrong answer as well as the right one, which is the effective pattern wherever confusion recurs.
The context tax
Because CLAUDE.md loads every session, every line taxes every session. This is the discipline the format demands: it is not a wiki, and it is not an archive. When the file grows past a few screens, it is telling you something has outgrown it:
- Multi-step workflows with verification belong in skills.
- Accumulated facts with dates belong in a memory system that loads an index, not full bodies.
- History belongs in the decisions log at one line per decision, or in git.
A curated CLAUDE.md under a hundred lines routinely outperforms a comprehensive one at five hundred, because the agent actually attends to all of it.
CLAUDE.md as a memory surface
In practice, mature CLAUDE.md files drift toward being memory: sessions append gotchas, decisions, and environment facts. That is healthy if treated deliberately. Date what you append, prune on a schedule, and delete entries that stop being true; an instruction file that asserts stale facts is worse than one that says nothing, because the agent trusts it completely.
Relationship to AGENTS.md
CLAUDE.md is functionally AGENTS.md for one runtime. If multiple agent tools touch your repo, make AGENTS.md canonical and keep CLAUDE.md thin: Claude-specific settings, plus a pointer. One source of truth beats two half-maintained ones.
Start from the CLAUDE.md template; it ships the gotchas and decision-log structure with annotations.
Frequently asked questions
What is CLAUDE.md?
Claude Code's project instruction file, auto-loaded each session: context, commands, style, workflow rules, and gotchas for that codebase.
What are CLAUDE.md best practices?
Exact verified commands, imperatives over prose, a gotchas section, dated decision one-liners, and ruthless pruning: every line taxes every session's context.
How big should CLAUDE.md be?
As small as it can be while preventing repeated mistakes. When it grows past a few screens, move procedures into skills and history into memory files.
Summary
- Topic
- CLAUDE.md: Claude Code's project instruction file
- Definition
- An auto-loaded, project-scoped file of context, commands, rules, and gotchas for Claude Code sessions
- Best used for
- Making every session start with your project's hard-won knowledge
- Related concepts
- AGENTS.md, instruction file, agent memory
- Common mistakes
- Bloat that taxes context, undated decisions, procedures that belong in skills
- Recommendation
- Keep it curated; record gotchas with the wrong answer named; date every decision