How to write a CLAUDE.md that actually helps your coding agent

Every major coding agent now reads a context file at the start of a session. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. Copilot reads .github/muse-instructions.md. Aider reads CONVENTIONS.md. Different names, same idea: a short document that tells the agent how your project works before it touches a line of code.

Most of these files are useless. They're either empty, or they're a 500-line brain dump nobody maintains. Here's how to write one that actually changes the agent's output.

What the file is for

Think of it as onboarding a sharp junior developer who has infinite energy, perfect memory within a session, and zero knowledge of your project. You wouldn't hand them a 200-page wiki. You'd give them the 10 things that prevent the 10 most common mistakes.

That's the bar: every line should prevent a real mistake you've seen the agent make.

The sections that matter

1. Stack and commands. The two or three commands the agent will run constantly. Build, test, lint, dev server. If tests take 10 minutes, say so — otherwise the agent will run them on every change and burn your context window waiting.

2. Architecture in five lines. Where the code lives, how it flows. "Next.js app in app/, API routes in app/api/, shared logic in lib/, database via Prisma in prisma/." That's enough. The agent can read the rest.

3. Conventions that differ from the default. Don't document standard practice — the model already knows it. Document where you diverge: "We use snake_case for database columns but camelCase in TypeScript." "All dates are UTC in the database, converted at the UI layer." "Never use any; prefer unknown with narrowing."

4. Things that have bitten you. This is the highest-value section. "The payments table has no foreign key to users — join on customer_email." "Don't run migrations against the staging database; use the seed script instead." Each line here saves a debugging session.

5. What not to do. Explicit prohibitions work better than you'd expect. "Don't add new dependencies without asking." "Don't refactor files unrelated to the task." "Don't write tests for generated code."

What to leave out

Tutorials. The agent was trained on every framework's documentation. Don't explain what React hooks are.

Aspirational rules. If the codebase doesn't actually follow the convention, writing it down just teaches the agent to produce code that clashes with reality.

Secrets and credentials. This file gets committed to git and possibly sent to third-party APIs. Never put tokens, passwords, or internal URLs in it.

More than ~150 lines. Long files get skimmed or truncated. If it's growing past that, split project-wide conventions (keep in CLAUDE.md) from directory-specific ones (put CLAUDE.md files in subdirectories — most agents support nesting).

A minimal template

# Project name

One-line description of what this project does.

## Commands

- Dev: `npm run dev`
- Test: `npm test` (full suite ~4 min; use `npm test -- path/to/file` for one file)
- Lint: `npm run lint`

## Architecture

- `app/` — Next.js routes and pages
- `lib/` — shared business logic
- `db/` — Prisma schema and migrations

## Conventions

- Database columns are snake_case; TypeScript is camelCase.
- All timestamps stored as UTC.
- Prefer `unknown` over `any`.

## Gotchas

- The `orders` table joins to users on `email`, not `user_id`.
- Don't run `prisma migrate` on staging — use `npm run db:seed`.

## Don't

- Don't add dependencies without asking first.
- Don't refactor files outside the task scope.

Start with this skeleton, then add one line every time the agent makes a mistake you could have prevented. After a month, you'll have a file worth more than most documentation.