When AI Writes the Code, Specifications Need an Exit Strategy
Markus Eisele · rss · 2026-08-17 source ↗ Reader 🖥️
Architecture Decision RecordsCoding AgentsContext EngineeringLegacy & Organizational ForgettingProgressive DisclosureSpec-Driven DevelopmentTest-Driven Development
When building software with AI coding agents, a specification should be a temporary 'change brief' that describes only the delta between current and intended behavior and expires at release, because durable system knowledge belongs in the native artifacts engineering already trusts to stay synchronized with the code — schemas, types, tests, policies, and telemetry — not in permanent prose that inevitably drifts and consumes an agent's finite context budget.
practical · argumentative — Builds toward a concrete operating model (the five-step process in 'A lighter operating model') via a sustained argument that specifications should be temporary and scoped to the current change, with durable knowledge relocated to native engineering artifacts. Uses diagrams, a brownfield case, and cited empirical studies as supporting evidence, but the intent is prescriptive throughout.
Structure
| Part | Role |
|---|---|
| Open a repository after six months of spec-driven agent work... | problem setup |
| Code is the fact | premise |
| Written words are for the delta | core proposal |
| The map will always be incomplete | elaboration |
| Keep durable facts in their native form | core mechanism |
| Judgment belongs in the workflow | supporting framework |
| Context is an engineering budget | cost argument |
| Modernization makes this obvious | extended case |
| Small specs still need real evidence | qualification, evidence |
| A lighter operating model | conclusion |
Key terms
- change brief Spec-Driven Development
The author's preferred replacement term for 'specification': a short-lived document that names outcome, non-goals, differing constraints, known unknowns, and acceptance criteria for one specific change — never a full description of the system. - delta
The difference between what the system currently does and what it should do after the change — the only thing the author believes is worth writing down in natural language. - durable fact / durable constraint
Information that must still be true and enforceable after a change ships — API shape, data invariants, security rules, architecture boundaries, reliability requirements, release rules — and therefore needs a permanent, checkable home. - native form
The artifact type — schema, type system, test, policy, telemetry signal, CI/CD rule — that software engineering already has and already knows how to keep synchronized with the running system, as opposed to a natural-language description of the same fact.
Propositions
- explicitAI-agent-driven spec workflows accumulate a 'second system' of Markdown files (requirements, designs, plans, review reports) that sits next to the code and drifts out of date even as the code itself changes quickly.conf: high
- explicitNatural-language specification is a weak mechanism for keeping agents synchronized with a codebase because it consumes context-window space, and agents drift attention toward the stronger signal (the actual code) once the two disagree.conf: high
- explicitcorroboratedCode is the ultimate, executable specification: once deployed, it is the actual behavior users and connected systems depend on, and even an unintended behavior can become a de facto contract simply by having run unchanged for years.conf: highsupports ←Presentation: From Retrieval to Reasoning: Building Production-Ready Agentic AI Systems with Knowledge Graphs · p8 — Shum reaches the same code-as-truth position from practitioner experience (code is what's real, driven to production); Eisele independently supplies the stronger de-facto-contract argument (an unintended behavior running unchanged for years becomes a binding contract) that Shum's talk does not itself make.
- explicitA change specification (a 'change brief') should contain only a short, bounded list: intended outcome and non-goals, known unknowns needing human judgment, affected system boundaries and authoritative interfaces, constraints that differ from current behavior, and acceptance criteria for the risky path.conf: highextendsWhy AI Coding Agents Still Need Clear Specs · p8 — Sharpens the earlier piece's task-dependent 'sweet spot on a completeness curve' into an operational rule: scope every spec to the delta of the current change, and discard the rest after release.
- explicitcorroboratedOnce a change ships, most of its specification should be discarded; only durable facts should be promoted, and they should be promoted into native artifacts (schemas, types, tests, policies, telemetry) rather than kept as permanent prose.conf: highrefinesThe Intent Debt · p25 — Agrees AGENTS.md/ADRs/specs are legitimate substrates for intent, but narrows their role to only the residual facts with no native-artifact home — most durable facts should move to schemas/types/tests/policies/telemetry instead of staying in prose.supports ←How we Claude Code · p13 — Supports the claim that durable system knowledge should be promoted into native, code-adjacent artifacts (schemas, types, tests) rather than kept as permanent prose — the schema/fixtures/invariants verification framework is a concrete, worked instance of exactly that kind of native artifact.
- explicitcorroboratedExhaustive upfront specification — the 'waterfall' pattern — recurs when agents generate the initial spec themselves: it looks controlled and complete but is administratively complete and engineering-useless, and it raises the human review burden rather than lowering it.conf: highsupportsIt Ain't Broke: Why Software Fundamentals Matter More Than Ever · p14 — Both treat large, agent-generated specification-first workflows as vibe coding in different clothing: the underlying code, not the spec prose, remains the real engineering artifact.supports ←Kent Beck's Post · p1 — Both identify exhaustive upfront specification as the specific failure mode — Beck calls the underlying assumption 'bizarre'; the article independently documents that this 'waterfall' pattern recurs and raises review burden rather than lowering it.
- explicitestablishedDiscovery of missing information continues throughout implementation — reading a module, building a prototype, running a test, or inspecting production data all surface unknowns that were invisible at the start — and the change brief remains part of this ongoing loop rather than a document fixed before work begins.conf: highsupports ←Kent Beck's Post · p1 — Beck's one-line critique (SDD wrongly assumes no learning during implementation) converges with this article's more developed claim that discovery continues throughout implementation and a specification should remain part of an ongoing loop rather than fixed before work begins.supports ←Presentation: From Retrieval to Reasoning: Building Production-Ready Agentic AI Systems with Knowledge Graphs · p7 — Both observe that discovery continues throughout implementation and must be fed back into the working spec/context rather than treated as complete at the start.
- explicitThe amount of process and specification a change needs should scale with its risk and unfamiliarity — a small familiar change can go almost straight to implementation, while an architectural or high-consequence change needs explicit human alignment and stronger evidence — rather than every change following the same fixed ceremony.conf: high
- explicitOversized specification material costs more than the time to write it: it competes with the code and evidence an agent needs for the current decision inside a limited context window, so the larger cost is degraded attention, not token spend.conf: highsupportsYour AGENTS.md might be a big problem · p4 — Same context-budget mechanism (every rule/instruction costs attention on every request) applied here to specifications and change briefs generally, not only to AGENTS.md rules.supportsAgent Skills · p11 — Shares the token-cost premise behind progressive disclosure — oversized specification material degrades agent attention the same way oversized skill/context material does.
- explicitIn legacy/brownfield modernization, code — not accumulated spec-prose — is the authoritative record of past decisions; an agent that treats every existing code variant as a target specification will faithfully translate defects and obsolete architectural patterns into the new system unless a human applies explicit classification judgment (preserve, verify, redesign, or remove).conf: highextendsForskning på digitalisering 2026 uke 19 · p9 — Agrees LLMs can refactor legacy code shaped by obsolete constraints, and adds an explicit judgment framework (preserve/verify/redesign/remove) for deciding which legacy behavior should actually survive the translation.
- explicitIndependent, non-self-referential verification (generated tests that filter proposed fixes, adversarial critic review, targeted repair of identified defects) catches requirement and specification problems more reliably than simply writing a longer or more detailed specification, per the cited studies on ambiguity repair (~31% improvement), SWT-Bench (doubled precision), and natural-language-to-TLA+ translation (~27%/9% syntactic/semantic correctness).conf: high
- implicitThe article assumes engineering teams already possess, or can readily build, sufficiently expressive and trustworthy native artifacts — real schema contracts, meaningful test coverage, working telemetry, enforced policies — to receive 'durable facts'; for a team whose native artifacts are themselves thin, absent, or untrusted, moving facts out of prose has no better home to go to.conf: medium
- implicitThe article assumes the triage between 'durable' and 'temporary' information at the moment a change ships is straightforward and gets performed correctly and consistently, without specifying who performs it or what happens when a fact is wrongly discarded as temporary and later turns out to matter.conf: medium
Arguments
Specifications for agent-driven development should be scoped to the current change's delta and treated as temporary, not as persistent whole-system documentation. strength: medium
Explicit premises:
- Code, once in production, is the actual executable behavior that users and connected systems depend on, so it functions as the real, primary specification.
- Agents cannot infer future policy changes, upcoming feature requests, or regulatory specifics from the codebase alone — that context has to come from somewhere else, but only for the change at hand.
- Exhaustive, complete specifications create administrative completeness without engineering value, and are expensive to produce, review, and keep synchronized with a fast-changing codebase.
Implicit premises:
- The set of facts genuinely needed to decide and review a specific change is a small, bounded set (the article's five-item list), reliably distinguishable in practice from facts belonging to the system's permanent record.
- Reviewers and agents can tell, at the point a change ships, which facts from the change brief must be promoted to a native artifact and which can simply be discarded.
Inferences:
- This implies a team could, in principle, audit 'specification debt' (stale Markdown vs. current code) as a trending health metric — something the article's own opening image gestures at but never operationalizes into a measurable practice.
Durable knowledge about a system should be encoded in native engineering artifacts (schemas, types, tests, policies, telemetry, and — sparingly — short decision records) rather than kept as standing prose specification. strength: medium
Explicit premises:
- Software engineering already has better, checkable representations for most durable facts: API compatibility in schemas/contracts, data invariants in types/constraints, security rules in access policies, architecture boundaries in module structure and tests, reliability in load tests/SLOs/telemetry, release rules in CI/CD policy.
- A failed schema check or alert forces a fix and gets handled; a stale paragraph in an old design folder does not — native artifacts are self-enforcing in a way prose is not.
Implicit premises:
- Every category of durable fact the article lists already has an available, sufficiently expressive native artifact to receive it — no significant category of durable system knowledge lacks a native, checkable home.
- The ongoing cost of building and maintaining those native artifacts is lower, or at least more sustainable, than the cost of maintaining prose documentation — a direct comparison the article never runs.
Inferences:
- Teams lacking mature native artifacts (no schema contracts, thin test suites, no telemetry) would, by this argument's own logic, still need prose specification as a stopgap — an artifact-maturity precondition the article never names explicitly.
Narratives
- Open a repository after six months of spec-driven agent work and find a 'second system' next to the code — requirements, research notes, designs, plans, and review reports — where the last documentation update is weeks old even though the code changed significantly last Tuesday.
→ Makes the central problem (spec/code drift under agent-driven development) vivid and concrete before any argument is made, setting up the whole essay's motivation. - The author recalls reading folders full of paper over a weekend to prepare for a new project starting Monday — the pre-AI waterfall era of exhaustive requirement documents, high/low-level designs, and architecture decision records for everything.
→ Grounds the critique of exhaustive, agent-generated specification in lived pre-AI experience, arguing the failure mode (administratively complete, engineering-useless) is not new and that agents are simply recreating it faster. - A brief, deliberately mundane example: a specific export job runs every night for only one customer, for a reason nobody wrote down.
→ Illustrates the kind of tacit, business-specific context (regulatory retention periods, one-off exceptions) that can only come from a human, not from reading the codebase — motivating why a change brief still needs some human input even under a code-is-the-fact view. - Dexter Horthy's retrospective on the Research-Plan-Implement workflow: plans grew to 1,000 lines and were reviewed almost like compiler output; implementations still drifted from the approved plan, forcing engineers to reconstruct decisions from the code anyway, and much of the time saved on generation was spent cleaning up low-quality output.
→ Provides external, cited validation that oversized planning/specification artifacts fail in exactly the way the article predicts — large specs don't prevent drift, they just relocate the reconstruction work to after the fact.
Questions addressed
- ✅ Should teams maintain a persistent, comprehensive natural-language specification of the system, keeping it in sync with the code as agents build it?
No — most of a change's specification should be discarded once the change ships; only a small subset of durable facts should be promoted, and only into native artifacts, never kept as permanent prose. - ✅ If not an exhaustive system description, what should a specification actually contain?
A short, bounded list: intended outcome and non-goals, known unknowns needing human judgment, affected boundaries/authoritative interfaces, constraints that differ from current behavior, and acceptance criteria for the risky path. - ✅ Does keeping specifications small amount to returning to loose-prompt or vibe-coding with no real verification?
No — small specs still need independent, non-self-referential evidence (targeted defect repair, generated tests that filter fixes, adversarial review) scaled to the consequence of being wrong; the cited studies show this kind of verification, not longer specs, is what actually catches problems. - ⭕ Who or what decides, at the moment a change ships, which facts are 'durable' and must be promoted to a native artifact versus which can be safely discarded as temporary reasoning — and what happens when that triage is wrong?
Gaps
- incompleteThe article never addresses teams whose native artifacts are themselves weak or absent (no real schema contracts, thin or no test suite, no telemetry). For them, 'keep durable facts in their native form' recommends a home that doesn't yet exist, and the article gives no guidance on sequencing — build the native artifact first, or use prose as a legitimate transitional stopgap while it matures.
Read next: Look for material on artifact/observability maturity models, or on how teams bootstrap schema, test, and telemetry discipline in codebases that currently have none, to test whether prose specification is a legitimate transitional artifact rather than pure waste. - incompleteThe article asserts that its short, fixed change-brief checklist (outcome, unknowns, boundaries, constraints, acceptance criteria) is sufficient to decide and review a delta, but never explains who validates that the checklist was filled in correctly and completely for a given change — the exact 'spec validation' step the author's own earlier companion piece raised explicitly is not revisited here.
Read next: Read alongside extract-eisele-ai-coding-agents-need-clear-specs, whose 'spec validation' step (checking a spec for internal consistency, completeness, testability before an implementation agent runs) directly addresses the gap left open here. - uninformedThe mapping of durable-fact categories to native artifacts (API shape to schemas, data invariants to types, security to policies, architecture to tests, reliability to telemetry, release to CI/CD) treats each category as if it maps cleanly one-to-one, without engaging cases where a single durable fact spans several categories at once (e.g., a business policy that is simultaneously a data invariant, a security rule, and a UX constraint), or with prior literature on the difficulty of converting tacit organizational knowledge into formal artifacts.
Read next: Knowledge-elicitation and requirements-engineering literature on tacit-to-explicit knowledge conversion (e.g., Nonaka & Takeuchi's SECI model), and this corpus's own organizational-forgetting material (extract-3-ways-ai-can-free-orgs-from-legacy-workflows) on how depersonalized evidence surfaces facts nobody wrote down anywhere. - incompleteThe empirical studies cited (ambiguity repair improving results ~31%, SWT-Bench doubling precision, TLA+ translation reaching only ~27%/9% syntactic/semantic correctness) support 'small specs plus independent verification' in general, but none of them actually measures this article's central claim — that treating specs as temporary and promoting only durable facts to native artifacts reduces total cost or drift compared to alternative approaches.
Read next: Look for empirical work directly comparing 'temporary change-brief' workflows against both prose-heavy and specless workflows on drift, rework, or maintenance cost — the same empirical gap already flagged in extract-eisele-ai-coding-agents-need-clear-specs#g1 for the U-shaped cost curve, now recurring for this piece's 'expire the spec' claim.
Related documents
- Forskning på digitalisering 2026 uke 19
- The Intent Debt
- [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero
- Coding Agent Development Workflows
- Why did Martin Fowler invite 60 engineers to a ski resort?
- Agentic AI and Code Reviews
- Why AI Coding Agents Still Need Clear Specs
- No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer
- Presentation: From Retrieval to Reasoning: Building Production-Ready Agentic AI Systems with Knowledge Graphs
- Your AGENTS.md might be a big problem