When a coding agent does something you didn't ask for, like when it edits a file it was told to leave alone, runs a command the wrong way, or wanders off into an architecture nobody requested, the reflex is almost universal. You open your CLAUDE.md and add a line. You make it firmer. You put the important part in capitals. You explain, one more time, why the rule matters. And when the agent ignores it anyway, you say it a third time, LOUDER.
We spent a recent stretch of work testing whether that reflex actually pays off, and the short version is that it mostly doesn't. The leverage in agentic development is not in writing longer instructions. It is in shaping the environment the agent works in and the way you talk to it. Instructions are a weak, probabilistic control surface. The environment can be a deterministic one. If you are building anything real with coding agents day to day, that distinction is everything.
We measured a heavy framework against no framework at all
The clearest evidence came from a comparison we didn't set out looking for. On one project, the client had built a very large framework for managing the agentic workflow. It included a spec-driven system running to roughly 60,000 lines of markdown instructions spread across many files, stitched together with supporting TypeScript. The premise was the intuitive one: give the agent enough structure and enough guidance and repeat yourself enough times and, fingers crossed, it will behave.
We put it on the bench against everyone’s favourite baseline; plain Claude Code with no framework at all. The task was a straightforward improvement, a file-upload progress bar, and then a second, harder case that involved an actual architectural change. Each configuration was run several times, because the same prompt does not produce the same output twice with an LLM, and a single run tells you almost nothing.
The most instructive part of the exercise turned out to be the setup, not the result: the hardest and slowest step was defining the criteria for judging the output. That is worth sitting with, because it is also the advice. You cannot know whether your scaffolding is helping until you can measure the quality of what comes out the other end, and most teams never build that measurement. They add framework and feel more in control without ever checking.
When we did check, the heavy framework did not earn its weight. In our testing on these cases, the output quality was broadly similar to the no-framework baseline against the criteria we'd defined. The framework tended to reach for a bigger, more ambitious approach, but bigger was not better, at least not in any noticeable way. What it reliably was, was more expensive: in these runs it came out several times slower, consumed several times more tokens, and produced several times more code to review, for a result that wasn't meaningfully improved. On the harder architectural case, the picture was no kinder. Both approaches failed CI on the first pass, both introduced a security issue, and the heavy framework still needed human supervision and review after all, while costing roughly twice the tokens. The thing that was supposed to run autonomously did not, expensively.
These are findings from a handful of cases, not a law of AI nature (paradox?), and we'd frame them that way to anyone. But the direction was consistent enough to change how we work.
Why more instructions tend to backfire
It helps to understand why the heavy approach underperforms, because the failure mode is baked into the method. The framework had grown to 60,000 lines through a very human process: whenever the agent didn't follow a rule, the author restated the rule more forcefully, and when that didn't work, added it again somewhere else. The end state was the same instruction repeated multiple times across overlapping files, on the theory that an agent that sees a rule a few times is more likely to obey it.
The trouble is that prose instructions are a probabilistic control surface. A well-phrased, emphatic, capitalized instruction moves the odds that the model complies, but it does not guarantee it. We saw this directly on a smaller scale: a source-of-truth interface file that the agent was told, in plain language and several rephrasings, never to edit. With careful wording, the agent respected it about half the time. Half. Half is not a control mechanism. And every additional line spent shouting the rule is context you've spent which, past a point, makes the agent worse at the thing you care about.
So the question stops being "how do I word this better" and becomes "how do I build a setup where the wrong move isn't even available." That splits into two moves: fix how you interact, and fix the environment.
You should make it a dialogue, not a dictation
The first cheap win costs no framework at all. Most people prompt an agent the way you'd file a ticket; one-way, here's what I want, go. But a one-way prompt forces the agent to fill every gap with an assumption, and its assumptions are where things go wrong.
The fix is to make the interaction two-way. Instruct the agent to ask when something is unclear, and especially to ask before making any decision that touches business behavior or anything a user will see. In practice, this alone removes most of the cases where an agent confidently builds the wrong feature.
A few things make this smoother. Have the agent ask its questions all at once rather than one at a time (a slow back-and-forth is a big part of why people abandon the approach) and then re-ask on anything still ambiguous after your first answers, until it's satisfied. Watch out with this approach; batching makes it easy to miss the important questions hiding under a haystack of trivial ones, so tell the agent to prioritize the decisions that actually change outcomes. One tip that’ll speed things up is to have it pose questions as single- or multi-select choices, so you don’t have to type out every decision. Lean toward lightweight questioning tools over heavy ones; the same "interview me before you build" behavior can be had from a short, adaptable skill that costs a fraction of the context. And ask the agent to summarize the decisions it's collected as a compact table before it starts writing. A table you can scan is far easier to review and correct than a page of generated specification.
The environment should build guardrails, not sermons
The second move is the one that changes everything, and the sharpest way to see it is an experiment we ran on our own tooling. We took a working agentic workflow, stripped almost all the procedural instructions out of it, and ran it anyway.
The agent still followed the process. Not because it remembered, but because it kept bumping into guardrails and reading the error messages they returned. It tried to finish early; a guardrail said the workflow isn't complete, keep going. It tried to skip a required step; a guardrail sent it back. The agent discovered the process by bumping into the guardrails. That is a very different design philosophy from writing a longer prompt, and it is a far more reliable one.
The mechanism underneath is why it works. These guardrails were implemented as hooks, checks that run at the harness level, below the model, on the tool call itself. That placement is the entire point. When an instruction in a prompt is violated, the model decides whether to care. When a hook denies a tool call, there is no negotiation, and nothing goes back to the model to reconsider; the action simply does not happen. Deterministic beats probabilistic, every time it matters.
Two details from building these turned out to matter more than expected. The first: always give the guardrail a reason. A bare block like "editing this file is denied"just tells the agent to get creative, and a creative agent has many ways to edit a file. Block a protected file with no explanation, and it'll try to route around you. Block it with the reason stated, and the agent understands why the wall is there and stops trying to climb it. As one of our engineers put it: it's intelligence; give it the reasons, and it's far more likely to comply.
The second: you can't list all the workarounds in advance, because the agent finds more of them than you'd guess. Trying to pin it to one way of running our tests, we counted sixteen distinct invocations it reached for (with and without the wrapper we wanted), with redirection, against single files, in every combination. No prompt expresses all sixteen. A hook that allows the one approved invocation and denies everything else covers them all, including the seventeenth you haven't seen yet. That's the real advantage of a guardrail over a rule: it defends against the workarounds you didn't anticipate, which is exactly the set prose can't reach.
The takeaway, and where you can start
The clean rule that falls out of all this: use instructions for what the model cannot know. Use guardrails for what the model must not do. Use dialogue for what you haven't decided yet. Match the mechanism to the problem, and stop trying to make one prose prompt do all three jobs.
If you want a concrete place to start, the permissions layer is the easiest and highest-return piece to adopt: a small set of hooks that deny the edits and commands you want off the table and hand the agent a reason each time. My personal implementation of that idea is published and usable 
. The broader phase-tracking framework is still an experiment rather than a shipped tool, and we'd treat it as one.
None of this is about a clever agent. It's about the ordinary engineering discipline of building a system where the right thing is the easy thing and the wrong thing isn't even reachable. That discipline is old. It's just newly pointed at a model instead of a junior developer, and it works far better than talking LOUDER.
