Anthropic closes its piece on code review with a rule: when the reviewer misses something, ask what the model didn't have in front of it and put the fix in a CLAUDE.md, a skill or a new check (the article (si apre in una nuova scheda)). Reading it, Theo called that the wrong default, and here I'm with him. I've worked this way for months: I change the code so the mistake becomes hard to make, add a check that catches it, and only then write instructions. Before tinkering with CLAUDE.md and REVIEW.md, ask yourself whether the architecture or the code should change to make the mistake impossible by design. Spoiler: it often should.
Instructions are the most fragile place for a rule
An instruction is paid for in context on every session, it can be read the most expensive way, and it goes stale when the code moves. I learned it on my own setup. My instructions said to use the strongest model for decisions, and the orchestrator was also launching it as a subagent for ordinary work. Today that rule is written in capitals (the story). Capitals are still words. The next step is a check in the harness that refuses that launch, the same way a linter refuses an import.
A missing translation breaks the build
This site is written in Italian, English and Polish. I could have told the agents to remember to translate every essay. Instead the build fails if an essay exists in one language and is missing in another, so neither I nor an agent can publish half a change. This essay exists in three languages because the site doesn't compile otherwise.
The colophon has a line I still stand by: the minimum sufficient context is a property of the repo, not of the prompt.
Retire the wrong option and fence it
At Intarget, on the agentic platform, two libraries were doing the same job of fetching data from the server, and it was easy for people and agents to pick the wrong one. We removed one, and a lint rule now fails whenever anyone imports it again. An instruction saying “use the other library” would have been followed, most of the time. The lint rule can't be talked around.
The same idea at a smaller scale: in CVing's WhatsApp agent I moved the security checks out of the prompt and into the code that performs each action (the details). Whatever must always hold belongs where the model can't interpret it.
If the agent reviews worse than you, look at the codebase first
Theo's hot take, and mine: most agents now review code better than most people, and if yours doesn't on your repo, start from the repo. Boris Cherny says it from the other side: code that's hard to check makes a codebase that's hard to work in.
The test I use is Theo's. Picture a very smart new hire who has worked in thousands of codebases and never in yours, and who will do tedious work all day without complaining. Whatever trips that person up will trip the agent too, and the fix is the same for both: clearer boundaries, names that say what things do, one obvious way to do each thing.
This holds for frontier models with a real token budget. If you've got the small model or a plan with rationed tokens, the model really is the limit, and everyone gets a pass for that. I said so when I corrected an older piece of mine.
The same reasoning applies to writing code. If you think your value is writing better code than Opus, you're measuring the wrong job. Mine is architecture, constraints and acceptance criteria, and deciding what shouldn't be built at all.
Instructions change when the project changes
Theo showed a number I liked: his repo's instructions for agents change about once a day, while the chat component changes thirty to fifty times a day. The last change to the instructions came because the repo had moved to a new setup. That's a healthy rhythm: the instructions describe the project, and the code prevents the mistakes.
When code-os, the open source framework we use at Yempik, moved to its second version, we removed our own duplicated rules. Every duplicate is one more ambiguity, paid for in context every session.
The objection: so instruction files are useless
They're useful, and they should be short. Anthropic's advice on REVIEW.md is good, and I follow it: the owners of a part of the code write what failure looks like there (for documentation, that it lies; for configuration, that it misroutes), cap the nits, list the paths to skip, and ask for a file and a line as evidence. That's knowledge the code can't express on its own. The mistake is using them to patch code that invites the error.
From Monday
- After every repeated agent mistake, ask first what in the code invited it.
- Make the mistake impossible where you can: types, a build that fails, a removed dependency with a fence.
- Then a check: a lint rule, a test, a hook in the harness.
- Only then a line in the instructions, and keep the file short.
- Use the smart new hire as the test for your codebase.
- Update the instructions when the project changes.
// the capitalised rule is still in my instructions. the hook that replaces it is next on the list.