spec-driven-development

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• write the spec first
• I want SDD on this
• spec this out before we build

What it does

spec-driven-development (SDD) is the four-phase workflow skill in Addy Osmani’s collection. The phases are sequential and gated: Specify → Plan → Tasks → Implement, with a human review at the boundary of each. The skill’s central claim is that code without a spec is guessing, and the spec’s value is in forcing clarity before code — writing it after is documentation, not specification.

Phase 1 — Specify — is the most opinionated. The skill mandates an “ASSUMPTIONS I’M MAKING” block emitted before any spec content gets written: “this is a web app, not native”; “session cookies, not JWT”; “PostgreSQL based on the existing Prisma schema.” The point is to surface the silent assumptions that turn into rework, before they’re baked into a draft. The spec itself covers six areas: objective (with success criteria), tech stack, exact commands, project structure, code style (one real snippet, not three paragraphs), testing strategy, and three-tier boundaries (always do / ask first / never do).

The skill also reframes vague requirements as success criteria. “Make the dashboard faster” becomes “Dashboard LCP < 2.5s on 4G; initial data load < 500ms; CLS < 0.1 during load” — testable targets the agent can loop against. Ambiguity that can’t be reframed gets surfaced as A/B/C options and stops rather than silently filling in.

When to use it

• Greenfield project where the spec doesn’t yet exist and the architectural decisions are still up for grabs
• Substantial feature touching multiple files where you want the rework cost paid in the spec phase rather than the implementation phase
• Tasks where the human is going to review anyway — the four phases give the review four cleaner artifacts (spec / plan / tasks / code) instead of a 600-line PR
• Any case where the agent is about to ask “should I just start building?” — that’s the trigger phrase

When not to reach for it:

• Single-line fixes, typo corrections, or changes where the requirement is unambiguous (the skill explicitly excludes these)
• Tasks under ~30 minutes where the gating overhead exceeds the rework risk
• Iteration on an existing spec — the skill is for creating a spec from a vague request, not for editing one

Install

From addyosmani/agent-skills at skills/spec-driven-development/. Pairs naturally with context-engineering (the spec is the level-2 context the engineering skill expects to load), incremental-implementation, and test-driven-development from the same repo — SDD is the upstream phase those downstream skills consume.

What a session looks like

1. Specify. Emit the assumptions block before writing any spec content. Loop with the human until the assumptions are correct. Then fill the six-area template — objective + success criteria, tech stack, commands, structure, code style with one snippet, testing strategy, three-tier boundaries. Save to a file, commit it.
2. Plan. From the validated spec, generate a technical plan: components and their dependencies, build order, parallelizable vs. sequential work, risks and mitigations, verification checkpoints between phases. The plan should be reviewable as “yes, that’s the right approach” or “no, change X.”
3. Tasks. Decompose the plan into discrete, single-session tasks. Each task gets explicit acceptance criteria, a verification step (test command, build, manual check), and the file list. The skill caps each task at ~5 files touched and orders by dependency, not by perceived importance.
4. Implement. Execute one task at a time. The skill defers to incremental-implementation and test-driven-development for the implementation discipline, and to context-engineering for loading the right spec section per task instead of flooding the agent with the whole document.
5. Keep the spec alive. When decisions change mid-build, update the spec first, then implement. The spec lives in version control alongside the code, and PRs reference the spec section they implement.

The discipline that makes it work: the assumptions block at the top of phase 1. Without it, the spec drafts get shaped around silent assumptions that nobody surfaces, and rework happens in implementation. With it, the bad assumptions die in the spec phase where they’re cheapest to fix.

Receipts

TODO — to be filled in from a real session. Once the skill has been used end-to-end on a non-trivial feature, this section will capture: how many silent assumptions the assumptions block actually surfaced (the on-paper claim is “this is the entire point”; the question is whether real sessions match), whether the gated phase boundaries felt like ceremony or genuinely caught wrong direction, and the wall-clock spec-vs-rework delta on a feature where the spec felt like overhead.

Source and attribution

From Addy Osmani’s agent-skills repository, an MIT-licensed collection of production-grade engineering skills for AI coding agents.

License: MIT.

Quote from the skill body, verbatim: “Don’t silently fill in ambiguous requirements. The spec’s entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.” The assumptions block, the reframing of vague requirements as success criteria, and the A/B/C options-and-stop pattern are how the skill operationalizes that stance.