CLAUDE.md: format, examples, and best practices

A CLAUDE.md file sits in your repository root and is read by Claude Code at the start of every session. It's the difference between an agent that guesses your commands and conventions, and one that knows them. This guide covers what to put in it, what to leave out, and the mistakes that make agents worse.

What CLAUDE.md is for

Claude Code loads CLAUDE.md automatically as standing instructions. It's the right place for exactly three kinds of content:

• Commands — how to install, run, build, lint, and test this repo, including how to run a single test. This is the highest-value section: without it, agents invent plausible-but-wrong commands.
• Conventions — the rules a senior teammate would enforce in review: framework idioms, boundaries between layers, what not to touch.
• Gotchas — the failure modes of your specific stack, so the agent doesn't rediscover them at your expense.

A complete example

# CLAUDE.md

## Project

**acme-api** — internal billing API.
Stack: Python, FastAPI, uv, pytest, Ruff.

## Commands

- Install dependencies: `uv sync`
- Run dev server: `uv run uvicorn app.main:app --reload`
- Run all tests: `uv run pytest`
- Run a single test: `uv run pytest tests/test_billing.py::test_proration`
- Lint: `uv run ruff check .`
- Format: `uv run ruff format .`

## Conventions

- Request/response shapes are Pydantic models; set `response_model` on routes.
- DB access through the repository layer in `app/repos/` — routes never
  touch the session directly.
- Async routes must not call blocking IO; use async clients or
  `run_in_threadpool`.

## Gotchas

- A sync call inside an `async def` route blocks the event loop —
  this is our most common performance regression.
- Alembic autogenerate misses column renames; always read the
  generated migration before applying.

Best practices

• Short beats complete. The file is loaded into every session's context. 60 focused lines outperform 400 thorough ones — an agent skims a wall of text the same way you do.
• Imperative voice. "Use X", "Never Y". Not "we generally prefer".
• Exact commands, not descriptions. uv run pytest tests/foo.py::test_name, not "run pytest on the relevant file".
• Keep it true. A CLAUDE.md that says npm test after you moved to vitest is worse than no file — the agent trusts it over its own exploration. Review it in PRs like code.
• Don't duplicate what the agent can read. Directory listings, full API docs, and code walkthroughs age badly; the agent can explore. Record what it can't infer: intent, boundaries, tribal knowledge.

CLAUDE.md vs AGENTS.md

AGENTS.md is the open, tool-agnostic equivalent — the same substance, read by many coding agents. Claude Code reads AGENTS.md as well when CLAUDE.md is absent; teams commonly commit both (or make one a symlink of the other) so every agent in the toolchain gets the same instructions. Our generator emits both from one detection pass.