CLAUDE.md Files: Teaching Agents Your Project In One Read

Claude Code reads CLAUDE.md at session start. Most projects do not have one, so the agent rediscovers the conventions every time. A focused file makes the agent productive from the first message.

What Goes In Mine

Three sections, nothing else. Conventions, gotchas, commands.

## Conventions
- Python: 4-space indent, type hints everywhere, snake_case
- TS: 2-space indent, strict mode, camelCase
- Imports: stdlib, third-party, local (blank line between)
- No em dashes ever
 
## Gotchas
- DynamoDB table has single-table design, see TABLE.md
- SES is in sandbox; test emails only go to whitelisted addresses
- `npm run dev` starts backend too via concurrently
 
## Commands
- Lint: `npm run lint && ruff check .`
- Test: `npm test && pytest`
- Deploy: `./deploy.sh`

That is the whole file. Under 300 words. Read once per session. Saves the agent from asking 'what is the test command' every time.

What Does Not Belong

Architecture explanations. Full API docs. Philosophy. Those go in ARCHITECTURE.md or README.md, which the agent reads on demand. CLAUDE.md is for the things the agent needs immediately and repeatedly.

The Review Loop

Every time the agent does something I did not want, I ask: does this belong in CLAUDE.md? Usually yes. The file grows slowly as I notice patterns. After a month it stabilizes.

This is the single highest-leverage file in an agentic codebase. More leverage than any prompt tuning. The agent can be brilliant in vacuum and wrong in your project. CLAUDE.md fixes the second problem.

See the Claude Code project context docs for the full shape. Write yours today. Five paragraphs beats no paragraphs.