AI Spec-Driven Development

1. What Spec-Driven Development Is

Spec-driven development is a feedback loop in which human intent is captured as repository artifacts before an agent changes the product. Those artifacts guide implementation, validation feeds discoveries back into them, and the final merge leaves both code and intent in a coherent state.

This is not an attempt to predict the entire system upfront. Good SDD deliberately uses small phases. A feature spec should be detailed enough to remove consequential ambiguity and small enough to revise without ceremony.

It also does not mean that the specification writes the software automatically. The spec improves the agent's context and makes its choices inspectable; engineering judgment is still required for architecture, security, performance, usability, and review.

Why it fits coding agents

An experienced teammate accumulates unwritten context over months. An agent session may start with none of it. Repository-level specifications act as shared, persistent memory:

• Humans can review product intent before paying the cost of implementation.
• Agents can discover constraints without relying on one giant prompt.
• Validation is agreed in advance instead of improvised after the code looks finished.
• A fresh agent can continue the work from files and Git history.
• Changes to scope become visible changes to the spec, not silent prompt drift.

The result is not perfect autonomy. It is better alignment, cheaper correction, and a much clearer audit trail.

2. A Small, Durable Spec Architecture

The workflow starts with two levels of documentation: a stable project constitution and a temporary-but-versioned packet for each feature.

specs/
├── mission.md
├── tech-stack.md
├── roadmap.md
└── 2026-08-15-feature-name/
    ├── requirements.md
    ├── plan.md
    └── validation.md

The project constitution

The constitution records decisions that should influence many features. It should be short enough that an agent can read it at the start of every planning task.

Explicit non-choices matter. “No ORM in the first release” or “do not add a client-side framework” prevents an agent from expanding the architecture simply because a familiar dependency would make one task convenient.

The feature packet

Each roadmap phase gets its own directory. Separating the three documents keeps three different conversations from collapsing into one:

A useful shorthand is: requirements describe what, the plan describes how, and validation describes proof.

3. The End-to-End Workflow

Stage 1: Interview before writing the constitution

Begin with the available stakeholder material: a README, product brief, issue list, meeting notes, or an existing application. Ask targeted questions before writing files. The most valuable questions cluster around three areas:

1. Mission: Who is the product for, which problem matters most, and what does success look like?
2. Technical boundaries: Which choices are fixed, which are preferences, and which remain open?
3. Delivery order: What is the first end-to-end slice that proves the stack and provides value?

The interview step is a guardrail against confident invention. If an unanswered question could materially change the feature, the agent should surface it before committing the assumption to code.

The roadmap should then decompose the product into thin, shippable phases. “Build the dashboard” is usually too broad. “Render the shared shell,” “show a read-only list,” and “add the first editable workflow” create clearer review and validation points.

Stage 2: Select one roadmap phase and isolate it

Choose the next incomplete phase, create a branch, and give the specification a dated directory. The date makes parallel or repeated efforts distinguishable; the feature name makes the history searchable.

git switch -c phase-2-agent-list
mkdir -p specs/2026-08-15-agent-list

The branch boundary is important. It lets the feature's spec and code evolve together, and it gives reviewers one coherent unit to compare against the roadmap.

Stage 3: Resolve scope, decisions, and context

Before drafting the feature packet, conduct a smaller feature interview:

• Scope: What data enters and leaves the feature? Which behaviors and states are included? What is explicitly deferred?
• Decisions: Which storage, API, validation, navigation, and UX choices need to be fixed now?
• Context: Which existing patterns, tone rules, compatibility needs, or operational constraints shape the work?

Grouped questions are efficient because the human can resolve product and engineering ambiguity in one pass. The agent should then cross-check the answers against mission.md and tech-stack.md.

Stage 4: Write the three-part feature contract

Write the requirements first. Separate in-scope behavior from out-of-scope work so “helpful” expansion is easy to detect. Record important decisions with their rationale, especially when the obvious implementation would violate the constitution.

Next, turn the requirements into numbered task groups. Good groups follow dependency order and end in something observable:

## Group 1 — Data
1. Add the migration.
2. Add typed queries.
3. Seed representative records.

## Group 2 — Presentation
4. Add the list component.
5. Cover empty and populated states.

## Group 3 — Route and navigation
6. Add the route.
7. Link it from the shared navigation.

## Group 4 — Verification
8. Add focused tests.
9. Run the repository's full validation commands.

Finally, write validation as observable evidence. Include exact commands where possible, expected user-visible behavior, failure cases, accessibility or tone checks, and the conditions required for merge.

Stage 5: Implement in task groups

The agent can now execute a bounded plan rather than infer the entire feature from scratch. Work through one task group at a time, run the closest relevant checks, and inspect the diff before moving forward.

This makes failures easier to localize. It also creates natural pause points for human review. For higher-risk work, commit by task group; for smaller features, keep the branch uncommitted until the full validation pass.

The plan is a guide, not a substitute for repository discovery. The agent must still inspect existing conventions, reuse established components, protect unrelated user changes, and avoid dependencies that the constitution does not authorize.

Stage 6: Validate against the declared evidence

Validation should be executed from validation.md, not summarized from memory. A practical validation ladder is:

1. Static checks: formatting, linting, types, schema validation.
2. Focused tests for the changed behavior.
3. The full regression suite.
4. Build or packaging checks.
5. Manual walkthroughs for user-visible behavior and edge cases.
6. Diff review against every requirement and out-of-scope boundary.

Record deviations honestly. “Tests pass” is not equivalent to “validation is complete” if the specification also requires a keyboard-only walkthrough or a real database migration.

Stage 7: Integrate, update, and replan

Once validation passes, update the roadmap, changelog, and any durable technical guidance discovered during the feature. Merge the branch only when the code and specifications tell the same story.

Then reconsider the roadmap. Delivered work often changes what should come next. Several tiny phases may now belong together; a newly discovered dependency may need an earlier spike; an MVP may be closer than the original sequence suggested.

Replanning is part of the workflow, not an admission that the first plan failed. The project constitution provides continuity while the roadmap adapts to evidence.

4. Keep Specifications and Code in Sync

The most important operational rule is simple: when the requirement changes, update the spec in the same branch as the code.

Suppose implementation reveals that a shared layout must be split into separate header, main, and footer components. There are three possible reactions:

• Change only the code. The spec immediately becomes misleading.
• Refuse the discovery because the plan did not predict it. The spec becomes bureaucracy.
• Review the change, update requirements and plan, adjust validation, then implement it. The spec remains useful.

The third option is living specification. The documents are authoritative enough to guide work but editable enough to incorporate what the team learns.

Global decisions must propagate

Some discoveries belong in one feature; others change the whole project. Adding responsive design or adopting a test framework, for example, should update tech-stack.md, relevant feature specs, current code, and validation—not just the latest prompt.

This propagation prevents a common form of drift where the newest feature follows one rule while older specs continue teaching agents another.

Specs are an interface between humans and agents

A good spec does not depend on one model's conversational memory. Another agent should be able to read the repository, understand the current contract, run the checks, and continue the work. That replaceability is a useful test of documentation quality: if changing agents destroys the workflow, critical context probably lives outside the repository.

5. Bringing SDD to an Existing Codebase

SDD does not require a greenfield project. For a brownfield system, the first task is reconstruction rather than invention.

1. Read the README, issue tracker, TODO files, package manifests, build configuration, tests, and recent history.
2. Infer the current mission and stack, but label assumptions and interview maintainers about the gaps.
3. Write a roadmap from unfinished work rather than pretending the existing product starts at phase one.
4. Create feature packets only for new or actively changing work.
5. Use tests and current behavior as evidence when documentation and implementation disagree.

Do not attempt to specify the entire legacy system in one pass. Capture stable boundaries, then improve the constitution as features expose missing context. This keeps adoption proportional to the work being done.

6. Turn Repetition into Reusable Agent Skills

Once a team repeats the workflow, the repeated procedure should become automation. The source course materials demonstrate this with reusable agent skills for feature specification and changelog generation.

A feature-spec skill can encode the mechanical parts:

• Find the next incomplete roadmap phase.
• Create a correctly named branch.
• Ask the scope, decisions, and context questions before writing.
• Read the constitution.
• Create the dated directory and three required documents.
• Enforce rules such as “no new dependency without approval.”

A changelog skill can inspect work since the previous merge and update a consistent project history. Similar skills can encode release checks, dependency reviews, database migration procedures, or documentation updates.

The right automation target is the procedure, not the product decision. A skill should remember how to interview and structure a spec; it should not silently decide what a user wants.

Keep the workflow portable

Prefer ordinary Markdown, repository scripts, and standard Git operations as the durable layer. Tool-specific commands can be convenient adapters, but the core artifacts should remain usable by a different coding agent—or by a human with no agent at all.

7. Common Failure Modes

The giant prompt

A single prompt mixes mission, architecture, feature scope, and validation. It is difficult to review, easy to truncate, and almost impossible to maintain. Split durable context by responsibility.

Specification theater

The repository contains polished documents, but implementation never reads them and review never checks them. Make the spec operational: point the agent to it, derive tasks from it, and validate against it.

Over-specifying implementation

A plan that dictates every function name before discovery can lock in weak assumptions. Specify behavior and consequential architecture; let routine implementation details follow repository conventions.

Validation written after the fact

Post-hoc success criteria tend to bless the existing solution. Write the observable contract first, then adjust it explicitly if a legitimate discovery changes the requirement.

Silent assumptions

An agent fills product gaps with plausible defaults. Some defaults are harmless; others change data retention, security, compatibility, or user experience. Use the feature interview to expose high-impact assumptions.

Specs that never change

Frozen specs drift away from reality. Update requirements, plan, and validation with the implementation whenever the team's understanding changes.

Specs for microscopic changes

Not every typo needs three files. Use the full workflow when ambiguity, risk, handoff cost, or multi-step implementation justifies it. A short issue plus a test can be enough for a trivial fix.

8. A Minimal Starter Kit

You can adopt the workflow without installing a framework. Add the three constitution files, choose one modest roadmap phase, and use the following compact feature templates.

requirements.md

# Feature Requirements

## Goal
What user or system outcome does this feature create?

## In Scope
- Observable behavior included in this branch

## Out of Scope
- Related work deliberately deferred

## Decisions
- Important choice and its rationale

## Constraints and Context
- Constitution rules and existing patterns that apply

plan.md

# Feature Plan

## Group 1 — Foundation
1. First independently verifiable task
2. Second task

## Group 2 — Behavior
3. Implement the user-visible slice

## Group 3 — Verification
4. Add or update tests
5. Run the declared validation commands

validation.md

# Feature Validation

## Automated
- [ ] Typecheck/lint command exits successfully
- [ ] Focused tests cover success and failure paths
- [ ] Full regression suite passes
- [ ] Production build succeeds

## Manual
- [ ] Primary workflow behaves as specified
- [ ] Empty, invalid, and failure states are usable
- [ ] Accessibility and responsive behavior are checked

## Definition of Done
- [ ] Every requirement is implemented or explicitly deferred
- [ ] Spec, code, roadmap, and changelog agree

Practical operating checklist

• Keep the constitution concise and read it before feature planning.
• Make roadmap phases independently reviewable and testable.
• Interview for scope, decisions, and context before writing the feature spec.
• State what is out of scope.
• Define validation before implementation.
• Update specifications when discoveries change the design.
• Run the checks; do not merely describe them.
• Merge spec and code as one coherent change.
• Automate repeated workflow steps without automating product judgment.

Conclusion

AI-assisted development becomes more reliable when the agent is not asked to infer the product from a transient conversation. A small project constitution supplies durable direction. A three-part feature packet turns one roadmap phase into an explicit contract. Predeclared validation makes completion measurable. Living updates keep the contract useful as implementation teaches the team something new.

The deeper benefit is continuity. The codebase becomes less dependent on one prompt, one developer's memory, or one agent. Intent, decisions, work, and evidence travel together through Git.

Start small: write the mission, technical boundaries, and next shippable phase. Specify one feature, validate it honestly, and refine the workflow from what you learn. That is enough to turn an AI coding session into an engineering process.