Making your codebase legible to an agent

Every agent harness now reads a file at the root of your repo before it does anything — an AGENTS.md, a CLAUDE.md, a .cursorrules, whatever yours is called. Most teams treat it the way they treat the README: written once, in a hurry, and never trusted again. Then they're surprised when the agent ignores the conventions they thought they'd documented. The file isn't the problem. The problem is that it was written for a reader who doesn't exist. Here's how to write one for the reader you actually have: a fast, capable engineer with zero memory and no instincts about your system, who takes you literally and gets better the moment you give it something it can run.

Who you're writing for

A new senior hire reads your onboarding doc once and then spends three weeks absorbing the unwritten rules — which module is the one nobody touches, why the tests in that folder are slow, what "done" means on this team. An agent gets none of that. It starts every session from the file and the code, and it does not learn between sessions unless you write the lesson down. That changes what the document is for. It isn't a reference someone consults when stuck; it's the whole of the agent's institutional memory, loaded fresh each time. Every sentence has to earn its place, because every sentence costs context the agent could be spending on your code.

It also means the file is a specification for behavior, not a description of the project. "This service handles billing" tells an agent nothing it can act on. "Never write to the invoices table directly — go through BillingService.post() so the ledger stays balanced" is a rule it can follow and you can check.

What belongs in the file

The pattern that works is the same one that works for a one-page spec: say what to do, say what not to do, and point at the thing that proves it. Keep the whole file under a couple of hundred lines. Anything longer gets skimmed, by agents and humans alike.

• How to run it. The exact commands to install, test, lint, and start the thing — the ones that work today, not the ones in the README from two years ago. If there's a Makefile or a task runner, name the targets.
• The one-paragraph map. Where the entry points live, which directories are generated and must not be edited, and where new code of each common kind goes. Paths, not prose.
• Conventions with a reason. "Use the repo's Result type instead of throwing" lands harder with "— the API layer depends on it for status codes." The reason lets the agent generalize to the cases you didn't list.
• The forbidden list. Files, tables, and operations it must never touch without a human in the loop: migrations, secrets, anything that costs money. Short and absolute.
• Definition of done. What a finished change includes here — tests that cover the new path, a changelog line, a note in the PR description. Agents stop when they think they're done. Tell them when that is.

What doesn't belong

Anything the agent can discover faster by reading the code. A list of every module. Architecture history. Aspirations — "we're moving to event sourcing" — that aren't true yet and will send the agent building toward a system that doesn't exist. Style rules a formatter already enforces; if the linter catches it, the file doesn't need to. And politeness: "please try to" is noise. Write rules as rules.

Be especially wary of the paragraph that explains your whole philosophy of software. It feels important to write. It's the first thing the agent discards when the context gets tight, and it displaces the line about the migrations folder that would have saved you a bad afternoon.

Back every rule with something that runs

The gap between "documented" and "followed" closes when the rule has teeth. A convention the agent is supposed to follow should be a lint check, a test, or a pre-commit hook that fails loudly when it isn't. Then the instruction file's job is to explain the failure — "if the boundary check fails, you've imported from the api package into domain; move the type instead" — rather than to prevent it by persuasion. Agents are very good at reading an error message and fixing the thing it names. They are much worse at remembering a sentence from forty turns ago. Put your effort where it works.

This has a useful side effect for the humans. Every time you turn a soft rule into a hard check to keep the agent honest, the codebase gets harder for a tired person to break at six on a Friday, too.

Treat it like code

The file lives in the repo, so review it like the repo. When an agent does something wrong that a human wouldn't have, the fix isn't to sigh and correct it in the chat — that correction evaporates when the session ends. The fix is a line in the file, and ideally a check that would have caught it. Make that a team habit: a PR that corrects an agent's misunderstanding should also update the instructions, the same way a bug fix ships with the test that would have caught the bug.

Prune it on the same schedule. Commands drift, directories move, the thing you forbade in March became the standard in June. A stale instruction is worse than a missing one, because the agent will follow it confidently. Once a month, have someone — or an agent — run every command in the file and walk every path it names. Delete what's dead.

Nested files for big repos

In a monorepo, one file at the root can't hold the rules for twelve services without becoming the long document nobody reads. Most harnesses also look for instruction files in subdirectories and apply the nearest one. Use that: a short root file with the universal rules and the map, then a file per service or package with its own commands, its own conventions, and its own forbidden list. The agent working in the payments directory loads the payments rules and nothing about the mobile app. Context stays small; rules stay specific.

A quick test of whether yours is working

Hand the file and the repo to an agent with a task you've done before and know the right shape of. Don't coach it. If the result follows your conventions, lands tests where you'd put them, and stops at the boundaries you set, the file is doing its job. If it doesn't, you've learned exactly which rule was unclear, uncheckable, or missing — and that's your next commit. Run that test every time the file changes meaningfully. It takes twenty minutes, and it's the only review of the document that counts.

The teams getting real leverage from agents aren't the ones with the cleverest prompts. They're the ones whose repositories explain themselves — in a few hundred lines a machine can act on and a person can keep true. That's a writing skill and an engineering skill at once, and it's one of the more durable things you can get good at right now.