Uncle Bob's Code Validation

The Problem with AI-Generated Code

AI agents and coding copilots can produce hundreds of lines in seconds. The bottleneck shifts from writing code to validating it — and line-by-line review doesn't scale. Robert C. Martin ("Uncle Bob"), author of Clean Code and the SOLID principles, argues that when code is generated at machine speed, human review must move up a level: from reading lines to enforcing objective, automated metrics as CI/CD gates that the AI itself must pass before its code is accepted.

"The code only merges when the metrics pass. Cyclomatic complexity, coverage, dependency direction — these are not suggestions. They are the gate."

The Five Validation Gates

The CRAP Score — Composite Risk Metric

Uncle Bob has referenced the CRAP score (Change Risk Anti-Patterns) as a practical composite metric. It combines cyclomatic complexity and test coverage into a single risk number per function: a complex function with low coverage scores much higher (worse) than a simple or well-tested one.

# CRAP(f) = CC(f)² × (1 - coverage(f))³ + CC(f)
# CC = cyclomatic complexity, coverage = test coverage fraction
#
# Interpretation:
#   CRAP ≤ 5   → low risk
#   5 – 10     → moderate risk, review required
#   > 10       → high risk, must refactor before merge
#
# Examples:
#   CC=2,  coverage=0.95  → CRAP ≈ 2.0  ✅
#   CC=10, coverage=0.50  → CRAP ≈ 22.5 ❌ refactor
#   CC=10, coverage=1.00  → CRAP = 10   ⚠️  still borderline

Python: radon cc -s gives CC per function; combine with coverage.py to compute CRAP. Some CI plugins (e.g. SonarQube) report CRAP out of the box.

The AI-Code Validation Pipeline

The recommended workflow lets the AI agent iterate on its own output until it passes objective gates, then hands off to a human reviewer who focuses on architecture, security and business intent.

Prompt: Asking the Agent to Self-Correct

When a gate fails, feed the metric report back to the agent with explicit targets. This closes the loop and often resolves issues without human intervention.

"""
Analyze this module and apply the following corrections:

1. Reduce cyclomatic complexity to ≤ 4 per function. Break large functions into
   smaller, single-responsibility ones.

2. Increase test coverage to ≥ 90%. Add missing test cases for uncovered branches.

3. Add or strengthen tests until the mutation score is ≥ 80%. Focus on:
   - Boundary conditions (off-by-one, empty inputs, null values)
   - Business logic branches (each if/else path)

4. Enforce the Dependency Rule: domain/business-logic code must NOT import
   framework, database or UI modules. Introduce abstractions (interfaces/protocols)
   where needed.

5. Keep all functions under 20 lines. Split longer ones by responsibility.

Preserve all existing public behaviour and document any architectural changes.
"""

Tooling Reference

GitHub Actions Example (Python)

name: Code Quality Gates
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint
        run: ruff check . && ruff format --check .

      - name: Tests + Coverage
        run: |
          pytest --cov=src --cov-fail-under=90 --cov-report=term-missing

      - name: Cyclomatic Complexity
        run: |
          radon cc src/ -n B --show-closures
          # exits non-zero if any function scores B or above (CC > 5)

      - name: Dependency Rules
        run: lint-imports
          # enforces rules in .importlinter config

      - name: Mutation Testing
        run: mutmut run && mutmut results
          # fail if surviving mutants exist

What Metrics Don't Catch — The Human Layer

Best Practices

Related Topics