What happens when an agent is built to treat the docs as the truth, and a senior developer knows something the docs don't? We got a real answer in one of our regular internal conversations about working with agents. We were talking about design systems, and our colleague and founder, Nick Van Weerdenburg, had just described governing rails: a set of rules, purposes and intent for doing work with agents, which a change to a component connects to first. I said my week had produced a scenario close to that process.
My team has set up our software work like this. People write behavior documents, which say how the system should act. An agent scans them and turns them into issues. Each developer's agent picks up an issue, checks its assumptions, implements the change and opens a pull request, a proposed code change that others review before it merges. A group of other agents reviews it, and it merges to production. We also have a rule that each pull request stays focused on one problem, so anything outside its scope becomes a new issue of its own. If you've used spec-driven development with coding agents, it's the same idea with more agents in each role.
That week, our team lead, a very senior developer, put changes straight into the code instead of going through that route. Their changes did a really cool thing. One of our agents saw that the change wasn't in the behavior documents and filed it as a bug. A separate agent, running on my machine, picked up the bug and reverted the team lead's code so that it matched the docs.
Then that agent stopped and asked me for clarification. I don't remember what gave it pause, but the question drew my attention to the fact that it was undoing our team lead's change. I took the question to the team lead, who confirmed they had implemented new requirements. The agent then updated the bug, reverted its fix, and aligned our behavior guides and tests with the new implementation. The revert was never merged, so it was easy to cancel.
Why a good change looked like a bug
Our flow was built on a sound rule: the behavior documents are the source of truth, and everything is checked against them. That works when every change arrives through the flow. A direct change arrives with no issue, no updated test strategy and no updated behavior document. The agent that filed the bug had only the docs to compare against, and from where it stood a deliberate improvement and a mistake looked the same.
Our team lead made a change they judged correct, the first agent reported a real gap, and the second agent followed its issue. Humans are far more likely to question an instruction to revert a new change. An agent doesn't consider recency or title; it just does its best, in the moment, to make sense of the prompt and provide a reasoned output.
If the most senior people on the team make deliberate changes to the code which violate the behavior, it's the behavior that's poorly defined.
— Ken Easson, Software Architect
Here, the docs were behind: our team lead had implemented new requirements, and our behavior guides and tests hadn't caught up. When a person with deep knowledge changes code on purpose, the docs may be the thing that missed something.
What happens when an agent finds a deliberate change
We're constantly looking to improve how we work alongside agents, and cases like this one are how our practices keep evolving. I shared it with the wider team, and it's now part of an ongoing conversation about how we work. It connects to something we had already been honing: how our agents handle clarifications and "needs decision". The instructions our agents work from set out clear permissions and a process for when they hit a contradiction or a question. An agent can move a ticket into a swim lane called "needs decision", add a comment describing the problem, and assign a developer or QA person who can answer it. On my own machine, I have a scheduled task that watches for new issues and brings them to my attention. The next step I'm looking at is notifications in Slack or other channels.
When the change comes from a senior person, the question should be a quick, friendly check-in. Something like: this change isn't in the test strategy, the behavior documents or an issue yet, so we have nothing to check it against. Was it on purpose? Then the person says yes or no.

After the answer, the agent knows which thing to fix: the code, or the documents that go with it. It reminds me of a design system. If someone changes a border width, the check should catch it and ask, "What should be fixed? Is it the border or is it the design system?" Either answer is reasonable. What matters is that a person with the context gets to give it.
The docs need a way to be corrected too
On my team, people write the documents and agents build from them. That makes those documents the source of truth. But people will still change code directly when they know something the docs don't. If all the flow can do is enforce the docs, it will keep undoing good work. The docs need a way to be corrected too.
The same risk runs the other way. We had already noticed that AI is quick to change tests to match code changes, and that's really dangerous. In this case, the tests were updated only after our team lead confirmed the change. A failing test needs a full review before anyone changes it to pass.
At Rangle we hold to a belief that agents should run only as far as your checks reach. The check that filed the bug asked one question: does the code match the docs? The question that mattered here was whether the docs were right. The risk sits where people and agents hand work to each other, so it matters to decide who answers when the code and the docs disagree. The more time I spend with AI, the more I'm convinced the success or failure of the system is all in the harness.
Who answers is a design choice. You can decide ahead of time which disagreements an agent may settle alone and which go to a person. This is my account of one week, so treat it as a worked example to test on your own flow.
Five quick steps to see how your flow handles a deliberate change
You can test this on a flow you already run, this week, with a harmless change.
- Find out what happens today. Ask your team what the flow does when merged code isn't covered by your specs. Does it file a bug, revert, or ask?
- Add a stop. Give agents a clear way to pause and send the question to a person who can answer it, such as a "needs decision" swim lane, before anything is merged. A simple scheduled check makes sure someone sees it.
- Write the question plainly. This change isn't covered by the docs, test strategy or issues. Was it on purpose?
- Give each answer a next step. If the code is wrong, the agent fixes the code. If it's right, the agent updates the docs and tests.
- Run it once. Make a small direct change, watch what the flow asks, and adjust the wording.








