Methodology · Spec-Drivenemergingpartial

Spec-Driven Development

also known as SDD, spec-first development, Spec Kit workflow

Applies to: coding-agentagentsoftware-team

Tags: spec-drivencoding-agentspecification

Write the spec first and treat it as the source of truth; the code is what the agent generates from it. Start with a short constitution of standing principles, then specify what to build, plan how to build it, break the plan into agent-sized tasks, and only then let the agent implement. When requirements change you change the spec, not the code, and regenerate.

Methodology process overview

flowchart TD idea[Feature idea] --> con[Write constitution] con --> spec[Specify: what, who, why, flows] spec --> plan[Plan: stack + architecture] plan --> tasks[Break into agent-sized tasks] tasks --> impl[Agent implements from tasks] impl --> change{Requirements change?} change -->|yes| spec change -->|no| done[Shipped feature serving the spec]

Intent. Make the specification, not the code, the source of truth so an AI agent implements against a settled, reviewable description.

When to apply. Use this when an AI coding agent does the bulk of the implementation and you want control over what it builds. It fits greenfield features and well-scoped changes where the requirements can be pinned down up front. Don't apply it to pure exploration where you do not yet know what you want.

Example scenario

A small team adds a saved-search feature to an analytics product, with an AI coding agent doing most of the typing. Their old habit was to prompt the agent straight into code, which produced plausible files that missed half the edge cases. They switched to spec-driven development with Spec Kit. First they wrote a one-page constitution: TypeScript, their existing auth, no new datastore without sign-off. Then they specified the feature: who saves searches, what a saved search contains, how sharing works, and the empty and error states, all without naming a single function. They reviewed the spec and caught a missing rule about who can delete a shared search before any code existed. The agent then produced a plan that reused the existing search index, which they approved, and broke it into nine tasks. The agent implemented task by task. When product later changed sharing from per-user to per-team, they edited the spec and regenerated the affected tasks instead of hand-patching code, and the change stayed consistent across the feature.

Inputs

Feature idea — The thing to build, stated as an outcome a user wants, not as code.
Project constitution — The standing principles and constraints the project always honours: stack, style, non-negotiables.
Spec-driven tooling — A toolkit such as Spec Kit and an AI coding agent that can read specs, plans, and tasks.

Outputs

Feature specification — A reviewed document of what to build, for whom, why, and the core flows, free of implementation detail.
Technical plan — How the feature will be built: stack choices, architecture, and constraints derived from the spec.
Task list — The plan broken into discrete, agent-executable tasks.
Implementation — Code the agent generates from the tasks, which serves the spec rather than the other way around.

Steps (6)

Write the constitution
Record the standing principles the project always honours: stack, style, and non-negotiable constraints. This layer outlives any one feature.
Specify the feature
Describe what to build, who it is for, what problem it solves, and the core and edge flows. State behaviour, not implementation.
usesPre-Flight Spec Authoring
Plan the technical approach
Turn the spec into a plan: stack choices, architecture, and constraints. This is where the how lives.
usesPlan-and-Execute
Break into agent-sized tasks
Split the plan into discrete tasks an agent can pick up and finish, each with a clear done state.
Let the agent implement
The agent writes code to satisfy the tasks, plan, and spec that are already settled.
usesSpec-Driven Loop Spec-First Agent
Re-spec on change
When requirements change, edit the spec and regenerate the affected tasks rather than hand-patching the generated code.
usesHuman-in-the-Loop