Day 58: Spec-First: OpenAPI Remains Source of Truth

Agents love inventing /v2/magic routes that do not exist. Spec-first means OpenAPI (or protobuf) remains source of truth, tests own the contract, and agents may only propose changes as patches to the spec — never as sneaky handler-only code.

⚡ TL;DR: CI fails if handlers expose routes missing from OpenAPI, or OpenAPI lists ops without handlers. Agents edit openapi.yaml + generate types; humans review contract diffs.

Contract ownership

# ✅ generate → implement → test
npx openapi-typescript openapi/api.yaml -o src/gen/api.ts
pytest tests/contract --openapi openapi/api.yaml

# tests/test_contract_drift.py
import yaml
from app import create_app

def test_no_phantom_routes():
    spec = yaml.safe_load(open("openapi/api.yaml"))
    spec_paths = set(spec["paths"])
    app = create_app()
    app_paths = {r.path for r in app.router.routes}
    assert app_paths <= spec_paths, f"undeclared routes: {app_paths - spec_paths}"

Agent workflow for API changes

1. Intent: patch_openapi with JSON Patch ops
2. Regenerate clients
3. Implement handlers to match
4. Contract tests must pass

{
  "kind": "patch_openapi",
  "params": {
    "ops": [
      {"op": "add", "path": "/paths/~1invoices~1{id}/refund", "value": {"post": {"operationId": "refundInvoice"}}}
    ]
  }
}

❌ “Just add a FastAPI route; we’ll update the spec later” — later never comes, agents keep inventing.

Closing checklist

• [ ] OpenAPI as source of truth
• [ ] Drift tests in CI
• [ ] Agents patch spec first
• [ ] Generated types for handlers/clients
• [ ] Human review on contract diffs

Series navigation

Day 57: Coding Agents That Only Emit Intents · Day 59: Multi-Agent Eval: Task Suites, Not Vibes

Last updated September 11, 2026