Skip to main content

Chapter 19

AOD Anti-Patterns

What Goes Wrong and How to Fix It

13 min read

Part 19 of the Agentic-Oriented Development series.


It was a weekend in October. I was coding at home. The authentication kept breaking, so I had built another authentication system. Then a third. One for users. One for owners. One for the Model Context Protocol (MCP) server, the layer agents use to reach outside tools and data. Three auth flows in one project, each one bandaged onto the last, all of them disagreeing about which token to trust.

That was the moment. Three auth systems is not a bug. Three auth systems is a structural pattern. The product had started as a small developer tool that scanned code for AI security weaknesses. By October it had grown into a monolithic Software-as-a-Service (SaaS) application with administrators, owners, and end users. Three audiences. Three auth surfaces. None of them existed in the dev-tool idea I had started with two months earlier.

I had a spec. By the standard of "did you plan," I had planned. What I did not have was a harness around the plan. No test that failed before the agent ran. No eval that graded what came back. My quality signal was "does the demo work." It did, until it didn't.

I tell you this story because every agent system I sit with now is running some version of that same product, even when the spec exists and the demos still pass.


Eighteen chapters of this book have built up the positive patterns. Context, tools, inheritance, polymorphism, orchestration, evals, knowledge, and the topology that holds them together. Every one of those positive patterns has a corresponding failure mode that practitioners ship anyway. The failure modes are not random. Each one is the absence or inversion of a specific positive pattern this book has already named.

I have shipped each of the six. I count my own teams in that number, and I count myself at the top of the list. The patterns recur often enough on the systems I review that I name them on sight, before the team has finished walking me through the architecture. Naming the failure mode gives the practitioner a vocabulary for what they are looking at when a system starts to break. Without the vocabulary, the team treats every failure as a one-off. With it, the team recognizes the shape and goes looking for the fix.

Part IV opens here. The catalog is the vocabulary. Six anti-patterns, each treated the same way. Name. Symptom. Why it happens. Consequence. Fix. Diagnostic test. The fix in every case is a positive pattern this book has already named, re-framed as the antidote.

AOD Operation — Diagnostic Game

The first pattern is the most architectural of the six. It is the one I had been building since the end of summer.


The Monolith Agent. One agent doing everything, refusing to specialize, refusing to delegate.

Symptom:

  • The agent's context window fills with mixed concerns. Frontend code, backend logic, deployment scripts, and test cases all live in the same conversation.
  • The agent answers every question but accumulates errors as the session ages. Outputs that were sharp in the first hour drift by the third.
  • The team builds workarounds because the agent's context is exhausted by mid-task. Frequent resets, manual handoffs, and re-pasting earlier context become the daily routine.

Why it happens. It is the path of least resistance. One agent is conceptually simpler than three. Setup is one prompt, one configuration, one place to debug. The cost of specialization (defining roles, designing handoffs, building an orchestrator) is upfront and visible. The cost of the Monolith is backloaded. Productive in the first hour. Painful in the third.

Consequence. Context exhaustion was Chapter 2's diagnosis. The agent's window fills, attention drops, and the system degrades silently. The Monolith hits it on every nontrivial task. With no per-role specialization, failures cluster around the agent's weakest competency rather than the task's hardest part. The system breaks in the same place every time.

Fix. Split the agent's prompt at the first sentence that mentions a second role. That line is the seam. Then specialize and orchestrate. Chapter 5 named the Swiss Army Agent as the seed anti-pattern. The Monolith is its full expression with no orchestration layer to make specialization scale. Chapter 8's orchestration layer is the coordination piece the Monolith never had. Chapter 14's four-layer topology is where specialization scales structurally, and the Monolith collapses all four layers into one.

Diagnostic test. If a single agent's prompt has more than two distinct role concerns, it is a Monolith candidate. Split it.

Specialization handles the agent count problem. The next failure mode is what happens inside the context of whatever agent you have.


Context Hoarding. Loading everything into a single context, never delegating, never pruning.

Symptom:

  • The base context file (CLAUDE.md, AGENTS.md, or your equivalent) grows past 200 lines and keeps growing. Every new rule, every new exception, every special case gets appended.
  • The agent burns the first quarter to third of its working memory on orientation before it touches the actual task, because the context preamble has become a small book.
  • The team treats more context as more safety. Adding instructions feels like reducing risk.

Why it happens. Context feels free. The window is large. Adding a paragraph "just in case" costs nothing visible at the moment of writing. Pruning feels risky, because removing a line might break something the writer does not remember adding. Roadmap pressure compounds it. Every near-miss in a sprint demo produces a new "remember to also do X" rule that gets pasted into the base context as the cheapest available fix. Delegation, the real defense, gets postponed because spinning up a subagent is more work than appending one more rule.

Consequence. Context pollution, the diagnosis Chapter 2 made for low-value information crowding out high-value information, takes over. The agent's attention budget is finite even when the window is not.

The agent starts ignoring earlier sections because more recent material dominates. Rules added "for safety" get silently dropped. Chapter 4's inheritance chain becomes brittle, because specialized contexts that should override the base get drowned by the base context's bulk.

Fix. Open the base context file. Highlight every paragraph that exists for a single special case. Move those out of the base. Then encapsulate, delegate, prune. Chapter 4's 200-line rule is the architectural defense against hoarding in the base context. Chapter 11's three-layer memory model names which knowledge belongs in long-term Practitioner Knowledge (the persistent, AI-readable record of what a team has learned across projects) and which belongs in session context.

Diagnostic test. If the base context cannot fit on a single screen, it is hoarding. Move detail into specialized contexts, skills, or Practitioner Knowledge, then prune what is left.

If the Monolith is too many roles in one agent, Context Hoarding is too much knowledge in one place. The next failure is too little discipline in any place.


Vibe Coding. No harness around the spec. No test, no eval, no rails. The team prompts the agent and hopes it figures out the rest.

Symptom:

  • There may be a spec, but there is no test that fails before the agent runs and passes after.
  • No eval that says whether the output meets the criteria.
  • The team's quality signal is "does the demo work." If yes, ship. If no, prompt again.
  • The team uses words like "feels right" and "looks good" to evaluate output.

Why it happens. The agent is fast enough that the upfront cost of harness work feels disproportionate to the time saved. Tests and evals feel like the old software development lifecycle (SDLC) overhead the agent was supposed to eliminate. Demo culture reinforces the pattern. Clean demos are the metric. The rails the agent ran on are invisible cost. Early wins (a fast feature, a quick demo) compound it. The cost shows up at the third feature, not the first. The team confuses the agent's confidence with the team's confidence, because the agent always sounds sure.

Consequence. The agent ships output nobody can defend. When the demo breaks in production, the team cannot reconstruct what the agent was supposed to do, only what it did. Successive prompts amplify drift, accumulating context without removing the conditions that caused the original miss. The team plateaus at the agent's default behavior, because no eval pushes the agent past its first acceptable answer.

I have shipped this pattern. The weekend-in-October product had a spec and shipped every symptom on the list. A spec without a harness is still Vibe Coding. The Agentic Maturity Ladder from Chapter 6 names three levels of discipline that escalate from no harness, to careful prompting, to full evaluation harness (Vibe Coding, Prompt Engineer, Agentic Engineer). Vibe coding is Level 1, what AOD exists to replace.

Pull the Pillars — Archie-Style Comic Strip

Fix. Write one test that fails before the agent runs and passes after. That is the contract the agent has to satisfy. Then add an eval that grades the contract. Chapter 7's spec-driven development is the discipline that replaces hope-and-prompt with an executable contract. Chapter 10's tests-as-specification approach closes the gap when the team finally writes the test. Chapter 9 named evals as control flow, not as quality theater, and that distinction is what lets a probabilistic system have a graded signal at all.

Diagnostic test. If the team cannot point to the spec the agent is satisfying, the team is vibe coding. If the team has a spec but no eval that grades against it, the team is vibe coding with extra steps.

Discipline determines whether the output is right. The next failure is what the agent reaches for to do the work.


Over-Tooling. Building custom tools when existing tools or composition would do.

Symptom:

  • The team has its own MCP servers for things that have published MCP servers (filesystem, git, search).
  • The team's custom tools are thin wrappers around existing commands the agent already knows how to call.
  • The tool count grows faster than the agent's measurable competence.
  • Each tool has its own bug surface, update cadence, and security review burden.

Why it happens. Custom tools feel like the engineering work. Building a tool produces an artifact. Configuring an existing one does not. Existing tools may seem too generic, so the team builds a "thin" wrapper that adds a few opinions. The wrapper accumulates into a maintenance burden no one wants to own. The team confuses tool count with capability. More tools feels like more options, even though the agent's effective competence does not scale linearly with tool count.

Consequence. The agent's tool-selection cognitive load grows with every new tool added. The agent spends more reasoning on "which tool" and less on "what to do." The team accumulates a tool maintenance backlog with no clear owner. Updates to the underlying agent platform break the wrappers, and the team patches, re-patches, and patches again. The agent's actual capability stays flat or regresses, because the tools are not addressing the agent's real gaps. Each custom tool wrapping a privileged operation is also a new supply-chain surface. The team owns the wrapper, the vulnerabilities, and the patch cadence.

Fix. List every custom tool. For each, answer in one line what the agent would be unable to do without it. Retire the ones whose answer is "compose two other tools." Then compose first, build only when no composition fits. Chapter 3 named over-tooling as the new over-engineering, and the VOICE principles (Visible, Outcome-oriented, Isolated, Composable, Error-aware) as the discipline that prevents it. Chapter 12's practitioner decision tree (skill, MCP, or memory) gives the team a checklist before they reach for "build a new tool" as the first option.

Diagnostic test. Every custom tool the team owns should have a one-line answer to "what would the agent be unable to do without this?" If the answer is "compose two other tools," the custom tool is over-tooling.

Tools determine what the agent can do. Governance determines whether you can trust what it did.


Trust Without Verify. No governance, no validation. The team assumes configuration is the same as verification.

Symptom:

  • The team has set up the agent system carefully, with good prompts, scoped tools, and well-named subagents, and treats setup itself as the safety mechanism.
  • There are no evals running between agent output and downstream use.
  • There is no human review at decision points where the cost of a wrong decision is irreversible.
  • The team's confidence rests on "we configured it right" rather than on "we measured what it produced."

Why it happens. The configuration work is visible and effortful. The team feels they have done the safety work because the artifact (prompts, tools, roles) is real and tangible. Evals feel like extra work that delays delivery, especially when the agent is producing usable output most of the time. The team treats agents as deterministic systems. The probabilistic ceiling is not in the team's mental model.

Consequence. Even a well-configured agent produces non-deterministic output. Good context engineering improves the odds. It does not eliminate variance. Birgitta Böckeler at Thoughtworks named the failure mode first. The label I use for it is the probabilistic ceiling (the upper bound on how reliable a probabilistic system can ever be, no matter how well it is configured). Context engineering raises the probability of useful results. It does not guarantee them.

The Probabilistic Ceiling — Asymptote Graph

Treating probabilistic systems as deterministic ones produces silent failures. The agent produces a confident wrong answer the team has no mechanism to catch. The first major failure is usually expensive because the team built no detection layer. Chapter 18 named the rubber-stamp human as a chain failure mode, where oversight is claimed in name and not in fact. I have shipped this. The harness was clean. The output was not.

Fix. Pick the single decision with the largest blast radius, the one whose wrong answer is irreversible. Add a grader for that decision, and log its inputs and outputs so an auditor can reconstruct what the agent decided and what the grader said about it. Iterate from there. Then build out governance and evals, not more configuration. Chapter 9 named evals as control flow, the structural reason a probabilistic system needs them. Chapter 13's AURA framework (Agentic Utilization and Reliability Assessment, the check that grades whether evals are actually catching what they claim to catch) closes the loop. The Governance Triad from Chapter 16 is the bound that prevents Trust Without Verify from compounding across a system. PM, Architect, and Team Lead sign off on agent creation. Security joins the triad for any agent that touches production systems. Book 2 expands the security path.

Diagnostic test. What grader is running on this output, and what does the grader do when it fails? If the answer is "no grader" or "logs the failure and continues," the team is trusting without verifying.

Verification keeps a single session honest. The next failure mode is what happens between sessions, when the learning the team paid for evaporates before the next agent run loads.


Knowledge Amnesia. Every new session reconstructs understanding from scratch because the team never serialized what was learned.

Symptom:

  • The code exists, but no one (human or agent) can explain why it was built that way.
  • New team members and new agent sessions both spend disproportionate time re-deriving decisions that were made and forgotten.
  • The team has no Practitioner Knowledge layer, no persistent, AI-readable record of what was tried, what worked, and what failed.
  • Decisions get re-made. Sometimes the team re-discovers an old constraint by hitting the same wall a second time.

Why it happens. Knowledge serialization feels like documentation overhead. Documentation has a bad reputation from the SDLC era because it goes stale, no one reads it, and the cost feels disproportionate to the value. Sprint pressure punishes the practice further. The team that writes the lesson down sprints slower than the team that ships and forgets, and on the immediate scoreboard the forgetters look faster. Knowledge engineering (the practice of writing down what a team learned so the next session inherits it) is the fifth and newest of the agentic skills, and many teams have not yet absorbed it.

Consequence. Every new session pays the context reconstruction tax, and the cost compounds across a team. Past failures repeat. The team makes the same mistake a second time because the lesson lived in one person's head. The agent's effectiveness does not improve over time. Senior practitioners become the only place certain knowledge lives, and bus factor risk grows silently.

I have shipped this pattern. Every team I have watched run for more than two months without a Practitioner Knowledge layer has rebuilt the same understanding twice. Sometimes three times. I count my own teams in that number.

Fix. Start a project-knowledge file today. Write down what the last session learned, what failed, and why. The serialization habit is the antidote. Chapter 11's three-layer memory model names Practitioner Knowledge as the persistence layer that defeats the anti-pattern. Knowledge engineering is the fifth skill from Chapter 6, the one most teams skip until the cost of skipping shows up. Chapter 13's AURA Context Continuity Score grades whether knowledge actually survives across sessions or just feels like it does.

Diagnostic test. When a new session starts, what does it know that the first session did not? If the answer is "the same thing," the team has Knowledge Amnesia.


Six patterns. Each is the absence or inversion of a positive pattern from Parts I, II, or III. The catalog gives the practitioner a vocabulary for what they are looking at when a system starts to break and a place to look for the fix.

Anti → Positive: The Fix Map

The pattern under the patterns is one pattern. In every case, the team is treating the agent as a deterministic tool that follows configuration. The Monolith assumes one good prompt is enough. Trust Without Verify assumes the configuration is the safety. Knowledge Amnesia assumes the code is the memory. The fix in each case is a discipline that configuration cannot supply on its own. Specialization, verification, and serialization. Habits the team has to build, not settings the team can flip.

One Root, Six Symptoms — Iceberg View

There is a tested antidote. The open-source threat-modeling toolkit I shipped after the weekend product had a plan plus a harness around the plan, ready to use before any feature was written, and the build went ten features in ten runs.

The difference between the two products was not the spec. It was whether the rails the agent ran on were as complete as the features the agent was asked to build.

These same patterns become security failure modes once an agent has authority over production systems, and Book 2 is the catalog of controls for that authority.

Planning is not enough. Overplanning is critical.

Planning Is Not Enough Quote Poster

Naming the failure modes is step one. Designing an organization where the patterns do not compound across teams is step two. Chapter 20 (Enterprise AOD) takes that up. How AOD scales across business units, where the Product Triad lives in the org chart, what governance the enterprise has to add, and which of these six anti-patterns the org structure itself produces if no one is watching. Part IV continues there.

Like what you read? Get the next chapter in your inbox.