The template
Replace everything in <angle brackets> with your own project, and delete lines that don’t apply. Save it as CLAUDE.md in the root of your repo.
# CLAUDE.md ## Project - What it is: <one sentence> - Stack: <language, framework, package manager> - Where things live: `src/` <...>, `tests/` <...> ## Commands - Install: `<npm ci>` - All tests: `<npm test>` - One test file: `<npm test -- path/to/file>` - Lint and typecheck: `<npm run lint>` and `<npm run typecheck>` - Build: `<npm run build>` ## Long tasks: plan first 1. Before changing code, write the plan to `PLAN.md`: the goal, the files you expect to touch, the steps, and how you will check each step. Then start. 2. Work one step at a time. After each step, run the tests for what you changed and tick the step in `PLAN.md`. 3. Append one line per finished step to `PROGRESS.md`: what changed and the test result. 4. After a compaction or a new session, read `PLAN.md` and `PROGRESS.md` before doing anything else. 5. Commit after each green step: `<type>: <what changed>`. Never amend or rewrite earlier commits. 6. If the same test fails twice for the same reason, stop. Write what you tried in `PROGRESS.md` and wait for me. 7. If the task turns out bigger than the plan, update `PLAN.md` first. ## Done means - `<npm test>` passes, lint and typecheck are clean. - New behavior has a test. - `PROGRESS.md` ends with three lines: what changed, what I should check, what is left. ## Guardrails - Don't push, deploy, publish or merge. I do that. - Don't read, print or edit `.env` files, keys or credentials. - Don't run `rm -rf`, `git reset --hard`, `git clean` or `git push --force`. - Don't add a dependency without writing why in `PLAN.md`. - Don't run migrations or touch production data. - Don't change a test to make it pass unless the test is wrong. If it is, say so in `PROGRESS.md`. - Ask before anything you can't undo. ## Code style - <e.g. 2-space indentation, named exports, no default exports> - Follow the patterns in nearby files before adding new ones. ## Compact instructions When you compact, keep the current step of `PLAN.md`, the latest failing test output and the list of files changed so far.
Why each part is there
- Commands. Exact commands are the most useful lines in the file. The agent runs your real test command instead of guessing one.
- Plan first. For a long run, a written plan is cheaper than re-work. PLAN.md and PROGRESS.md live on disk, so they survive a compaction or a fresh session.
- Stop after two failures. Long runs waste most of their budget retrying the same broken idea. The rule turns that into a note you can read in the morning.
- Done means. Something the agent can check itself: tests pass, lint is clean, a short summary.
- Compact instructions. Claude Code reads a section with this name when it summarizes a long conversation, so the parts you care about survive.
Rules that make it work
- Under 200 lines. The file loads into every session. Longer files cost context and get followed less. Instructions for one part of the code can go in .claude/rules/ with a paths filter; workflows you use now and then can be skills.
- Concrete beats general. “Run npm test before committing”, not “test your changes”. “API handlers live in src/api/handlers/”, not “keep files organized”.
- No contradictions. If two lines disagree, Claude may pick either one. Re-read the file when the project changes.
- It guides, it doesn’t enforce. The Guardrails section tells Claude what not to try. To actually block a push or a .env read, add permission rules: see Never on Always.
- Let Claude draft one. /init scans the repo and writes a starting CLAUDE.md with the build and test commands it finds. Merge in the Long tasks and Guardrails sections from here.
Where it goes
- ./CLAUDE.md or ./.claude/CLAUDE.md: the project, shared through git.
- ./CLAUDE.local.md: just you, this project. Add it to .gitignore.
- ~/.claude/CLAUDE.md: just you, every project.
- Using Codex too? Codex reads AGENTS.md. Claude Code reads AGENTS.md when there is no CLAUDE.md, and a CLAUDE.md can pull it in with a line that says @AGENTS.md. Keep one file and both agents follow the same plan. Codex stops adding instruction files after 32 KiB by default.
sources
Checked against these official pages on 20 October 2026. Plans and limits change; if a page here disagrees with them, the official page wins.