Specs and instruction files feel like a safety net. But pile on too many and the agent gets confused rather than sharper. So what’s the actual source of truth?
There’s a reflex that every team adopting coding agents develops: when the agent gets something wrong, add more context. Write a spec. Add a rule to the instructions file. Tell it to go read the relevant docs before it starts. The assumption is that more guidance means better output.
Not always. We’ve been running enough features through agents to see the other edge of this, and it’s counterintuitive: past a certain point, more context makes the agent worse.
When specs start lying to the agent #
We have a set of spec files in our cloud repo that describe how various systems are supposed to behave. For genuinely complex work — billing, a gateway with a lot of surface area — they’ve been lifesavers, especially for reviewers trying to make sense of a large change.
But something breaks when the agent pulls in three or four of them at once. It starts treating a detail from one spec as a fact about another. It over-anchors on things it half-read. It confidently tells you “this is how it should be,” and when you push back and ask why, it admits it conflated two documents. You end up needing far more runs to get to the state you actually wanted.
Part of the problem is that the specs drifted. The original intent was that a spec describes outcomes and behavior — what should be true, not how to build it. Over time they picked up implementation detail and grew. One of ours ballooned to well over a hundred bullet points of rules, written in such precise, lawyerly RFC-style language (”the upstream payment provider” instead of just naming the thing) that it reads like a unit test written by an attorney. A human can barely parse it. An agent takes every clause as gospel — including the clauses that are now subtly wrong.
The question underneath the specs #
Strip away the tactics and the harder question is this: what is the source of truth?
Agents are non-deterministic. You tell one to implement something and it will, but that doesn’t tell you what should be true. So where does that live?
Is it the tests? The agents write those now, and they’re very motivated to make them pass. That’s not the same as the tests being correct.
Is it the code? The code is what
istrue, not necessarily what was supposed to be true. An agent reading the codebase will infer intent from the current implementation, bugs and all.Is it the specs? Only if they’re maintained, unambiguous, and someone actually keeps them evergreen. Ours weren’t, reliably.
Is it in someone’s head? That person goes on vacation, or the feature was built three weeks ago and the details are already gone.
This isn’t academic. Months later — sometimes only weeks later — you land in a corner of the codebase and need to know: how is this supposed to work? What was the business outcome? Was it implemented correctly? Without a source of truth you can point at, you’re guessing, and so is the agent.
Two kinds of truth #
The most useful framing we’ve landed on splits it in two.
There’s how the software is — and the honest source of truth for that is executable: the code and the tests. You can’t write “this is the best plugin in the world” in a prompt and make it true. Behavior is verified by running it.
And there’s how you want the software to be — the goals, the direction, the architectural constraints. That’s the part you set, and it can’t be reverse-engineered from the current code, because the whole point is that you often want the new thing to not look like the legacy thing.
Conflating those two is where a lot of agent pain comes from. If your instructions contradict each other, or describe the current state when you meant to describe the target state, the agent walks confidently in the wrong direction.
Less instruction, more intent #
The most surprising trend runs the other way. Look at the system prompts and harnesses shipping from the frontier labs, and the trend across model generations is fewer baked-in instructions, not more. They lean on skills and context pulled into the window dynamically, rather than a giant static rulebook.
That points at a fix worth trying:
Cut the standing instructions. If your agents file is aggressively telling the model to go read all the specs before every task, that eagerness works against you. Make context pull-in deliberate and situational.Separate the two truths explicitly. Let code and tests be the source of truth for how thingsare. Use instructions to express where you want to go — the goals and boundaries — not to re-describe the implementation.Enforce direction with structure, not prose. When we’ve migrated architectures with human teams, we didn’t document it exhaustively; we created a new folder or module so it was obvious which pattern was current and which was legacy. Agents need the same clear signal.Keep specs for the genuinely hard stuff. Billing, gateways, anything a reviewer couldn’t hold in their head. Not every component needs one, and a spec per feature is how you get the confusion in the first place.Decide who the spec is for. A document optimized for an agent and a document optimized for a human reader are different artifacts. Pick one on purpose, and know whether your review process expects a human to read and understand a spec change in a PR, or whether that’s the agent’s job.
Where I’m still uneasy #
I’ll admit I feel a little nervous about removing specs entirely. Across multiple sessions, having some reference point you can verify a change against is genuinely valuable — being able to tell an agent “confirm the implementation matches the spec” is a real superpower, and it’s helped when partnering with non-engineers who needed a contract to reason about.
But “valuable sometimes” is not “load all of it, always.” The goal isn’t zero context. It’s the right context, pulled in on purpose, kept honest, and clearly separated into what is true versus what we want to be true. Give the agent that and it stops arguing with itself; give it everything and it won’t.