Chapter 2 · Spec-Driven Development in Depth · Lesson 2.1
The SDD Mindset & the Trio
A quick, deeper look at why spec-driven development pays, and the three frameworks that deliver it - before we go deep on Spec Kit.
- Chapter 0 · Sprint Zero
- Chapter 1 · The ratchet & the practice loop
- 2.1 · The SDD mindset & the trio
- 2.2 · Spec Kit, end to end
- 2.3 · Spec Kit in practice
- 2.4 · OpenSpec & agent-skills
- 2.5 · Choosing & adopting
Where we are
Lesson 0.3 introduced spec-driven development, and Lesson 1.4 turned "spec before code" into a habit. This chapter goes deep on the tools that make the habit stick - with Spec Kit as the main event across the next few lessons. This lesson is the map: when the discipline is worth it, and the three frameworks that deliver it.
The core, one more time
Spec-driven development (SDD) means you write a short, structured spec - what you're building, why, and how you'll know it's done - and the agent generates code from that spec. The spec is the source of truth; the code is generated output that serves it. The opposite is vibe coding: prompting freely and accepting whatever comes back, letting the agent fill every gap you left with its own guesses.
That is the whole argument in two sentences. The model can produce plausible code in seconds, so the scarce thing is knowing the code is right - and a spec is the cheapest way to pin down what "right" means before a single line is written.
When it pays, and when it's overkill
SDD is not free - writing the spec takes real minutes - so it earns its keep only on work that will outlive the session. Match the effort to the stakes:
- Spec-drive it when the code is production, shared across a team, or a long-lived system you (or a teammate) will maintain. Guesses there cost you later.
- Vibe-code it when the code is a prototype, a throwaway, or pure exploration - you're learning the shape of the problem, not shipping.
The rule of thumb: start vibe, finish spec-driven. Explore freely to find what you want, then write the spec once the thing is worth keeping - the moment throwaway becomes production is the moment to pin it down (GitHub Spec Kit).
The trio at a glance
Three tools bring this discipline to whatever agent you already use. They differ in weight and packaging, not in purpose - all three make the spec the source of truth:
- Spec Kit (GitHub) - the heavyweight, phase-gated toolkit. Thorough and structured, with explicit gates between each step.
- OpenSpec (Fission AI) - a lightweight, change-based framework. Its unit of work is the change: a bounded, reviewable delta.
- agent-skills - the same discipline as a drop-in skill, loaded straight into a harness you already run. No separate CLI.
The next three lessons take each in turn, Spec Kit first (2.2 and 2.3), because it's the most-adopted and the most explicit about the gated chain you'll recognise everywhere else.
Why this belongs in your harness
A spec is not a throwaway doc you delete after shipping. It's part of your harness - a durable, earned artifact. Like a rule or a hook, it's written once and pays off on every run that reads it: the agent works from clear intent instead of re-guessing. That is the ratchet applied to intent - turn a decision into structure once, and stop paying for it again.
Check yourself
The rule of thumb for SDD is -
Explore freely to find the shape of the problem, then write the spec once the work is worth keeping. Prototype or throwaway - vibe it; production or lasting - spec-drive it.
In SDD the source of truth is -
The spec is the durable source of truth and code is generated output that serves it - the reverse of writing code first and documenting later.
The three frameworks differ mainly in -
All three make the spec the source of truth. Spec Kit is the heavyweight phase-gated toolkit, OpenSpec is lightweight and change-based, and agent-skills is a drop-in skill - the split is weight and packaging.
Do this now (3 min)
Take one task on your plate this week. Decide it by the rule: is it a prototype or throwaway (vibe-code it), or is it production or lasting (spec-drive it)? Write the one-line reason for your call - that sentence is the whole decision, and you'll reuse it every time.
Go deeper
Primary source (read this): GitHub Spec Kit - the most-adopted, structured SDD toolkit, and the main event of this chapter.
Secondary: OpenSpec - the lightweight, change-based alternative. Skim its README to feel the heavy-vs-light contrast.
Wisdom (test it on people): r/ChatGPTCoding - active, cross-tool debate on spec-driven vs vibe workflows.