Onboard the agent like a senior hire

When a senior engineer joins a team, someone spends an hour telling them how to run the app, how to test it, what "done" means, what's off-limits, and who to ask when they're stuck. Skip that hour and they'll guess, and some of those guesses will be expensive. An agent needs the same hour — the difference is that it can only get that briefing from files, not from a conversation over coffee, and most teams never write it down anywhere the agent will actually read it.

The checklist is the same one you already have

You don't need a new onboarding format. Use the one you already give humans: how do I run this, how do I test it, what's the definition of done, what must I never touch, who do I ask. The only new step is mapping each answer to something the agent reads before it starts — README and Makefile for the first, test config and a verification hook for the second, and so on, as shown in the figure.

CLAUDE.md carries the two questions no file answers

Notice that two of the five rows point to the same file. "How do I run this" and "what must I never touch" are things the codebase can express on its own — a Makefile target, a permission rule — so the agent can, in principle, derive them without you writing anything extra. "When am I actually done" and "who do I ask" can't be read off the code. Nothing in a diff tells the agent whether deleting a failing test counts as fixing it, or whether a schema change needs a specific person's sign-off before it ships. That's exactly the gap CLAUDE.md exists to fill: durable context the code can't express for itself.

Write it as instructions, not description

A common mistake is writing CLAUDE.md like a README — describing the architecture the agent could read from the code anyway. Write it like a checklist for a new hire instead:

## Definition of done
- `make test` passes with no skipped tests
- New endpoints have a request/response example in the PR

## Never do this
- Never edit files under `migrations/applied/`
- Never delete a failing test to make CI green — flag it instead

## Ask before doing
- Schema changes: ping @data-team in the PR

Each line answers a question a new hire would ask verbally. That's the test for whether it belongs in the file.

Keep the checklist current, not comprehensive

An onboarding doc that lists everything goes stale and gets skimmed, same as it would for a human. Keep it to the handful of things that would actually cause damage or wasted work if missed — the deny list, the definition of done, the escalation point — and let the agent read the rest from the code, same as you'd expect a new hire to read the codebase instead of asking about every function.

Try it today

1. Write down the five onboarding questions you'd answer for a new engineer, out loud, from memory.
2. For each one, name the exact file where an agent would find that answer today. If there isn't one, that's the gap to fix.
3. Add a "Definition of done" section to CLAUDE.md with checkable criteria, not adjectives like "clean" or "robust."
4. Add a "Never do this" section listing the two or three mistakes that would actually hurt if an agent made them.
5. Test it: start a fresh session, give it a real task, and see which of the five questions it gets wrong. Fix that file, not the prompt.

Where this breaks

A CLAUDE.md written once during setup drifts the same way a stale onboarding doc does — nobody updates it after the incident that should have taught it something. Deny lists and hooks catch mistakes only if someone thought to write the rule down first; they don't generalize to a new kind of mistake the way a human colleague's judgment would. And over-specifying "how to run this" in prose, when a single make test command would do, just gives the agent more text to parse and more chances for the doc and the Makefile to disagree.

Next: verification is the bottleneck — why the checklist above matters less than what checks it before anything ships.