CLAUDE.md template for a code repository
Open in the editor Opens as CLAUDE.md, ready to edit. Nothing is uploaded.
The shape of it — edit here, or open the full template
Result
Runs entirely in this tab. Open the full editor to work on a real document.
Markdown is the native format of AI coding tools, and CLAUDE.md is where a
repository writes down what it expects. This template is a structure for that
file — the things worth saying, in the order they get used.
Write down what the code cannot say
The useful content is whatever an agent cannot work out by reading the source. Which command runs the tests. Which directory is generated and must not be hand-edited. Which file looks abandoned and is quietly load-bearing for two large customers.
Restating what the code already says is the most common way these files get long without getting better. If a competent reader would learn it in thirty seconds from the source, leave it out.
Commands first
npm install # setup
npm run dev # local dev server on :3000
npm test # unit + integration; must pass before any commit
npm run build # production build to dist/
This is the section that gets used on every task, so it goes near the top. Add
the one-line comment saying what each command is for — npm run check could
be a linter, a type check, or a deploy gate, and guessing wrong wastes a cycle.
Be specific, not emphatic
Vague instructions are the ones that get applied unevenly. Compare:
- Write good tests.
with:
- Every bug fix gets a regression test that fails before the fix.
The first is a sentiment. The second is checkable. The same applies to emphasis: a file where several rules are marked critical reads as a file with no priorities at all. State the rule once, plainly, and let it stand.
The section people skip
The “things that will bite you” heading is the one most worth filling in, and the one most often left empty — because the traps are obvious to whoever already knows them:
- `src/lib/legacy-parser.ts` is load-bearing for two large customers. It
looks dead. It is not.
- The dev server proxies /api to staging. Data there is real.
- Migrations are irreversible in production. Ask before writing one.
Every line there is something that would otherwise be discovered the expensive way.
Keep it current
An instruction file that has drifted from the project is worse than none, because it is trusted. When a command changes, change it here in the same commit — the file is small enough that this is a habit rather than a chore.
Common questions
- What is a CLAUDE.md file?
- A Markdown file in a repository holding project instructions for Claude Code — how to build and test the project, what the conventions are, and what to avoid. It is committed alongside the code, so everyone working in the repository gets the same context.
- What should go in it, and what should not?
- Things an agent cannot infer by reading the code: which command runs the tests, which directory is generated, which innocuous-looking file is load-bearing. Leave out anything already obvious from the source — restating what the code says adds length without adding information.
- How long should it be?
- Short enough that every line earns its place. A file that opens with several screens of background gets skimmed, and vague instructions are either ignored or applied too broadly. Specific beats comprehensive.
- How is this different from a README?
- Audience. A README introduces the project to a person deciding whether to use or contribute to it. This file briefs someone — or something — that is about to change the code, so it is weighted towards commands, conventions and hazards rather than motivation.
- Is Markdown required?
- The .md extension says so, and it is the sensible choice: headings give the file navigable structure, and code fences keep commands unambiguous. There is no schema to satisfy beyond that — it is prose with structure, not configuration.
- Should I commit it?
- Yes, for anything that applies to the whole project — that is what makes the guidance shared rather than personal. Keep genuinely individual preferences out of it, or they become rules for everyone by accident.