Back to all posts
• 7 min read

Solving the Reviewing Problem in AI Engineering

How to combine Matt Pocock’s brakes-and-accelerators model, blast radius triage, proactive alignment with pedagogical diffs, and deterministic quality gates to eliminate review bottlenecks.

In Artificial Intelligence (AI) engineering, generating code has become trivially fast. Because coding agents can draft hundreds or even thousands of Lines of Code (LOC) in seconds, the bottleneck in software engineering has shifted decisively downstream to reviewing.

When an agent dumps a massive diff into your lap, you are immediately confronted with two interconnected dangers: cognitive debt (losing your mental model of the system) and AI slop (subtle architectural drift, bloated boilerplate, and leaky abstractions).

To solve the review bottleneck, we need a cohesive approach that balances speed with control. This can be achieved through two central ideas: proactive alignment to eliminate cognitive debt, and strict, automated quality gates. Underpinning both is a foundational design philosophy: building brakes before using accelerators.

1. The Core Paradigm: Matt Pocock’s Brakes and Accelerators

When developers first experiment with agentic workflows or try to assemble automated software factories, their instinct is almost always to maximize speed. They wire up autonomous agent loops, prompt models to generate whole features Away From Keyboard (AFK), and open massive Pull Requests (PRs).

As Matt Pocock points out in his cohort Software Factories for Real Engineers, this impulse creates a dangerous imbalance. Running an AI agent without constraints is like pressing the accelerator pedal to the floor in a car with no brakes. You might accelerate quickly in a straight line, but the moment you encounter a turn, you crash.

In software engineering, that crash takes the form of unmanageable PRs. Senior engineers end up spending more time deciphering slop, untangling regressions, and fixing hallucinations than they would have spent writing the code manually. The review process becomes a soul-crushing bottleneck.

Pocock’s core principle provides the remedy: first build brakes to decelerate, then use accelerators wisely to safely speed up.

The Golden Rule of Software Factories: Build Brakes First, Accelerate Safely

Before you unleash autonomous coding agents on a codebase, you must first construct reliable brakes: automated linters, strict type checking, mutation tests, and architectural boundary checks. Only when these brakes can reliably halt flawed code should you press the accelerator. Once your brakes are dependable, you can widen the autonomy loop and move with genuine speed.

2. Proactive Alignment and Paying Down Cognitive Debt

Cognitive debt occurs when code changes faster than our understanding of it. When an engineer writes code by hand, their mental model develops alongside each line. When an agent writes the code, the human is bypassed, leaving them feeling alienated from their own codebase.

To eliminate cognitive debt, we bracket the agent’s implementation phase with deliberate alignment practices before and after code generation.

Grill Before You Build

Before letting an agent write a single line of production code, conduct an interactive “grilling” session. Force the agent to challenge your assumptions, uncover domain edge cases, and clarify constraints. In turn, challenge the agent’s proposed technical approach. Aligning on interfaces, schemas, and error-handling strategies upfront prevents hours of wasted review downstream.

Slice Vertically and Tracer Bullets

If an alignment session feels overwhelming or sprawling, the task scope is too wide. Cut the task vertically into thin, manageable slices. Start with a tracer bullet: a minimal, end-to-end slice that connects all architectural layers and proves the contract works. Once the tracer bullet is verified, the agent can build out the remaining functionality slice by slice.

Close the Loop with Pedagogical Diffs (Geoffrey Litt’s explain-diff)

Never blindly accept a passing build if you do not understand how the agent implemented the solution. However, reading standard Git diffs is mentally fatiguing, especially when dealing with hundreds of lines of agent-generated code.

This is where Geoffrey Litt’s explain-diff skill provides an exceptional breakthrough.

Instead of treating code review as a tedious line-by-line inspection, the explain-diff skill transforms the diff into a self-contained, educational document:

  • High-Level Intuition and Narrative: It begins by summarizing the design rationale and architectural context, answering why changes were made before diving into syntax.
  • System Diagrams: It visualizes state changes, data flows, and component interactions with clear, consistent diagrams.
  • Concrete Walkthrough: It breaks down the diff by logical concern rather than alphabetical file order, walking the reviewer through critical logic.
  • Interactive Comprehension Quizzes: Crucially, it generates multiple-choice comprehension questions with expandable explanations.

By answering these quizzes, the human reviewer is forced into active recall. Rather than skimming lines passively, you actively test your own understanding of the new code. The review transforms from a chore into a structured learning session, immediately paying down cognitive debt and restoring your mental model before merging.

Review “Golden” Specs Instead of 50k Lines of Implementation

Human attention is a scarce resource. Instead of burning human brainpower auditing every boilerplate class or routine function, focus human review on spec-like black-box tests.

In Behavior-Driven Development (BDD), these tests define the observable contract of the system. If you review the “golden” specifications and confirm that all domain invariants and edge cases are covered, you can trust the agent’s internal implementation details. Just as you do not micro-manage every local variable written by a colleague, you verify the public contract and let automated quality gates handle the rest.

3. Trust as Predictability: Blast Radius and Doorways

Trust is not blind optimism; it is a measure of predictability. In an AI workflow, lack of trust manifests as anxious babysitting, exhaustion, and second-guessing every diff. You trust a coding agent when you know what it predictably does right, anticipate where it predictably stumbles, and engineer safeguards around those failure points.

To scale agentic engineering without burnout, Matt Pocock highlights two essential dimensions: evaluating what the agent produces, and determining what it will cost if something goes wrong.

One-Way Doors, Two-Way Doors, and Blast Radius

Pocock borrows Amazon’s classic doorway metaphor to categorize risk across agent-generated Pull Requests (PRs):

  • One-Way Doors (High Blast Radius): Decisions and actions that cannot be easily undone without substantial damage and recovery effort. Obvious examples include destructive database schema changes (such as dropping columns without data preservation), security vulnerabilities (exposing credentials or bypassing authentication), and passive real-world side effects (such as modifying a configuration file that triggers an automated batch email to 100,000 customers). One-way doors demand mandatory, meticulous human architectural review.
  • Two-Way Doors (Low Blast Radius): Changes that are straightforward to revert, isolate, or iterate upon. Examples include internal refactorings behind a stable facade, UI layout adjustments, or isolated utility functions.

By scoring PRs based on reversibility and blast radius (how much code, data, and user traffic the change touches), teams can triage review effort. High-risk one-way doors receive focused human attention, while low-risk two-way doors that pass all automated quality gates can safely merge with minimal or even zero human intervention.

Compounding Feedback Loops: Never Leave the Same Review Comment Twice

A major point of friction in agentic workflows is repeatedly correcting the same stylistic or architectural mistake across multiple PRs. Pocock advocates for compounding feedback loops: whenever a human reviewer leaves feedback on an agent’s PR, the factory implements the fix and converts that critique into a persistent linter rule, test assertion, or rule file.

The software factory learns continuously. By encoding human standards into automated checks as you go, you never have to leave the same review comment twice.

Communication Engineering: Project Glossaries and ADRs

Coding agents are heavily influenced by the code they inspect and the language used to prompt them. To ensure predictable output, we must engineer their communication environment.

Skills such as grill-with-docs and wayfinder establish a unified domain glossary, map future design choices, and maintain Architectural Decision Records (ADRs). When the agent shares the exact domain vocabulary and architectural intent of the human team, miscommunications evaporate and generated code fits the system naturally.

4. Strict Quality Gates: The Brakes in Action

As Robert C. Martin (“Uncle Bob”) has emphasized in his discussions on agentic pipelines, real speed can only be achieved by radically shrinking review effort down.

Prompt instructions alone are fragile. Large Language Models (LLMs) suffer from context drift, and agents readily forget soft guidelines as context windows expand. To prevent agents from producing architectural rot, we must translate our engineering standards into deterministic, executable quality gates.

If any quality gate fails, the agent is blocked. It cannot hand the PR over to a human reviewer; it must stay in its execution loop and continue iterating until every check is green.

The Automated Quality Gatekeeper Pipeline

The Essential Gates for Agentic Engineering

  1. Foundational Static Hygiene: Clean compilation, strict static type checkers, and linters configured with zero tolerance for warnings.
  2. Rigorous Automated Testing and Mutation Testing: Basic unit tests with high line coverage can easily give a false sense of security. Mutation testing introduces deliberate faults into the code to verify that the tests actually catch bugs, ensuring that test assertions are meaningful.
  3. Architectural Dependency and ADR Drift Checks: Agents naturally look for the shortest path to make a test pass, which often means taking lazy shortcuts across architectural boundaries. Automated dependency checkers (such as ArchUnit or Dependency Cruiser) enforce layer boundaries and prevent circular dependencies. Similarly, drift checkers ensure code changes stay consistent with documented Architectural Decision Records (ADRs).
  4. The CRAP Metric Guard: Propagated by Uncle Bob for AI agent workflows, the Change Risk Anti-Patterns (CRAP) metric combines cyclomatic complexity with test coverage:
CRAP(m) = comp(m)^2 * (1 - cov(m) / 100)^3 + comp(m)

In this formula, comp(m) represents the cyclomatic complexity of method m, while cov(m) is its percentage test coverage. When complexity is low (for example, comp = 1), the CRAP score is simply 1.0, regardless of coverage. But as complexity rises, the squared term amplifies the score unless test coverage is exceptionally high.

Enforcing a strict threshold (such as CRAP <= 8) creates a powerful automated brake. An agent that generates a convoluted, multi-branch method is forced by the gatekeeper to either simplify the code or write exhaustive test coverage for every branch before a human ever looks at it.

  1. Enforcing Deep Modules: Checking that the codebase adheres to the principle of deep modules (as defined by John Ousterhout in A Philosophy of Software Design): modules that provide simple, stable interfaces while hiding complex internal implementations. This ensures high cohesion and low coupling across the system.

5. Why This Matters: Architecture Directly Multiplies AI Speed

When quality gates are automated and diffs are reviewed pedagogically, human reviews can concentrate on what genuinely matters: system architecture and behavioral specifications.

Clean architecture is not a cosmetic preference. In an agentic environment, architecture directly dictates the speed, accuracy, and cost of your AI agents.

Empirical Evidence: Code Health and Agent Performance

Recent empirical research confirms that software architecture and code health are direct prerequisites for effective AI engineering:

Key Study:

  • Paper: Code for Machines, Not Just Humans: Quantifying AI-Friendliness with Code Health Metrics (Markus Borg, Adam Tornhill et al., 3rd Association for Computing Machinery and Institute of Electrical and Electronics Engineers (ACM/IEEE) International Conference on AI Foundation Models and Software Engineering, FORGE 2026 and CodeScene Whitepaper).
  • Empirical Findings: In a large-scale benchmark examining 5,000 real-world programs and six frontier Large Language Models (LLMs), researchers discovered that unhealthy code (marked by low cohesion, high complexity, and bumpy road code smells) increases the risk of AI-introduced defects by at least 60%. Furthermore, unhealthy code causes agents to burn up to 50% more tokens in failed reasoning loops and hallucinated fixes.
  • The Buffer Effect: Conversely, modular code with high cohesion acts as a protective shield. It reduces human review effort by more than a third and enables coding agents to complete complex tasks on the first attempt.
  • Complementary Reading: Uncle Bob on Why Hardcore Technical Focus Still Matters Big Time (Product Engineers Podcast, Sep 2026), detailing how deterministic feedback loops allow engineers to retain total technical control without reviewing every line of AI-generated implementation code.

When modules are deep, decoupled, and guarded by deterministic quality gates, an AI agent requires minimal context to solve a problem correctly. Architectural discipline is not obsolete in the era of AI: it is the primary engine of sustainable agentic velocity.

Summary

The solution to the reviewing problem in AI engineering is not to read faster or rubber-stamp massive diffs. The solution is to build a balanced system:

  1. Install the Brakes First: Build deterministic quality gates (linters, mutation tests, architectural dependency rules, and CRAP score limits) before widening agent autonomy.
  2. Align Proactively: Use pre-build grilling sessions, vertical slices, and tracer bullets to keep tasks focused.
  3. Score by Blast Radius: Classify PRs into one-way doors (security, data loss, irreversible actions) and two-way doors (isolated, reversible changes). Automate two-way merges and reserve human review for high-blast-radius decisions.
  4. Never Leave the Same Comment Twice: Compound your engineering standards by converting reviewer feedback into automated linter checks and rule files.
  5. Pay Down Cognitive Debt: Use Geoffrey Litt’s explain-diff skill to turn raw diffs into interactive learning documents with diagrams and quizzes.
  6. Review Golden Specs: Spend human attention on black-box behavioral contracts, trusting automated gates to verify internal implementation details.

By building brakes first, you earn the confidence to hit the accelerator, shipping higher quality software faster than ever before.