You've probably had this happen. The agent does something weird, like running npm when the repo moved to pnpm months ago, or putting a new file somewhere nobody's put files in a year. You go looking and find the reason in a rules file nobody's touched since spring. Annoying, but at least you found it.
Now make it a little harder. The change merged three weeks ago and something downstream just broke. You open the rules files and nothing in them explains what the agent did. Maybe someone fixed the rule since. Maybe it was in a developer's local config and never in the repo at all. Maybe it was in the file but past the point where the tool stopped reading.
You can look at the diff. You can probably find the prompt. Some tools will show you what files it read and what commands it ran. What's surprisingly hard to get back is the guidance it was working under at the time.
The agent did what it was told. Figuring out what that was is the hard part.
I've debugged this before, just not with agents
Anyone who has chased an IAM problem at an unreasonable hour knows how this goes. The policy you're staring at is perfectly clear and it's still not the answer. The answer is whatever the effective permissions turn out to be once group membership, inheritance, resource policies and that one exception from last spring all get resolved.
After enough of those nights you stop asking what the config says. You ask what's actually true.
Coding agents have that same problem now. We haven't named it yet.
What's in the repo isn't what the agent got
Every major coding tool reads persistent instructions now, and every one of them resolves those instructions differently. I'm using Codex as the worked example, because its loading rules are the most clearly documented. The shape of the problem is the same everywhere.
Codex builds its instructions by walking from the repo root down to whatever directory it happens to be working in, adding files as it goes. It caps the combined result at 32 KiB by default and stops adding once it hits that. The budget is spent from the root down, so a long root AGENTS.md can crowd out the one sitting in the service folder you are actually working in. It's configurable, but plenty of people don't know the limit exists, and someone filed an issue about it happening silently, noting that Claude Code warns you when your instruction file is too big and Codex doesn't.
That inverts who gets hurt. The team that wrote the most specific guidance, closest to the code it governs, is the team most likely to have it dropped. Nothing fails. Nothing warns. The agent works from the general instructions instead of the specific ones, and the change looks fine.
Some of what shaped a change never lived in the repo at all. A developer with a personal rule in their own editor config, or a global instruction file on their machine, brought that to the work too, and git has no idea.
So "what does our AGENTS.md say" and "what was the agent actually following" end up being two different questions. I've been calling the second one effective instruction state. It's not an industry term and I'm not trying to make one up for sport. I just needed a way to talk about it that wasn't a paragraph long.
Git helps, but not as much as you'd think
The obvious pushback is that we have version control, so just check out the commit.
That tells you what each file said. It doesn't tell you which ones the tool loaded, which one won, what got cut off at the size limit, what came from someone's laptop, or which skill the agent decided to pull in. To rebuild that you'd need the tool, its version, its precedence rules, the working directory, and the developer's local config from that day. You can do it for one change if you really want to. Nobody's doing it for a hundred a week. Git gives you the files. It doesn't give you the effective instruction state.
I'm not saying the instructions caused the output. They didn't. These systems are not deterministic state machines, and GitHub says outright that custom instructions may not be followed the same way every time. But in a postmortem there's a big difference between "the agent made a bad call" and "we told it to do that," and right now that's hard to tell.
Yes, drift. We know.
The stale instructions part is getting attention, and it should. A preliminary study of 356 repos found stale code references in the AI config files of about 23% of them. People are already running that drift check in CI and adding hooks that draft the instruction updates while the diff is still small. If you're not doing any of that yet, start there.
What those tools answer is whether the instructions match the code today. That's useful. It's also not the same thing as knowing what governed a change last month.
I'd push back on some of the common advice though. A lot of it says to put a last reviewed date on the file. Age is a terrible proxy for correctness. An instruction can be fine after six months and wrong the same afternoon you wrote it.
The other thing is that finding a mismatch doesn't tell you which side is wrong. If an instruction says don't touch /generated and someone deleted /generated, maybe the instruction is stale. Or maybe deleting it was the mistake. Detection establishes a mismatch. It does not establish intent. That distinction matters a lot once people start talking about auto fixing instructions when they don't match.
And it goes the other direction too
Most of the checks start from the code. Something moved, so which instructions are now pointing at the wrong thing?
The question I care about more is the reverse. Someone changed an instruction, so where did the guidance just change? If it's a shared skill or an org level rule that thirty repos and six teams pick up, that one edit changed the context for a lot of future work. It doesn't mean every agent will suddenly write different code. It does mean something with real reach just got changed, usually without anyone treating it that way.
In platform work we'd call that blast radius, and nobody would change a shared Terraform module or CI template without thinking about it first. Agent instructions are turning into shared infrastructure too, but most of us still edit them like they're a README.
Where I've landed
The way I've been thinking about it in Ctrl Alt Delegate is discover, resolve, verify, and understand impact. Find all the instructions, including the ones outside the repo. Figure out what actually applies to a given piece of work under a given tool. That resolved view is the effective instruction state. Check what can be checked against the code. Show what a change touches before it lands.
Then hand it to a person. I don't want a system rewriting instructions on its own because it found a mismatch. Anyone who's operated enough automation has seen what happens when remediation runs ahead of understanding.
OpenAI wrote earlier this year about moving off a single big AGENTS.md in their own environment because it got stale, was hard to verify, and ate too much context. They went to a smaller file that works like a table of contents into structured repo docs, with checks around it. That's the maintenance side. Creating context is not the end of the job.
The provenance side is still pretty open. We're getting better at giving agents context and better at watching what they do, but when someone asks what the agent was actually operating under for a specific change, you're mostly left digging through files and guessing.
I'd like that to be a question we can just answer.
