Somebody Finally Wrote Down Why My Coding Agents Keep Failing the Same Way

I read Beyond Code as a PDF in Apple Books, which means the only reason I have any notes on it is that I got annoyed enough last month to make my own plugin dig the highlights out of Apple’s database. So the first thing this book did was justify a weekend I’d already spent.

The second thing it did was produce 113 highlights in the first hundred pages. With this book I was highlighting entire paragraphs because I kept hitting sentences that described something I had personally screwed up and then written a blog post about.

That’s the review, really. But I’ll take the long way there. Fair warning, I’m sixty percent in. Parts I through IV.

• What This Book Isn’t
• The Framing That Should Be on a Poster
• The Chapter That Made Me Go Look at My Own Repo
• What Not to Feed
• Mechanical Gates Over Advisory Review
• The Multi-Agent Thing
• Every Metric in My Pipeline Is Now Suspect
• Where It Loses Me a Little
• Where I Actually Am With It

What This Book Isn’t

The most important thing about this book is a thing that isn’t in it.

There is no tool in this book. Not one. No “here’s my Claude Code setup.” No .cursorrules walkthrough. No comparison table of Copilot versus Opencode versus whatever shipped last Tuesday and will be deprecated by the time you finish the chapter. No recommended library, no framework, no repo to clone. The author does not tell you which model to use. He does not tell you which agent harness to use. He never once tells you what to install.

I’ve read a lot of books and many blog posts about AI-assisted development at this point, mine included, and nearly all of them sit at one of two extremes. Either they’re deeply technical and showing you how to write the code, or they’re written for stakeholders and exist to convince a CEO that AI deserves a budget line. Both have a shelf life of about six months, because the thing they’re really teaching you is a menu, and the menu changes. This book sits between the two, which happens to be the only place where you come away with a framework in your head instead of a list of settings.

Beyond Code is teaching you the physics. Every failure mode it describes is derived from a property of how attention works, or how information behaves when you compress it, or how optimization pressure behaves when you point it at a proxy. None of those change when a new model ships. McEntire says this outright, and it’s the line that made me trust the rest of the book:

The engineer who understands information loss at coordination boundaries, proxy optimization in evaluation systems, and the structural impossibility of quality-through-review-gates does not need to memorize a list of anti-patterns. They can derive the anti-patterns from the physics, and they can design architectures that avoid them by construction rather than by vigilance.

That’s a hell of a claim to open with. He mostly delivers on it.

The Framing That Should Be on a Poster

The book opens on an asymmetry I have been failing to articulate since I started doing this:

the cost of building software dropped by roughly an order of magnitude, but the cost of building the wrong software did not drop at all. When code was expensive to produce, the expense itself served as a natural forcing function for thought.

Everything else falls out of that. When typing was slow, the slowness did your thinking for you. It made you consider whether the feature was worth it, because you were the one who had to sit there and type it. That forcing function is gone and nothing replaced it.

There’s a carpenter analogy early on that I’d normally roll my eyes at, because tech books love a trade analogy, but this one earns it. Give a nail gun to someone who understands load paths and soil conditions and you get a faster carpenter. Give it to someone who’s never framed a wall and you get something that looks like a house until the first heavy snow. The line that stuck:

It made them a fast amateur, and a fast amateur with a power tool is more dangerous than a slow one, because the volume of confident mistakes exceeds anyone’s ability to catch them before the roof goes on.

I have been the fast amateur. I have fifteen projects proving it.

The Chapter That Made Me Go Look at My Own Repo

A guideline says “functions should be short.” A constraint says “functions exceeding fifty lines fail the linter.” The guideline needs someone to agree, to notice, and to care. The constraint just fails the build. One admits interpretation. The other doesn’t. I’d been operating on that distinction by feel and had never had the words for it.

Then he describes constraints as a topology. Rigid exterior, flexible interior. The boundary is enforced mechanically and non-negotiably, and inside the boundary the agent gets total freedom on naming, structure, algorithm choice, error handling, all of it.

And then he names the failure on the other end, which is the one nobody warns you about:

An over-constrained system has specified the requirements so precisely that no implementation can satisfy all of them simultaneously without consuming the entire budget on compliance. The remedy in both cases is the same: constrain what matters, leave flexible what does not, and know the difference.

I stopped reading and went and looked at a repo.

Because I have written this exact arc as three separate blog posts without once connecting them. I vibe coded a project into a corner and got a sprawling codebase that did a third of what I wanted in a way that made the other two thirds impossible. That’s under-constraint. Then I tried spec-kit on the same idea and generated a beautiful tree of documents describing something I was still guessing about, and I was exhausted with the project before I wrote a line of code. That is over-constraint, precisely, and I’d been telling people it was a spec-kit problem. It wasn’t. It’s a topology problem. Spec-kit just made it easy to fall into.

The thing that eventually worked, a single PLAN.md with numbered decisions and everything else left loose, is a constraint topology. I built one by accident and then wrote a post about how the trick was “dumber than I want to admit.” Turns out the trick has a name and about eight pages of derivation behind it.

That’s the experience this book keeps producing. Not “here’s a new technique.” More like watching someone explain the mechanism behind a thing you’d already stumbled into, which is somehow both validating and humiliating.

What Not to Feed

One chapter in here is worth the price of the book on its own.

The core argument is arithmetic. Attention is a fixed mass distributed across candidates. Ten thousand tokens of context, each token gets a share. A hundred thousand tokens, each token gets a thousandth of that share. The degradation isn’t a bug someone will patch. It’s how the mechanism works.

Then he lands the part that genuinely reordered something in my head:

This mechanism explains why well-written documentation is more dangerous than random text. Random text has low semantic coherence with the task-relevant information in the context. The model’s attention mechanism can distinguish between meaningfully related tokens and gibberish, and it largely ignores the gibberish. Coherent documentation on a related topic, by contrast, is densely packed with tokens that are semantically proximate to the task-relevant tokens.

Gibberish in your context is harmless. The model routes around it. Well written, on-topic, genuinely useful documentation that happens to be irrelevant to this specific task is the poison, because it looks identical to the relevant material in embedding space. The model cannot tell “related and relevant” from “related and irrelevant.”

He points this straight at RAG, noting that retrieval by semantic similarity is retrieval by exactly the metric that predicts maximum distraction. I don’t think that’s a full takedown of RAG and he doesn’t claim it is, but it’s the most uncomfortable sentence about RAG I’ve read.

For me it explained a thing I’d already fixed without understanding. My PLAN.md grew to 28,000 words and became the document I dreaded opening, so I built a skill to keep it lean and file the cooled material into linked docs. I thought I was solving a token cost problem and a me-being-bored problem. I was actually solving an attention dilution problem, and every word in that doc was well written and on topic, which per this book is what made it worse.

The rule he gives is one line and it’s the whole discipline: the quality of context is determined as much by what you exclude as by what you include.

There’s also a small tactical thing in here that I’ve already changed my behavior over. Negative instructions backfire mechanically. To process “do not use eval,” the model has to represent eval, which activates the attention patterns around eval, which raises the odds eval shows up in the output. Then it has to suppress that, and suppression fails under load more often than activation does. So the forbidden thing appears because you forbade it. Positive instructions specify the correct point in the solution space. Negative ones exclude one wrong point and leave the rest wide open.

My agent instruction files are full of “never do X.” I have some editing to do.

Mechanical Gates Over Advisory Review

This is the section I expect people to argue with, and it’s the one I most agree with.

Advisory review asks whether someone did the work. Mechanical verification asks whether the work succeeded.

The argument is that code review, as practiced almost everywhere, is advisory. It renders an opinion. And any process that asks “does this look right?” instead of “does this pass?” is asking a question with no objective answer, so the answers get governed by cognitive bias and social dynamics instead of by properties of the artifact. Swapping human reviewers for AI reviewers doesn’t fix it, because the humans were never the problem. The gate was.

I’ve been building around this without naming it. Every one of my writing pipeline skills that actually holds up is a mechanical gate. A link auditor that resolves every URL. A fact checker that produces a pass or fail report. A brief checker that counts headings against the spec. The skill descriptions I wrote for myself say things like “generation is unreliable, this is the guarantee.” I wrote that before I read this book, and reading it felt like getting graded.

The chapter goes further into contract-driven development, where the contracts are the product and the implementation is disposable. Production incident happens, you don’t patch the implementation, you write a reproducer test and regenerate the implementation against the stricter contract. “The implementation is cattle, not pets.” He handles the obvious objection honestly, too, which I appreciated: contracts only test what you thought to specify, and they don’t test what you failed to anticipate. His answer is convergence over time rather than a claim of completeness.

The Multi-Agent Thing

This is the part that stung.

He ran experiments across pipeline, hierarchical, and swarm agent architectures, and the finding is blunt: a single agent with full context beat every multi-agent configuration, because it suffered no compression loss. Every gate in a pipeline squeezes a rich code artifact down into a low-dimensional verdict, and every stage after that operates on the verdict instead of the code. The information is gone and no amount of additional review recovers it.

For any task that fits within a single agent’s effective context window, hierarchical distribution is a net negative: it introduces compression losses, strategic distortions, and coordination overhead without providing any compensating benefit.

I want to be honest about my reaction here, which is that I did not want this to be true. I like the fan-out. Firing off a bunch of agents in parallel feels like leverage. It also once killed an entire session for me, because twenty-two background jobs finished at various times and each one dumped its full output back into the same context, and the session ate its own limit in about a minute. I turned that into a hard rule in my global agent config afterward: cap concurrency, jobs write to disk, they return a path and a one line status. Conclusions come back, not payloads.

That rule was pure scar tissue. This book explains it as coordination bandwidth. Distribute only what actually needs distributing, decompose at natural information boundaries where coupling is low enough that the interface fits in a sentence or two, and coordinate through the shared environment rather than through chatter between agents. That last one he calls stigmergic coordination, and the best line in the chapter is about why it beats agents describing things to each other:

A description of a bug is a lossy compression of the bug. The test failure is the bug, visible in the shared environment without anyone’s having described it.

That’s what a task board and a test suite have been doing in my projects the whole time. I just thought of them as project management.

Every Metric in My Pipeline Is Now Suspect

I came off the Goodhart chapter right before sitting down to write this, so it’s the freshest one in my head. The argument isn’t the usual “metrics bad” hand-wave. It’s that the search for the correct metric is itself the mistake, because the divergence between proxy and objective is structural rather than a matter of picking better. Test coverage measures execution and execution is not verification, and no amount of refining coverage as a metric will make those the same thing. His agents weren’t gaming the system out of career anxiety. They optimized what they could see at the expense of what they couldn’t, which is just what optimizers do.

Where It Loses Me a Little

Two honest gripes.

The prose is dense. This is not a book you skim on a phone. Some sentences run long enough that I had to take a second pass, and the register stays clinical even when the material is dramatic. I don’t mind it, but if you want the breezy conversational thing, this is not that. It reads more like a good long paper than like a blog. But each chapter is broken up into sections that are rarely over two pages long, so you can read it in bite-sized pieces.

The other is that being tool-agnostic has a cost. The book will tell you to encode a constraint mechanically and it will not tell you what that looks like in your stack. That’s deliberate and it’s why the book won’t rot, but there were a few points where I wanted one concrete example and got a principle instead. You are expected to do the translation yourself. If you want a book that hands you a config file, this is not the book for you.

Where I Actually Am With It

The technical argument is the part I came for and it’s done: the shift, context, constraints, coordination. What’s left is Part V on the craft and Part VI on where engineering goes, which look more like the career and human chapters. I’m going to finish it.

Beyond Code: Context, Constraints, and the New Craft of Software by Jeremy McEntire. Five stars on the two thirds I’ve read, and I’ll revisit that when I finish the rest.

Who should read this: anyone who has been using coding agents seriously for more than a few months and has started noticing that the failures repeat. If you’re finding that your agents fail the same way across different tools and different models, this book explains why, and the explanation will survive the next model release. It’s also, I think, genuinely good for the “AI is useless” and “AI replaces engineers” crowds, both of whom are answered here by the same argument: the cost of producing code collapsed, the cost of knowing what to build did not, and both camps are assuming the first one implies the second.

Who shouldn’t: anyone looking for a setup guide. Go read a blog post. Possibly one of mine.

I read a lot of stuff in this space and most of it is somebody’s workflow with the serial numbers filed off. This is the first one where I finished a chapter and went to go change something in a repo. Then did it again four chapters later. That’s a low bar in theory and almost nothing clears it.