Every team that has tried to manually keep an OpenAPI spec in sync with backend
source code knows how this ends. The spec is a planning document for week one and
a misleading artifact by week six. Contract tests get skipped. Fields get added
directly to handlers. Consumers find out from an
app crash. You find out from
alarms, bad reviews or churned customers.
AI coding agents can make drift worse, not better —
plausible code and spec-conformant code are not the same thing.
Read the full argument → Drift — Week-by-week 3 DIVERGENCES Week 01 — Spec written
POST /users → 201 { id, email, role }
GET /users/{id} → 200 { id, email, role }
Week 06 — Code in production
POST /users → 200 { userId, email }
GET /users/{id} → 200 { id, email, role,
createdAt, orgId }
// status wrong · field renamed · 2 added
The core failure mode
When the spec and the code are two separate artifacts manually maintained by the
same team, one of them is usually wrong.
Spec drift is the gap between what your spec says your API does and what your code
actually does. The gap starts small, grows invisibly, and gets discovered the
worst possible way.