Your Codebase Is the Biggest Prompt
Agents copy whatever your codebase already does. Every correction you give one should become a lint rule, a type, or a better API, not another line in a rules file.
I spend a lot of time writing instructions for coding agents. My repos have a CLAUDE.md with a pre-commit checklist in capital letters, a rule about which scratch paths a session may write to, and a list of words my writing tools are never allowed to use. All of it is prose, and all of it is the weakest tool I have.
An agent writes code based on what it reads. The rules file is a few hundred lines. The codebase is a few hundred thousand. When the two disagree, the codebase wins, because the agent's job is to make the new code look like the code around it.
So the place to spend effort is the code itself.
Agents copy the established pattern
When a person joins a team, they learn which parts of the codebase are the good parts. Somebody tells them to ignore the old billing module and copy the new one. An agent has nobody to tell it that, and it starts fresh every session.
It looks for the established pattern and repeats it. If the workaround from last spring appears in eleven files, the workaround is the established pattern. A deprecated helper that still has callers looks just as valid as its replacement. A setTimeout someone used to paper over a race condition becomes the way this codebase handles timing, and the next agent adds three more.
This used to be survivable because code arrived slowly. A few pull requests a day, a reviewer who remembered why the weird thing was weird. Now one engineer can have dozens of agents producing code at once. Bad patterns spread at the same speed as good ones, and they spread before anyone reviews them.
I think of the codebase as a garden. Weeds you leave alone don't stay put. They seed.
Turn every correction into a check
Here is the rule I try to hold myself to: when I correct an agent, I ask whether that correction can live in code instead of in prose.
Prose is a request. A lint rule is a fact. If I write "never import server code into client components" in a rules file, the agent will follow it most of the time. If a lint rule fails the build when it happens, the agent follows it every time, and so does the next agent, and so do I.
The order I reach for things:
- API design and architecture. Make the wrong thing impossible to express. If there's no function that does the dangerous thing, nobody calls it.
- Lint rules, types, and compilers. Make the wrong thing fail fast, with an error message that says what to do instead.
- Tests and verification. Check the behavior you care about, including the parts no type can describe.
- Prose. Rules files and skills, for the things that need judgment.
Most teams build this pyramid upside down. They start with a long rules file because it's the fastest thing to write, and they never get around to the checks.
Ban the things that need nuance
Some APIs are fine in skilled hands and a mess everywhere else. React's useEffect is the classic example. It has real uses, and it's misused far more often than it's used well. Agents are not good at nuance. They see an effect somewhere in the codebase and reach for it to sync state that should have been derived.
You can write a paragraph explaining when an effect is appropriate. Or you can ban it in product code with a lint rule, allow it only inside a few framework-level hooks you wrote carefully, and never discuss it in code review again. The second option removes a whole category of bug.
The same move works for anything that requires judgment to use safely. Raw SQL strings, direct fetch calls that skip your auth wrapper, date math without a timezone. Wrap them once, ban the raw version, and the lint error points to the wrapper.
Put the boundary in the directory structure
Some mistakes are about where code lives. In a desktop app, importing main-process code into the renderer causes long tasks and jank. In Next.js, importing a server-only module into a client component either breaks the build or leaks something you didn't mean to ship.
You can explain this in prose, or you can make it structural. Two top-level directories with obvious names, and a dependency rule that forbids imports across them. The agent sees the directory name, the lint rule catches the exception, and the boundary holds without anyone thinking about it.
Directory names are context the agent reads on every file it opens. That makes them more reliable than a rules file it may or may not load.
Comments are an escape hatch
This one surprised me. Agents use comments to justify not doing the right thing.
Ask an agent to fix a flicker and it may wrap the update in a requestAnimationFrame, then write a comment explaining why that was necessary. The comment makes the workaround look deliberate. The next agent reads it, concludes this is how the codebase handles flicker, and adds another one. A few weeks later there are timers everywhere and the app is slow, and every one of them has a comment saying it was justified.
Comments also go stale, and nothing enforces them. "Don't call this from the render path" is a wish. A lint rule that fails when you call it from the render path is a guarantee.
I've moved toward very few comments and lint errors that explain the root cause. When an agent hits the rule, the error message tells it what the real fix is. That's the right moment to deliver the instruction: at the exact point it matters, and only then.
Clean up what's already there
A new lint rule stops new occurrences. The old ones are still in the codebase, still the established pattern, still getting copied. So every rule comes with a cleanup: fix the existing violations, or at least list them so they can't grow.
This is the kind of work that used to be too expensive to bother with. Migrating two hundred call sites to a new wrapper was a quarter-long project nobody wanted. An agent will do it in an afternoon, and it does it well, because the target pattern is now clear and the lint rule tells it when it's done.
What you get back
Each correction that becomes a check is one less thing to look for in review. Do that enough times and review gets short. You stop reading diffs for the same ten mistakes because those mistakes can't land anymore.
That's the point where agents can start merging their own pull requests, and I think it's the only safe route there. Trust comes from the environment the agent works in, and you build that environment one rule at a time.