AGENTS.md and a codebase AI coding agents can work in

In September 2026, one of our products merged more than a hundred pull requests and landed over 450 commits. Much of that code was written by AI coding agents, running in parallel in their own git worktrees, with people reviewing and steering.

That pace only works because the repository is written for its readers, and many of its readers are now agents. Here's what that looks like in practice.

Start with AGENTS.md and written decisions

An agent starts every task with no memory of why the code looks the way it does. Left alone, it will re-derive those decisions, often differently. So the repo carries them explicitly:

CONTEXT.md, a domain glossary. It includes a list of naming traps: terms that sound like one thing and mean another, or tables whose names don't match the concept. Read the traps first.
docs/adr/, numbered architecture decisions with their evidence, their cost, and what they do not buy.
AGENTS.md, which ties it together: where code goes, which guards run, and how to deploy.

None of this is new. What's new is how much it pays off. A person reads the ADRs once. An agent reads them on every task.

One place for each kind of code

Every feature follows the same slice layout:

packages/api/src/modules/<slice>/

lib/<thing>-rules.ts   pure. no queries. the tests live here
lib/<thing>-store.ts   THE ONLY FILE THAT TOUCHES THE DATABASE
lib/<thing>.ts         the interface, composition only
procedures/            one procedure per file, on `authed`

The rule that earned its place the hard way: a surface doesn't write its own query. We once had three implementations of "list the deals I can see," one for the web UI, one for an MCP tool, and one for an API route. They disagreed about columns and sort order, so an agent and the UI looked at the same firm and saw different answers. Now surfaces only project what the module returns.

Guards are ratchets

Four checks run in CI, and each has a self-test that proves it catches a known-bad fixture:

Ungated procedures. An RPC procedure that isn't behind auth is reachable by anyone.
Migration idempotency. DDL has to be safe to run twice.
Direct database access. Queries outside a store file are tracked.
A framework footgun that silently breaks server rendering.

They're ratchets: the count of violations may go down, never up. That matters more with agents than with people, because an agent will happily copy the nearest example, including the bad ones. The ratchet keeps the bad examples from spreading.

"Zero" doesn't mean safe

We also give agents a code graph tool for impact analysis: before editing a function, check its callers. The most important rule we wrote for it isn't about the tool at all:

Agents are very good at taking a clean-looking result and running with it. The guidance has to say explicitly which results are not permission.

The takeaway

Agent-written code is only as good as the repo it's written into. Clear boundaries, recorded decisions, and ratcheting guards were always good practice. With agents doing most of the typing, they stop being nice-to-haves and become the main way you keep a codebase coherent.