Anti Pattern Catalog

The Anti-Pattern Catalog

Status: Complete · The named ways SAE decays in practice — each mapped to the principle it betrays and the fix that restores it.

A framework doesn't fail all at once. It rots one shortcut at a time. Every anti-pattern below starts as a reasonable-looking accommodation under deadline pressure — a hand-fix you'll reconcile later, a check you'll run next time, a role you copied because the diagram looked clean. Individually they feel survivable. Collectively they hollow out the discipline until you're running the costume of SAE — the folders, the roles, the spec files — with none of the load-bearing rigor. This page exists so you can name the decay early, because a failure mode you can name is one you can refute. Each entry follows the same shape: Symptom (how you notice), Why it happens, Violates (the First Principle at stake), and The fix.

---

The Stale Spec

Symptom. The specs/ folder describes a system that no longer exists. Behavior was changed in code, the spec was never updated, and now both humans and agents are reasoning from a document that lies.

Why it happens. A one-line hot-fix in production is faster than editing the spec and regenerating. The reconciliation gets deferred — and deferred work in a solo operation is forgotten work.

Violates. P2 — The spec is the source of truth. A spec that disagrees with shipped code isn't a source of truth; it's a second bug.

The fix. Reconcile every hand-edit back into the spec the same day. Track spec-drift time (hours between a code change and its spec catching up) as a first-class metric — when it grows, the framework is decaying regardless of how good the other numbers look. A stale spec is worse than no spec, because everyone trusts it.

---

The Self-Judging Writer

Symptom. The same context that generated the code also "reviewed" it and declared it correct. The review reads like a victory lap — it confirms rather than refutes.

Why it happens. Spinning up a fresh adversarial context costs tokens, time, and a deliberate change of posture. Asking the writer "does this look right?" is one keystroke and it always says yes.

Violates. P3 — The writer never judges its own work. A context that just wrote the code shares every assumption it made; it is structurally incapable of seeing its own blind spots.

The fix. Verification comes from a separate, clean-context Guardian briefed to refute, not approve — grey-box, reviewing the diff, not its own output. Confirmation is not a pass; an unrefuted change is. For high-stakes changes, use diverse lenses instead of repeating one identical check.

---

Context Pollution

Symptom. Answers drift. The agent starts referencing files you never primed, contradicts earlier decisions, or confidently invents APIs. Quality degrades the longer a session runs.

Why it happens. People keep one mega-session open all day and dump the whole repo into it "so the model has everything." More context feels safer. It is the opposite — signal-to-noise collapses and precision goes with it.

Violates. P1 — Clarity is the binding constraint and P4 — Isolate bounded contexts. Clarity-per-unit-of-context drops as you flood the window with the irrelevant.

The fix. Prime with only the relevant slice, its spec, and the rules file. Start a fresh context the moment answers drift — never fight a polluted session. Treat the context window as a scarce, curated workspace, not a dumping ground.

---

The Happy-Path-Only Spec

Symptom. The spec describes exactly what should happen when everything goes right and is silent on everything else. The generated code handles the demo and falls over on the first malformed input, empty list, or concurrent write.

Why it happens. The happy path is the part you can picture, so it's the part you write. Edge cases require the harder, higher-Context-Entropy thinking the spec exists to force — and skipping them feels like progress.

Violates. P2 — The spec is the source of truth. The edge cases are the spec; a spec that omits them under-specifies the system and hands the agent license to guess.

The fix. Write the failure modes explicitly: empty, malformed, oversized, concurrent, unauthorized, partial. If you can't enumerate how it breaks, you don't understand it well enough to generate it. Score the task's preparation difficulty before starting — high-entropy work earns more edge-case specification, not more keystrokes.

---

The Big-Bang Rewrite

Symptom. "Generation is free now, so let's regenerate the whole subsystem in one shot." A massive, unreviewable diff lands touching dozens of files, and nobody can verify it slice by slice.

Why it happens. Near-free generation makes the rewrite look cheap. The cost didn't disappear, though — it moved to verification and accountability, which do not scale with a single prompt.

Violates. P4 — Isolate bounded contexts and P6 — You own the output. A diff too large to understand is a diff you can't honestly sign off on.

The fix. Slice the work into bounded, independently verifiable vertical changes — each one understandable and reviewable on its own. Cheap generation is an argument for more, smaller increments, not one giant leap. If a fresh context can't hold the change, it's too big to verify.

---

Autonomy-Ratio Gaming

Symptom. Your autonomy ratio — the share of changes shipped with zero hand-edited code — climbs impressively. "Look, no hand-fixes!" Meanwhile the regression escape rate is quietly climbing right alongside it.

Why it happens. Autonomy ratio is visible, flattering, and easy to optimize: just stop hand-editing and ship whatever the agent produced. The escape rate is the metric you can't see until production tells you — so you trade the invisible one for the visible one without noticing.

Violates. P7 — Honest by construction. A metric optimized into a lie is the purest form of self-deception, and self-deception is the primary defect when clarity is the product.

The fix. Never read a flow metric without its paired quality metric. High autonomy ratio with a rising escape rate isn't autonomous — it's sloppy. These are personal instruments for making decay visible early, not a dashboard to perform for someone else. If you're tempted to celebrate a single number in isolation, that's the tell.

---

Cross-Context Leakage

Symptom. A change to one feature silently breaks another. Bounded contexts share mutable state, reach into each other's internals, or import across the seam "for convenience." The slices exist on paper but bleed in practice.

Why it happens. A narrow contract is more work to define than a direct reach-across. The agent, asked to do the quick thing, will happily wire two contexts together unless the architecture physically discourages it.

Violates. P4 — Isolate bounded contexts. Once slices leak, no single one can be understood or changed without reading the rest — and clarity-per-context collapses.

The fix. Enforce narrow, explicit contracts between contexts; encapsulate vendor and external code behind an adapter seam so it can't leak into domain logic. Apply the test on every file: can a fresh context understand this without opening six others? If not, the isolation has already failed.

---

The Symptom-Masking Auto-Heal

Symptom. An agent — or an automated retry/recovery loop — "fixes" a failure by suppressing the symptom: swallowing the exception, retrying the deletion, re-running the migration, papering over the auth error. The alert goes green; the underlying fault is now invisible and irreversible damage may already be done.

Why it happens. Auto-remediation feels like maturity — "the system heals itself." But healing that hides the cause is just deferred catastrophe, and when it's applied to irreversible operations, there's no undo.

Violates. P5 — Gate the irreversible by blast radius. The cost of a mistake, not its likelihood, decides the gating — and auto-heal removes the gate precisely where it matters most.

The fix. Classify every operation by blast radius. Auth, payments, deletion, and schema drops never auto-apply and never auto-retry — they stop at an explicit human gate with an independent P3 review. Reversible failures may self-recover; irreversible ones surface loudly and wait for a human. Auto-heal that masks a cause is a defect, not a feature.

---

Unevaluable Output

Symptom. Code ships that the operator can't actually read, explain, or judge — generated in a domain or style they don't understand, accepted on faith because "it passed the tests and the agent seemed confident."

Why it happens. When generation is near-free, the temptation is to outsource not just the typing but the understanding. "The AI wrote it" starts to feel like an explanation.

Violates. P6 — You own the output. Accountability does not delegate to a model, vendor, or agent. Output you cannot evaluate is output you cannot own.

The fix. Generated code is read, understood, and signed off — never shipped on faith. If you can't evaluate it, you have two honest moves: raise your own clarity until you can, or recognize the work as outside SAE's fit and get a human who can judge it into the loop. "The AI wrote it" is not an explanation an operator gets to give.

---

Cargo-Cult SAE

Symptom. A team adopts the artifacts of SAE — the Digital Org Chart roles, the features/<slice>/ layout, a specs/ folder, the Guardian label — but skips the discipline underneath. They have the diagram; they don't refute, don't measure drift, don't gate by blast radius. They copied the structure and ignored the principles.

Why it happens. Structure is cheap to copy and looks like adoption. This is the Spotify-model warning: organizations cloned "squads and tribes" off a conference talk while the actual practices that made them work never transferred. SAE's roles and folders are just as easy to mimic and just as worthless without the underlying rigor.

Violates. All seven — but most sharply P7 — Honest by construction. Adopting the vocabulary of discipline while skipping the discipline is the framework's deepest self-deception: it looks like SAE to everyone, including yourself.

The fix. The artifacts are consequences of the principles, never the point. Audit by asking of every practice: which of P1–P7 does this enforce, and how would I measure that it's working? A Guardian that doesn't refute is a label. A spec nobody reconciles is a graveyard. If a practice can't be traced to a principle and a metric, you have the costume, not the framework — see the Maturity Model for what real adoption looks like at each stage.

---

Reality check. No one runs SAE free of every anti-pattern on this page — under real deadline pressure you will hand-fix and reconcile late, ship thinner tests than you'd like, or let a session run long. The goal isn't a clean sheet; it's making each deviation deliberate and tracked rather than silent and forgotten. A principle you broke knowingly and logged is recoverable. One you broke without noticing is technical debt compounding in the dark. This catalog isn't a purity test — it's a vocabulary for catching the rot while it's still cheap to reverse.

---

See also: First Principles · Best Practices · The Verification Doctrine · KPIs and Metrics · The Maturity Model · When Not to Use SAE · Risks, Security and Governance