Uncle Bob's AI Coding Pipeline: 5-Agent Gauntlet & Architecture Governance

Quality Assurance Pipeline: 5-Agent Gauntlet Relay

Uncle Bob's AI coding methodology centers on a pipeline called Gauntlet, where five specialized agents each perform a single task and exit, passing artifacts via git worktree or handoff files to avoid "mental residue." A single agent takes ~5 minutes but yields questionable quality; the full pipeline takes ~1 hour, replacing half a day of human work with higher quality.

Agent Roles

Specifier : Converts human requirements into executable Gherkin (Given-When-Then) acceptance scenarios plus QA step documents. Output: executable acceptance spec; ambiguities are clarified by asking humans.

Coder : Takes Gherkin spec, writes unit tests and implementation to pass acceptance scenarios (red→green). Output: behaviorally correct code, not necessarily clean.

Cleaner : Runs CRAP analysis, splits high-cyclomatic-complexity functions, performs DRY review, adds tests. Output: code meeting CRAP/complexity thresholds (agent threshold relaxed to 6–8, human standard ≤4).

Hardener : Applies mutation testing (e.g., changing > to >=, + to -, boolean negation) to verify tests catch mutants. Output: zero surviving mutants, high-coverage "true test" suite.

QA Agent : Converts Specifier's QA document into UI-driven executable scripts for end-to-end runs. Output: deterministic pass/fail report for human review.

Design Principles (Counter-intuitive but Critical)

Context Isolation : Each agent is born, works, dies, avoiding the "Lost in the Middle" effect; rules placed at the top of context.

Rules Externalized : TDD rhythm, Clean Code rules not stuffed into prompts; instead enforced via unit-test gates, CRAP gates, mutation testing—agents can forget the 80th reminder but cannot bypass a failing run.

Threshold Recalibration : Don't impose human cognitive habits (strict TDD test-first, complexity ≤4) on agents; agents have strong short-term memory, can write code then add tests, complexity ceiling raised to 6–8.

Humans Only Review Reports : Pass/fail, coverage, surviving mutants, CRAP distribution, dependency violations—no line-by-line code review; as Uncle Bob says, "don't review the toolpath, build the gauge."

Architecture Governance & Planning: Humans Guard Boundaries, Agents Take Small Steps

Module Boundaries & Dependency Rules — Human-Defined, Tool-Enforced

Agents excel at tactical coding, not strategic layering. Uncle Bob still draws module boundaries himself, then lets agents work within constraints:

Deep Module Preference (Ousterhout) : Narrow interfaces, wide implementations; agents only need interfaces and unit tests to proceed, avoiding internal noise.

Dependency Direction Allow/Deny Lists : A may depend on B, but B must never depend on A; violations require interface extraction, dependency inversion, or module split.

Architecture Viewer (UML-like) : Humans drill down into modules for review without reading line-by-line.

Dependency Verification Config : Serves as an immutable "constitution" for agents; CI runs dependency graph checks, rejecting any boundary crossing.

Anti-Waterfall: Feed Small Stories, Fast Feedback Loops

Agents love writing grand plans but collapse on details—mirroring 1970s waterfall SDD failures. The approach:

Human provides 1–2 concrete User Stories (not MRD, not full technical design).

Agent runs full Gauntlet, producing artifacts plus evidence package.

Human reviews only: architecture changes, dependency graphs, permissions/money/concurrency, QA report, surviving mutant list.

Manually adjust module boundaries or acceptance points, then feed next story.

Spec documents are ephemeral; final code is the spec; no maintenance of "forever-correct upfront design."

Minimum Viable Loop (Teams Can Adopt Today)

If not ready for the full 5-agent pipeline, start with this:

Write requirements as Given-When-Then (including exceptions and edge cases).

Agent must write code with unit tests, red→green.

One make gauntlet command chains: typecheck + lint + unit tests + coverage gate + mutation testing + complexity ceiling.

Threshold breaches (surviving mutants >0, CRAP >8, dependency violations) automatically return to agent for self-repair.

What reaches human eyes is an "evidence package"; human only judges architecture and risk.

Closing Summary

The quality pipeline makes "agents prove themselves correct."

Architecture governance means "humans set boundaries, agents sprint in small steps within them."

Together, they reconstruct Clean Code discipline from "humans memorize rules" into "system-enforced rules."