Repository orientation

A CLAUDE.md file is read at the start of every session. Treat it like a README written for a new engineer who is fast, literal, and has no tribal knowledge.

Put in CLAUDE.md

• Build, lint, typecheck, and test commands that actually pass today.
• Non-obvious constraints: "never edit generated files", "migrations are append-only".
• Where things live, expressed as one line per subsystem.
• Conventions the team enforces but a linter cannot (naming, error style).

Keep out

• Tutorials and history. The agent does not need the migration story of your company.
• Rules a linter already catches. Duplication teaches the agent to ignore the file.
• Secrets or environment values of any kind.

Keep it short

Every token in CLAUDE.md is paid on every session. Aim for under 150 lines. When a rule only matters for one subsystem, move it to a nested CLAUDE.md in that directory; Claude Code picks up the nearest file.

Verify it works

Ask a fresh agent session: "What commands would you run before opening a PR?" If the answer is wrong or hesitant, your CLAUDE.md failed its job.