Review the Spec, Not the Diff: How AI Changes the Way We Build Software — mkdshare.DEV

Something quietly broke in how we build software, and most teams have not adjusted to it yet. For decades the safeguard that kept code honest was review at the end: a person read the diff before it merged. AI did not make that safeguard better or worse. It made it impractical at the scale we now produce code. What is replacing it is a different shape for the whole lifecycle, and it is worth understanding before it arrives by default.

The shift fits in one line:

Review the spec heavily, the code lightly.

It sounds like a corner being cut. It is the opposite. It is what rigor looks like once a machine, not a person, is doing most of the typing.

One clarification before going further, because the word spec is overloaded. The spec this piece cares about is the technical one: the proposed approach and how the change will be built. It is not the product spec — the brief that decides what to build and why. Product requirements are the input to this step, not its subject. The document under review is the engineer's plan for satisfying them, and that technical plan is what gets read heavily before any code exists.

The thing that broke

Writing code used to be the slow and expensive part of the job. Review existed to catch the mistakes people made while doing that slow work, so it sat at the end, right before merge. It worked because code arrived at roughly the speed a person could read it. The producer and the reviewer ran at the same pace.

AI breaks that balance. Code now gets produced far faster than anyone can read it line by line. Writing got cheap and the volume went up, so reading all of it got more expensive, not less. The reviewer can no longer keep up with the producer, and no amount of discipline closes a gap that is growing by orders of magnitude.

WHERE THE COST LIVES

BEFORE — humans write the code<br>───────────────────────────────────────────────<br>spec ░░░<br>build ████████████ slow: writing is the bottleneck<br>review ██████████ feasible: code arrives at reading speed

NOW — AI writes most of the code<br>───────────────────────────────────────────────<br>spec ██████████ invest here, up front<br>build ░░░ fast and cheap<br>review ████████████████ more code, arriving faster than<br>anyone can read it, so reviewing<br>every line by hand costs more than<br>before, not less.

This is the part people misread. Manual code review did not get cheaper. It got more expensive, and trying to read every line by hand is the thing that no longer fits. So the effort moves to where a small amount of human attention still changes the outcome: the decision about what to build and how to structure it, made before any code exists.

A wrong approach caught in a spec is a five-minute edit. The same approach caught after a pile of generated code already exists is a day of rework, or it never gets caught at all because the review queue is hopeless. The leverage moved to the front of the process because that is the last point where reviewing a little still covers a lot.

The shape the lifecycle is taking

When you follow that logic through, the lifecycle reorganizes itself. The center of gravity becomes the spec and its review. Everything after exists to make that early decision pay off.

┌─────────────────────────────────────────────────────────────┐<br>│ THE EMERGING LIFECYCLE (7 steps) │<br>└─────────────────────────────────────────────────────────────┘

1. SPEC A short TECHNICAL spec: the problem and<br>│ why in a line or two, then the proposed<br>│ approach — how the change will be built.<br>│ The engineering plan, not the product brief.<br>2. SPEC REVIEW ◀══════ ★ THE MAIN QUALITY GATE ★<br>│ A peer reviews the technical spec BEFORE<br>│ any code. Align on the approach, kill wrong<br>│ ideas while they're cheap to change.<br>3. BUILD Implement against the approved spec.<br>│ AI does most of the typing. A human<br>│ owns and understands every line.<br>4. ACCEPTANCE CHECK (only if there's UX to try)<br>│ ··· optional Someone tries the feature and confirms<br>│ it does what the spec intended. A check<br>│ on outcome, not on code.<br>5. SHIP Automated review runs on everything.<br>│ Human review only for high-stakes<br>│ changes ↓<br>│ ┌─────────────────────────────────┐<br>│ │ HIGH-STAKES? → human review │<br>│ │ required before merge │<br>│ └─────────────────────────────────┘<br>6. VALIDATE Confirm it works in staging, then in<br>│ production, before announcing it.<br>7. ANNOUNCE Tell people once it is validated.

The steps matter less than the move underneath them: the heavy human gate shifts from the end of the process to the beginning, and from the code to the intent.

Two reviewers, not one

The reason this is safe and not reckless is that review does not disappear. It splits in two, by what each kind of reviewer is actually good at.

Machines review the code. Static analysis, security scanning, dependency checks, and tests run on every change, every time, with no exceptions. This is the only kind of review that scales with the...