Write Specifications That Preserve Judgment
A useful specification fixes invariants and evidence while leaving reversible implementation choices open. It is a decision boundary, not a screenplay. Separate outcome, invariants, examples, non-goals, and proof. Mark decisions as locked, bounded, or delegated. Preserve agent judgment where choices are cheap and reversible. Require human checkpoints where consequence or public behavior changes. An underspecified task asks an agent to guess the system. An overspecified task asks it to transcribe a design that may already be wrong. The useful middle is an executable contract: Locked: the agent must not choose. Use for public compatibility, authority, safety, irreversible cost, or a product commitment. Bounded: the agent may choose inside explicit limits. Use for search budgets, retry counts, allowed dependencies, or a known interface family. Delegated: the agent owns the choice and must explain it. Use for local structure, names, reversible refactors, and implementation details. Examples compress intent better than adjectives. “Helpful,” “robust,” and “production-ready” are not executable. A small set of normal, edge, failure, and forbidden examples gives both the builder and verifier something concrete. Examples do not replace invariants. One passing case cannot prove a universal safety rule. A unit test proves a local function contract. A wire test proves serialization and transport behavior. A browser journey proves an interface path. A replay set proves behavior over representative cases. An…
Write Specifications That Preserve Judgment: A useful specification fixes invariants and evidence while leaving reversible implementation choices open. It is…
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.