The Right Amount of Spec for Agentic Development
Central idea
Agentic development needs enough specification to make correctness testable, but not so much stale prose that agents must reconcile competing sources of truth.
Summary
Cheap implementation does not make intent or correctness cheap. Missing specification returns as repeated clarification, review, testing, and correction, while exhaustive prose creates its own drift and context cost. The useful middle combines structured intent, examples, nongoals, failure behavior, and executable checks. Specifications also need adversarial review: another pass should search for contradictions, ambiguous terms, hidden dependencies, and ways an implementation could satisfy the text while violating its purpose. Multi-agent handoffs require stronger contracts because one misunderstanding becomes the next agent's assumed truth. As working interfaces and tests grow, detailed build prose should shrink.
Key ideas
Optimize total cost
A short prompt may start quickly yet cost more overall when human reviewers repeatedly reconstruct missing intent.
Review the specification adversarially
A coherent implementation can faithfully encode an ambiguous, inconsistent, or incomplete spec.
Retire prose as executable truth grows
Keep rationale, nongoals, safety constraints, and external contracts; remove descriptions that merely restate current code.
Choose specification depth by risk
State the goal, assumptions, and nongoals.
Add concrete observable acceptance examples.
Name edge cases and failure behavior.
Turn stable claims into executable checks.
Strengthen contracts across agent or team handoffs.
Remove stale build prose as code becomes authoritative.
Why it matters now
As implementation accelerates, ambiguity can propagate into convincing code before people notice it. Specification and verification become primary engineering work.
Continue with the original
This short version preserves the main argument. Follow the source for the complete talk, article, or book.