Instruction files are code
Ada (VP Engineering)
- ai-transformation
- running-the-initiative
- gated-agents
- engineering
- code-review
- playbook
Instruction files are code
If a file can change what your agents do next, it is production code. It doesn't matter that the file is written in English.
I mean the instruction files sitting in repositories: AGENTS.md, CLAUDE.md, .cursor/rules, project rule packs, and system prompts checked in next to the code. Teams treat them like README notes — edited in place, rarely reviewed, almost never tested. Agents treat them as authoritative. That gap is where behavior drifts.
AI agents draft most of the code changes to our own site, so a lot of my time goes to review and to the files that tell those agents how to work. When the team is mostly agents, the human job shifts toward guidance, decisions, and quality control. The instruction file is where that guidance gets written down. If it is sloppy, every later task inherits the slop.
They are not documentation
A README explains the project to a person who can ignore it. An instruction file is loaded into the agent's context and used as operating policy. Change a paragraph about how to open a pull request, what the agent may never do, or which checks have to pass, and you have changed the system. The next task will follow the new text, not the old habit you thought you still had.
That is why a quiet edit is risky. Someone adds "be more helpful," pastes a long vendor template over a short working file, or deletes a constraint that was blocking a demo. None of those look like a production incident. They show up later as agents skipping a gate, opening oversized pull requests, or doing work you never asked for — after the file has already steered a dozen tasks.
How I ask people to write them
The same four principles we use when we brief an agent apply to the standing files that brief every agent.
Think before you write. Don't assume the agent knows a constraint you left unsaid. If two readings are possible, the agent will pick one, and you won't be in the room. State the assumption. Name the tradeoff. Write the "never" list as carefully as the "do" list.
Simplicity first. A short, structured file beats a long one that tries to cover every case. One page an operator can audit is better than a novel nobody rereads. Extra prose is extra surface for conflict and for silent override.
Surgical changes. When you need a new rule, add that rule. Don't rewrite the whole file to "clean it up" in the same pull request. Adjacent edits make review harder and rollback messier. Every changed line should trace to the request in front of you.
Goal-driven. Every standing instruction should point at something you can check. "Be careful with secrets" is a hope. "Never print environment variables, tokens, or .env files, and if a task needs a secret, stop and ask" is a rule you can grade. If you can't describe what done looks like, you aren't ready to encode it.
Those principles also describe a good brief: a goal, the context the agent actually needs, the constraints it may not cross, and a success check someone else could run without you. The standing instruction file is the brief you don't want to retype every time. Give it the same shape.
Five things code already gets
If the file is code, it should get the habits code already has.
Version it. Keep instruction files in the same repository as the system they steer, not in a personal chat or a wiki page anyone can overwrite. History is how you answer "what did the agent think it was supposed to do last Tuesday?"
Review it in a pull request. A change to AGENTS.md or a system prompt should not go straight to the default branch. It needs a diff someone can read, checks, and a human approval. I wrote earlier about why that approval belongs in config, not a promise. The same gate applies here: the reviewer should ask what will be different tomorrow, not just whether the prose sounds right.
Test it against a golden set before you change it. Virginia has already described the habit: ten to fifty examples of correct, wrong, and never-ship, run before every prompt or tool change. An instruction file is a prompt. Run the set after an edit and look for two outcomes: the new rule takes effect where it should, and nothing else quietly breaks. If you don't have a set yet, write the examples first — including one case the current file must never violate — before you rewrite the file.
Name an owner. Someone has to be accountable for the file the way a code owner is accountable for a service. That person reviews changes, explains why a rule exists, and decides what to delete. A file with six informal authors and no owner accumulates contradictory advice, and agents will follow the wrong paragraph when two of them disagree.
Keep a rollback path. Because the file lives in version control, rollback is an ordinary revert. Practice it once: if a change makes the golden set worse, revert the file, rerun the set, and only then discuss a smaller edit. Teams that can't roll an instruction file back will "fix forward" under pressure, which is how a bad paragraph becomes a worse chapter.
Review and tests make a bad edit harder to ship. They don't make the file wise. That is still a person's job: deciding what the agent is for, what it may never do, and whether a new rule earns its place.
If you run agents, try this on Monday
- Inventory the files that already steer your agents.
AGENTS.md,CLAUDE.md, editor rule files, checked-in system prompts, and any template pasted into every new task. If a file can change behavior and it isn't in the repo, put it there. - Name an owner for each one. One person, with a backup. Write the name in the file.
- Require a pull request for changes. No direct edits on the default branch. The reviewer should be able to say what behavior will change.
- Attach the golden set to those changes. No instruction-file change goes out until the set runs. If you don't have a set, write ten cases before the next edit.
- Make rollback boring. Confirm you can revert the last change and that the previous version is the one the agents will see.
- Cut before you add. Read the file as if you were briefing a new teammate. Delete advice that conflicts, that you can't check, or that you no longer mean. A shorter file is easier to review and harder to misunderstand.
The human work doesn't go away when agents write most of the code. It moves into the guidance, the decisions, and the quality control. Instruction files are how that guidance persists. Treat them like any other file that can change production.
Get the playbook
Phase 2 of the 231 Labs AI Transformation Playbook, Gated Agents, covers drawing the gate, the golden set you run before a prompt change, and the failure modes that show up when either one is missing. It's free at 231labs.com/playbook.