Agent Instruction Files Are Source Code: Versioning AGENTS.md and CLAUDE.md Like Config

There is a file in your repository that gets executed more often than your CI pipeline, modifies the behavior of every engineer's tooling, and has never once been reviewed. It has no tests. It has no owner. Three people have appended contradictory rules to it over the past six months, and nobody has read it top to bottom since April. It's called AGENTS.md, or CLAUDE.md, and if your team uses coding agents, it is quietly shaping every line of generated code you ship.

We version-control Terraform. We review nginx config changes. We have a change advisory process for feature flags. Then we let an intern append "always use tabs" to the one file that steers an autonomous system with write access to the codebase, and we merge it without a second look.

Instruction files earned the config treatment the moment agents started reading them on every run. Most teams haven't caught up.

The file that runs on every task

A quick alignment on what these files do, because the mechanics explain why the versioning discipline matters.

AGENTS.md is the cross-tool standard: a plain Markdown file at the repo root that coding agents read before doing anything else. It emerged from a merger of competing conventions (Codex's original format, Cursor's rules, various .clinerules dialects) and is now supported by more than 30 tools. Tessl's writeup on the standard's rise frames it well: one file, read by everything, replacing a mess of per-vendor formats.

CLAUDE.md is Claude Code's version of the same idea, with more machinery. Per the Claude Code memory documentation, it supports hierarchical loading (enterprise, project, user levels), imports via @path/to/file syntax, and per-directory files that load when the agent works in a subtree. A common pattern now is a one-line CLAUDE.md that just imports AGENTS.md, plus any Claude-specific additions.

The property that matters for this article: these files are injected into context on every single run. Not when someone chooses to read them. Not when onboarding. Every run, every task, every background agent, every CI-triggered fix. That is the defining characteristic of configuration, and it has two consequences:

1. A good line pays dividends on every task in the repo, forever.
2. A bad, stale, or contradictory line degrades every task in the repo, silently.

Documentation that's wrong wastes the time of whoever reads it. Config that's wrong breaks production. Instruction files are the second thing wearing the costume of the first.

Why instruction files rot faster than code

Code has a property that keeps it honest: when it's wrong, something fails. A test breaks, a type check fails, an exception fires in production. Instruction files have no equivalent feedback loop. When a line in AGENTS.md is stale, the agent just... behaves slightly worse, on some tasks, some of the time, in ways nobody attributes to the file.

The rot follows a predictable pattern. We've seen versions of this across teams, so here's a composite example of a nine-month-old CLAUDE.md:

• Line 12 says "use yarn," but the repo migrated to pnpm in Q2. The agent now runs yarn install, gets a lockfile error, and burns three turns recovering. On every task.
• Line 40 says "never modify files in src/legacy/," added during a migration that finished months ago. The agent now refuses to fix a real bug there and routes around it with a shim.
• Lines 55 and 78 give contradictory test commands, added by two engineers who never read each other's sections. The agent picks one nondeterministically.
• A 60-line "deployment runbook" section, pasted in during an incident, consumes context on every task including one-line typo fixes.

None of this shows up in metrics anywhere. The Augment Code guide to building AGENTS.md makes the point that agents follow instructions literally and don't apply the human judgment of "oh, that section is obviously outdated." Humans skim stale docs and discount them. Agents obey them.

This is also why the problem is getting worse rather than better. When one engineer ran one agent interactively, they'd notice weird behavior and correct it in the session. With background agents, scheduled agents, and CI-triggered agents multiplying (we've written about this shift in the 8 levels of agentic engineering), nobody is watching most runs. A stale instruction file becomes a defect injected into every one of them, and the only symptom is a vague sense that "the agent got worse lately."

The counter-intuitive part, borne out by nearly every practitioner writeup on the topic: deleting lines improves behavior more often than adding them. Teams treat instruction files as append-only, adding a rule every time the agent does something annoying. But every line competes for the model's attention on every task, including the 95% of tasks where that line is irrelevant. Tembo's guide to writing AGENTS.md is blunt about this: keep it minimal, high-signal, and current, because a bloated file dilutes the instructions that matter. Ryan Peterman's reflection on 120,000 lines of agent-written code lands in the same place from the other direction: the constraint on agent output quality was context quality, and curating what the agent sees was the highest-return work.

Ownership and review: the boring fix that works

The fix for rot is unglamorous and you already know how to do it, because it's the same fix you applied to infrastructure config a decade ago.

Assign an owner. Add the instruction files to CODEOWNERS. One person or one small group approves changes. This sounds bureaucratic for a Markdown file until you remember the file modifies the behavior of a system with write access to your codebase. The owner's job isn't gatekeeping style; it's preventing the two failure modes that unowned files always develop: contradiction (two rules that conflict) and accretion (rules nobody can explain anymore).

Review edits like code, and review for a specific set of defects. Standard code review instincts undershoot here because the file looks like prose. What reviewers should check:

That last question deserves emphasis. Long procedures (release processes, migration guides, debugging runbooks) don't belong in the always-loaded file. They belong in separately loaded modules that the agent pulls in when the task calls for them, a pattern we covered in Agent Skills Over Prompts. The instruction file should hold constraints and pointers, not procedures. Atlan's guide to writing AGENTS.md recommends the same split: a lean root file, with detail pushed to nested files that load per-directory.

Schedule drift checks. Instruction files reference a moving target (your codebase), so schedule a quarterly audit plus a triggered one after any large refactor, toolchain migration, or directory restructure. The audit is 30 minutes: read the file top to bottom, verify every command still runs, every path still exists, every rule still reflects a real policy. Some teams automate part of this with a CI job that greps the instruction file for file paths and package commands and fails if they're dead. Crude, and it catches the most embarrassing category of rot for nearly free.

Keep the file in git, and only in git. Local overrides and uncommitted personal variants are the agent equivalent of SSH-ing into a box and editing config by hand. Claude Code supports user-level memory for genuine personal preferences; repo behavior belongs in the repo, where its history is inspectable. When agent behavior changes mysteriously, git log -p CLAUDE.md should be a complete answer to "what changed."

Regression tests for a file with no test suite

Ownership and review catch defects a human can spot by reading. They don't catch the harder problem: an edit that looks reasonable and degrades behavior anyway. Instruction tuning has the same property as prompt engineering generally, which is that plausible-sounding changes routinely make things worse. The only defense is measurement.

You don't need an eval platform for this. You need a fixed task set:

1. Pick 5-10 representative tasks from your repo's history. Real ones: a bug fix in the gnarly module, a small feature touching three files, a test-writing task, a refactor. Include at least one task where the agent historically misbehaved, because that misbehavior is probably why someone edited the instruction file in the first place.
2. Record known-good outcomes. For each task, what does success look like? Tests pass, diff touches only expected files, no forbidden directories modified, correct package manager invoked. These are checkable assertions, not vibes.
3. Rerun the set after significant instruction edits. Fresh sessions, same tasks, before and after the change. Compare pass rates and, more importantly, failure modes. Did the new "always write integration tests" rule cause the agent to bolt useless tests onto a one-line typo fix?
4. Gate the merge on the result. Not automatically at first; a human looks at the before/after and decides. Automation can come later if the volume justifies it.

Is this expensive? Ten agent runs cost a few dollars and half an hour of wall time. An instruction regression that silently degrades hundreds of background agent runs over a quarter costs a great deal more, and you'll never get a clean attribution for it after the fact. Morph's AGENTS.md spec guide recommends treating the file's effect on agent output as the thing you evaluate, rather than the file's prose quality, which is exactly the shift: you're not reviewing writing, you're testing config against a workload.

This is the same argument we made about harnesses in Stop Writing Code, Start Writing Harnesses: once the agent is doing the work, your engineering effort moves to the scaffolding that shapes the work, and scaffolding without tests is scaffolding you can't safely change.

A versioning policy you can adopt this week

Pulling it together into something concrete enough to put in front of a team:

• Layout: AGENTS.md at the root holds the shared, vendor-neutral instructions. CLAUDE.md imports it and adds only Claude-specific configuration. Per-directory files for subtrees with genuinely different rules (the frontend and the data pipeline probably shouldn't share test commands).
• Size budget: Root file under ~150 lines. Anything longer gets split into on-demand modules. Enforce it in review like you'd enforce a function-length lint.
• Ownership: CODEOWNERS entry, one approver group, no direct pushes to instruction files on the main branch.
• Change hygiene: Every edit gets a commit message explaining why, same as code. "Add rule about migrations" is a bad message; "Agent kept editing generated migration files in PR #482, forbid writes to db/migrations/" is a good one. Six months from now, that reasoning is the difference between a rule someone can confidently delete and folklore nobody dares touch.
• Drift audit: Quarterly, plus after any refactor that moves directories or changes the toolchain. Verify commands, paths, and policies against reality.
• Regression check: Fixed task set of 5-10 tasks, rerun on significant edits, human compares outcomes before merge.

None of this is novel process. It's the standard treatment for production configuration, applied to a file category that most teams still mentally file under "docs." The teams getting consistent results from coding agents in 2026 are, almost without exception, the teams that made this reclassification early.

Where this fits in an agent operations practice

Instruction file discipline is one slice of a larger problem: coding agents are production systems now, and most organizations run them with none of the operational scaffolding they'd demand from any other production system. No ownership, no change control, no regression checks, no drift detection.

This is the layer where OpenNash spends most of its time on agent engagements. Building the first agent is rarely the hard part; making its behavior stable, auditable, and improvable over months is. For coding-agent adoption specifically, that means setting up the instruction file hierarchy, the review gates, and the fixed-task regression harness so that the config steering your agents is as trustworthy as the config steering your infrastructure. Clients own all of it after handoff: the files, the task sets, the audit checklist, and the reasoning behind every rule.

If your team already has agents running against real repos, start with the cheapest diagnostic available: open your AGENTS.md or CLAUDE.md right now and check three things. Does every command in it still run? Do any two lines contradict each other? Can anyone on the team explain why each rule exists? If you get through all three clean, you're ahead of most of the industry. If you don't, you've just found free performance sitting in a Markdown file, and git blame will tell you exactly where the folklore came from. For teams that want a second set of eyes on their agent configuration and the regression harness to keep it honest, OpenNash runs instruction-file audits as part of its agent operations work: book a call and bring the file.