CLAUDE.md That Actually Works: Templates for Real Projects, Not Toys

Watch the video version here: CLAUDE.md That Actually Works: Templates for Real Projects, Not Toys (9 minutes, 3 seconds). This article is the written version, laid out so you can copy the sections that fit your repo.

The file is the only memory your agent has

CLAUDE.md is a plain markdown file that Claude Code loads into every session automatically, before you type anything. Other agent tools have their own version of the same idea, and the principle holds either way: this file is the only memory your agent reliably has.

Sessions end and context windows get compacted. A fresh session tomorrow knows nothing about what today's session figured out, except what is written down. So the rules live in a file, not in your head and not in chat history.

One catch shapes everything else. The file is rented context: it loads every time, so every line costs tokens and attention, and agents skim long files the same way people do. A 600 line CLAUDE.md is not thorough. It is ignored in the middle. So the templates carry a hard rule: keep the file under about 120 lines. If a line does not change agent behavior, it does not belong.

1. Commands, not guesses

The first section is commands, labeled "run these, not guesses." Install. Build. Test. Lint. Run. Each one is the exact string the agent can paste, not a description to interpret.

Two details matter. First, give both the full suite command and the single file command. An agent that can only run a ten minute suite to check a one line fix will start skipping the check, and it will not announce that decision. Second, exact commands end the package manager guessing game. Nobody has time to watch an agent try npm in a pnpm repo, then yarn, then bun, burning turns on archaeology you could have prevented with one line. The command is decided before the work starts, not improvised after it.

2. Conventions and boundaries

Conventions are the handful of patterns that actually matter in the repo. How files are named. How errors are handled, with a real file named as the example. What gets logged, and the one rule with no exceptions: secrets, tokens, and personal data never get logged, printed, or committed.

Then boundaries, and boundaries are the point of the whole file. Never edit generated files, lockfiles, or migrations, and if a task seems to require it, say so instead of doing it. Never commit straight to the main branch. No new dependencies without naming the package and why. These lines read like distrust because they are. An agent optimizes for finishing the task in front of it. The boundary lines are how you tell it which finishes do not count.

The working agreement sits in the same file: read before writing, meaning open the files you will touch and a test that covers them, and keep diffs small and reviewable. A definition of done, covered below, closes the file.

3. One skeleton, three projects

The skeleton never changes. Project, commands, conventions, boundaries, how to work, definition of done. What changes is the layer you add for the kind of project it is.

The general repo template is the base.

The Python microservice template adds architecture rules. Handlers stay thin: parse the request, call a service function, format the response. Business logic lives in the services layer, never in route handlers. Every external call goes through a clients layer, so tests can fake the outside world at one seam. Config comes from environment variables, read once, in one config file. Its testing rules are blunt: every behavior change ships with a test, a bug fix starts as a failing test, and tests never touch the network, a real database, or the clock.

The multi agent template adds governance, because parallel agents fail in social ways. Named roles: an orchestrator that owns the plan and reviews everything, workers that execute one packet each, a reviewer that is read only. File ownership: one writer per file at a time, and shared contract files belong to the orchestrator alone. The packet rule, in four words: no packet, no work. Cost discipline: bulk work goes to the cheapest model that can do it, premium models are for design, hard debugging, and final review.

4. Rules, not state

The fastest way to ruin a good CLAUDE.md is to start using it as a notebook. Current tasks. Progress notes. Decisions from last Tuesday. It feels helpful for about a day.

Then the state moves on and the file does not, and now your rules file is lying to every new session. The agent reads that a migration is still pending three weeks after it shipped, and plans around a world that no longer exists.

Rules of the game go in the file. State of the game goes in the code, the tests, and the task list, the places that stay current on their own. If you keep one split from this article, make it that one.

5. A definition of done

Every template ends with a definition of done. Done means three things: the change itself, tests that cover it, and a verification summary that says what ran, what passed, and what was not checked.

That third item does most of the work. "Tests pass" is a claim. A summary that names the command, the result, and the gaps is something you can check in a minute. It also ends the oldest argument in agent work: the agent says done and means "I wrote some code," you say done and mean "it works and I can prove it." Write the definition down once and the argument stops.

The honest failure: the green suite that proved nothing

The strictest line in my templates says tests are the spec, and tests never get edited to make failing code pass. That line exists because the failure it prevents is quiet and total.

It goes like this. An agent implements something slightly wrong. The test catches it. The agent, optimizing for a green suite, edits the test to match its own output. Suite green. Report says done. And the spec is now whatever the agent happened to write, chosen by nobody, and every later change builds on it. A green suite that was edited to be green proves nothing at all.

So the rule is structural, not moral. Agents do not get write access to the spec they are graded against. And that gives you the maintenance rule for the whole file: when an agent makes the same mistake twice, that is not bad luck. It is a missing line. Add the line. Half the lines in these templates started exactly that way.

Get the Starter Pack

The free Multi Agent Starter Pack is the three CLAUDE.md templates from this article, general repo, Python microservice, and multi agent project, plus the one page orchestration checklist from the first video in this series:

• Download it on GitHub: https://github.com/second-shift-dev/multi-agent-starter-pack
• Or get it by email and join the Second Shift Dev list for new videos and the December launch of the full Multi Agent Coding Ops Kit: https://second-shift-dev.kit.com/f1a6475d0f

The video version of this article is here if you want to see the templates walked through section by section: https://www.youtube.com/watch?v=KZxDAnxXJCQ

The day job ends. The agent team clocks in.

Second Shift Dev