Phase 1: Spec-Driven Development · 45 min · Git · GitHub Actions · Python

Spec-Code Drift and How to Prevent It

Drift isn't a bug you fix later — it's invisible by construction until something blocks the merge that creates it.

Hiring signal: Implementing an actual CI-style drift gate — not just describing the concept — is direct evidence you can build the enforcement mechanism a team would need, not just recite the theory in an interview.

What you will learn

Explain silent spec-code drift as a structural failure mode, not an occasional mistake
Describe how a drift gate makes spec-code divergence a blocking merge condition instead of an invisible one
Justify the same-commit contract update rule and why 'update the spec later' defeats the gate's purpose
Implement a real, git-based drift gate that detects business-logic changes made without a corresponding spec update

Introduction

Spec-Code Drift and How to Prevent It

A payments team's spec says refunds are capped at the original transaction amount. Eighteen months and eleven refactors later, an edge case for partial-shipment orders was patched directly in the code — a quick fix, reviewed and merged like any other PR — that allows a refund up to 110% of the original amount to cover a specific shipping-adjustment scenario. Nobody updated the spec. Nobody was supposed to remember to; it just wasn't part of anyone's checklist. Nine months after that, a new engineer, onboarding onto the team, reads the spec, sees "refunds capped at 100% of original amount," and builds a fraud-detection rule that flags anything above that threshold as suspicious — which now fires constantly on the legitimate shipping-adjustment case the spec doesn't know exists, because the spec has been quietly wrong for nine months and nothing ever told anyone.

This is silent drift, and the word "silent" is doing real work in that name. Research on this exact failure mode (the Spec Growth Engine paper, arXiv 2606.27045) identifies it as one of two structural failure modes specific to AI-assisted development: "code evolves, spec doesn't, divergence becomes invisible until it's costly." The cost here wasn't the original quick fix — that was a reasonable patch. The cost was eighteen months of a spec silently lying to anyone who trusted it, with no mechanism that would ever have surfaced the lie before it caused a real problem.

This particular incident also illustrates why drift compounds instead of staying flat. The first divergence (110% refund cap, undocumented) was harmless in isolation — a reasonable business decision, correctly implemented, just not recorded anywhere the spec could see. The damage came from a second, independent piece of work built on top of the wrong assumption, by someone with no way to know it was wrong. Drift doesn't announce itself at the moment it's created; it waits, quietly, for the next person who trusts the spec, and the cost lands on them instead of on whoever created the gap.

Why this is structural, not a discipline failure

It's tempting to conclude the payments team just needed better discipline — "everyone should remember to update the spec." That framing misses the actual mechanism. Discipline-based fixes rely on every single person, on every single change, remembering an extra step that has no immediate consequence if skipped. The refactor that broke the spec worked fine, passed review, and shipped — skipping the spec update cost nothing at the time it was skipped. The cost only appeared nine months later, attached to a completely different piece of work (the fraud rule), built by a completely different person, who had no way of knowing the spec they were reading had gone stale. When the cost of a mistake is separated from the mistake by months and by which person experiences it, "just be more careful" doesn't scale. You need something that makes the skip itself impossible, or at least visible, at the moment it happens.

The drift gate's actual job
A drift gate isn't there to catch bad specs — it's there to make "I'll update the spec later" structurally unavailable as an option. If a pull request touches business logic and the corresponding spec file isn't touched in the same PR, the gate blocks the merge. Not a warning, not a Slack reminder — a blocked merge, the same severity as a failing test.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers The same-commit contract update rule, What a drift gate actually checks, Build It — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.