Prompting Does Not Survive a Real Codebase

A coding agent does not fail on your codebase because you phrased the request badly. It fails for structural reasons, and better wording will not reach them.

That is the premise of this series, and it took me a while to accept it. My first instinct with a misbehaving agent was always the same: rewrite the prompt. Add a constraint. Say it more firmly. It works on a toy repository. It stops working the moment the codebase is big enough that the agent cannot hold it in view, old enough to contradict itself, and load-bearing enough that a confident wrong edit costs a day.

TL;DR

• Prompting is a per-request act. A real codebase imposes standing problems: finite attention, stale rules, ambiguous domain words, work too big for one step. Those do not respond to rephrasing.
• What fixes them is the machine around the model: what it reads, what it is allowed to do, what gets checked before its output counts. That machine is the harness, and it is the unit of engineering.
• This series takes one mechanism per post. One problem it solves, one recipe you can run. No vibes.

The failure is structural

Watch what actually goes wrong and a pattern shows up fast. The agent repeats work it already did. It forgets a constraint you stated forty messages ago. It reads Member as an ordinary English word instead of the specific thing it means in your system. It follows a rule in a file that stopped being true in March.

None of those are phrasing failures. They are properties of the situation. The window is finite and the model rereads all of it on every step, so a fuller window is a worse one. The rules you wrote drift out of date because nothing forces them to keep up. Your domain vocabulary is precise and undocumented, so the model substitutes the generic meaning and proceeds with total confidence.

You cannot prompt your way out of any of that. You can only change the conditions the model works under.

The harness is the unit

A woodworker who needs the same cut a hundred times does not practice holding the saw steadier. They build a jig. The jig is not a hack around a lack of skill. It is what makes skill repeatable, and it is a real piece of engineering in its own right.

The harness is that jig. It is everything that is not the model: what goes into the window, what the agent is permitted to touch, what runs before its work counts as done, what happens when it gets something wrong. The model is fixed. The machine around it is entirely yours, and it sets the ceiling on what that model can reliably do for you.

This is where I part company with most agent writing. The industry keeps selling autonomy: give the agent more freedom and it will do more for you. My experience runs the other way. Reliability comes from structure that a human designed on purpose. The agent is a component inside it, not the thing in charge.

Start here

Three pieces define the vocabulary the rest of the series leans on. They are short and they stand alone.

• What a context window actually is (and what it costs) covers the mechanism underneath everything else: why the window is finite, why a longer one costs more than linearly, and why capacity is not reliability.
• Context engineering is the content side. Deciding which tokens the model sees on every step of a task, which is a judgment discipline, not a prompt trick.
• Harness engineering is the machine side. The loop, the tools, the guardrails, the sub-agents, and why engineering that machine measurably outperforms swapping the model.

Then the first mechanism: the bigger the window, the quieter the rot. Why a larger context window raised the ceiling on what an agent can attempt without ever buying immunity from junk tokens, and the habits that keep a working context lean on purpose.

Where this goes

The series runs in three arcs, each one a different kind of control.

The first is the context you author: everything you decide before the agent runs. Keeping the window lean, grounding your domain vocabulary so the model stops guessing, keeping standing rules honest as the code moves, and encoding architecture as something enforced rather than described.

The second is the context you enforce: correctness and safety while it runs. Turning a fuzzy ask into a typed spec the agent executes, growing custom lint rules that harden over time, drawing permission boundaries, isolating work so parallel agents cannot collide, and debugging from observation instead of guesswork.

The third is portability and operating cost: measuring what you actually spend, routing each task to the cheapest model that can do it, writing configuration that is not welded to one vendor, and putting a real number on the energy behind it all.

Every post is narrow and operable. One mechanism, the problem it solves, and something you can run. I will publish the things that broke alongside the things that worked, because the failures are where the design decisions actually live.