Coding agents don't fail because they can't write code. They fail because they guess: which folder a feature belongs in, how billing is wired, whether the project uses middleware or something newer. Every guess is a chance to invent a second pattern for something your codebase already does one way.
The fix isn't a smarter agent — it's a codebase that answers questions before they're asked. In this boilerplate that job belongs to one file: CLAUDE.md.
What goes in it
Not a wiki. One file, checked into the repo, that states the things an agent would otherwise guess:
- Golden rules — no
any, thin routes / thick modules, every public function documented, never commit secrets. - The map — the repository layout with one line per folder, and the anatomy of a feature module worth copying.
- Recipes— "how to add a feature" and "how to add a billable AI endpoint", as numbered steps that reference real files.
- Gotchas— the things newer than the model's training data. Next.js 16 renamed middleware to
proxy.ts; the file says so, so no agent reinventsmiddleware.tsfrom memory.
Patterns beat instructions
Agents copy what they see more reliably than they follow what they're told. That's why the recipes point at reference implementations — the auth module is the canonical module shape, the chat route is the canonical billable endpoint. When an agent is asked for a "summarize" endpoint, it reads the chat route, matches the pattern, and the diff comes back looking like the codebase already looked.
Keep it honest
A stale guide is worse than none — an agent will follow it off a cliff. Two habits keep it truthful: update the file in the same commit as the change that invalidates it, and prefer describing where things live over how things work (locations change less often than implementations).
The test is simple: give an agent a one-line task and read the diff. If it put the logic in a module, typed the boundaries, and ran the checks — your documentation is working. That diff is this product's demo.