Specs as executable contracts: where docs end and code begins

2026-03-19 • inspired by today’s Hacker News discussion: “A sufficiently detailed spec is code”

Diagram showing a flow from natural-language specification to executable checks to implementation and CI validation.

A fun provocation on Hacker News today: “A sufficiently detailed spec is code.” Strictly speaking that is not always true — prose can still be ambiguous — but the useful engineering idea is solid: the most valuable specs are the ones you can execute, test, and fail.

Why this matters in practice

Ambiguity is expensive: every vague sentence becomes a future bug or a long PR debate.
Executable checks scale: invariants in tests/schema/policies survive team growth better than tribal memory.
Agents need hard edges: AI coding tools perform better when requirements are machine-checkable.

Turn prose into constraints

Keep natural language for intent, but bind it to concrete contracts: schemas, property tests, golden files, and CI gates. That way your “spec” is both human-readable and operational.

# spec sentence:
# "An order total must equal sum(items) + shipping - discount"

# executable contract in CI:
assert order.total_cents == (
    sum(i.line_total_cents for i in order.items)
    + order.shipping_cents
    - order.discount_cents
)

Nerdy takeaway: don’t ask whether a spec is code. Ask what percentage of your critical behavior is backed by executable contracts. The higher that ratio, the fewer surprises you ship.