3 Keeping Specs Alive

Authoring a specification in spec-driven development is valuable because it creates a durable place where human intent and agent execution can meet. A good spec helps the team and the AI align on what should be built, how success will be judged, and which constraints must hold, but that value lasts only if the spec continues to reflect the system. When changes are made directly in code or when the spec is left behind, the team loses a reliable source of truth and future changes become harder to guide.

The chapter explains that stale specs usually come from repeated, locally convenient shortcuts: bypassing the spec for small fixes, accepting vague requirements, or failing to capture key decisions in enough detail. It identifies four places where intent can be lost: during the conversation that surfaces the idea, in the spec format that captures it, in the construction of the implementation, and in the verification that proves the work is done. Each kind of gap calls for a different repair, such as improving the dialogue, strengthening the specification format, encoding architectural constraints, or requiring deterministic evidence before completion.

Keeping specs alive means treating these gaps as feedback for improving the workflow, not just the code. The chapter argues for a governance loop that attributes each escape to the point where intent was lost, then updates the process so the same problem is less likely to recur. It also distinguishes between control authority and fidelity: a living spec must both drive change and accurately represent the system. Tools and practices should therefore support standing context, reasonable granularity, regeneration from the spec, and lightweight but effective verification, so the specification remains the easiest and most trustworthy place to express change.

When there are gaps between the agent-generated implementation and the intent articulated in our specifications, we face a choice between improving the specification and regenerating the implementation, or bypassing the specification and changing the code directly through ad hoc prompts.

Intent can be lost as an idea moves from human intent to specification, implementation, and validation.

Implementation gaps should feed back into the part of the SDD workflow where intent was lost.

The SDD governance operating loop involves observing gaps between intent and implementation and correcting them by revising the specification and regenerating the implementation. We then attribute the gap in the specification to where the intent was lost in the SDD workflow to improve it, and we confirm the improvement is working when the same class of gap stops recurring.

How alive a specification is depends on the control authority and fidelity.

Taxonomy of specification styles based on structure, location, granularity, and organization

• Specifications go stale when implementation changes bypass them. A direct fix may solve the immediate problem, but it moves intent into code, prompts, review comments, or memory, rather than returning it to the durable specification.
• Implementation gaps are feedback about the SDD workflow. A gap should first be corrected in the specification, but recurring gaps should also improve the workflow that allowed the intent to escape.
• Intent can be lost during surfacing, capture, construction, or verification. Each kind of loss requires a different repair, such as better questions, richer formats, stronger construction constraints, or deterministic evidence.
• Thorough specification does not mean repeating every concern in every feature spec. Recurring guidance should move into standing context, skills, hooks, checks, and project-level constraints so the workflow stays precise without creating markdown mountains.
• SDD governance should attribute deviations to the point where intent was lost. The purpose is not to label failures, but to make sure each observed gap improves the right part of the Intent Harness.
• A specification is alive when it has both control authority and fidelity. It must drive change and faithfully represent the system, so the team and the agent can safely use it as the primary control surface for future work.

FAQ