CLAUDE.md best practices, with a template.

Guides

CLAUDE.md is the instruction file Claude Code loads into every session. Claude Code reads your personal file at ~/.claude/CLAUDE.md and the project's CLAUDE.md at the repository root, plus CLAUDE.md files in parent folders. Files in subfolders load when Claude works in them. Whatever is in those files is paid for on every turn of every session, so the job is to keep it short and true.

What belongs in it

  • Rules that apply to every session. How you want results reported, what needs your approval, the commit style.
  • The verify command. One command the agent runs before it says done. Name it exactly.
  • Hard boundaries. Generated folders, migrations, CI config: anything the agent must not edit, or must ask about first.
  • Pointers, not content. One line saying where the architecture notes or the release steps live and when to read them.

What to leave out

  • History. "On 3 March the queue broke, so..." is a work log entry. Keep the lasting rule, drop the story and the date.
  • Retired rules. A line marked SUPERSEDED still loads every session. Delete it; git remembers.
  • Repeats. The same rule written three ways reads as three rules, and the copies drift apart.
  • Secrets and machine paths. The file is often committed and always sent to the model. Reference a secret by its name or vault path, and write ~ instead of C:\Users\you.
  • Procedures you rarely run. Release checklists and migration recipes belong in a doc or a skill the agent loads when the task calls for it.

How big is too big

A useful budget is about 3,500 estimated tokens per engine, roughly 14,000 characters, counting your personal and project files together. CommonRig's own rule kernel is built to that budget, and the footprint score starts deducting a point for every 250 estimated tokens past it. Past that size, rules start competing with each other and with the task for the model's attention. Trimming a long file covers how to get back under.

A template

Replace the specifics with your own. Every line here either changes behaviour or points somewhere.

# Instructions for <your name>

## Working style
- Lead with the result, then the evidence. Keep summaries short.
- Ask before anything hard to undo: deletes, force pushes, schema changes.

## This repository
- Stack: TypeScript, Node 22, Postgres. Package manager: pnpm.
- Verify with: pnpm verify (typecheck, lint, tests). Run it before you say done.
- Never edit generated files under src/gen/; change the schema and rebuild.

## Git
- Short lowercase commit headings, bullet outcomes in the body.
- One branch per change. Never push to main directly.

## Where things live
- Architecture notes: docs/architecture.md (read before touching src/core/).
- Release steps: docs/release.md (load only when releasing).

Keep it honest over time

Instruction files grow by accretion: something goes wrong, a rule gets added, nobody removes it. Give each rule a short id (GIT-COMMIT, TEST-GATE) so you can refer to it, review it and delete it on purpose. If you also use Codex, keep one source and generate both files; sharing one rule set shows how. Rules ask; hooks enforce the few that must never be broken.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides