Chapter 2 · Spec-Driven Development in Depth · Lesson 2.5
Choosing & Adopting a Spec Framework
A simple decision aid for picking Spec Kit, OpenSpec, or agent-skills - and how a committed spec plugs into your harness.
- 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
The decision aid
You have now seen all three frameworks close up. The choice is not "which is best" - it is "which weight fits my situation". Match the ceremony to the context: heavy structure on a throwaway is waste, and none at all on a big team project is drift. Use this table to pick.
| Your situation | Reach for |
|---|---|
| Greenfield project; want a thorough, repeatable, structured process; don't mind the ceremony | Spec Kit |
| Existing (brownfield) codebase; want it lightweight and iterative; fast setup | OpenSpec |
| Already in a skill-capable harness (e.g. Claude Code); want SDD with no extra tooling | agent-skills |
| Just testing the water on any one task | The 5-line spec habit (no tool) |
- Start with the 5-line spec habit before any tool - from Lesson 1.4. If that is enough, stop.
- Commit specs to the repo. A spec in version control is a durable artifact, not a scratchpad you lose.
- Add ceremony only where it earns its place. Don't bolt on Spec Kit's full phase chain for a one-file fix.
- Keep the spec alive. When a decision changes, update the spec first, then the code.
A spec is part of your harness
This is the point that ties the whole chapter to the rest of the course. A committed, living spec is scaffolding - it steers the agent every turn, just like a rules file or a hook. So treat it with the ratchet: earn it, keep it lean, and prune it when the model no longer needs the hand-holding.
Honest close
The best framework is the lightest one your project can get away with. A heavyweight setup cargo-culted onto a small job costs you in tokens and ceremony; a no-structure free-for-all on a big team project costs you in drift and rework. Pick by context, commit what you choose, and ratchet it as you learn. And remember: if all you ever need is the five-line spec, that is not a failure of SDD - it is SDD working at the right weight.
You've completed Chapter 2
One breath: spec-driven development makes the spec the source of truth, and three frameworks deliver it at three weights - Spec Kit (heavy, phase-gated), OpenSpec (light, change-based), and agent-skills (a drop-in skill). Pick by context, commit what you choose, and treat the spec as part of your harness - lean, earned, and disposable. Next, Chapter 3 takes the harness you've built and runs it for real, safely.
Check yourself
For a big greenfield project you should -
Spec Kit's thorough, repeatable, phase-gated process is the fit when you want full ceremony on a large, long-lived, greenfield project - the other options are lighter and better suited to brownfield or no-extra-tooling situations.
On an existing brownfield codebase, choose -
OpenSpec is brownfield-first, lightweight, and iterative - it can even reverse-engineer baseline specs from code you already have. That fits an existing codebase where heavy phase gates would fight you.
A committed spec is best treated as -
A committed, living spec is durable scaffolding that steers the agent - harness. So earn it, keep it lean, and prune it when the model outgrows it, exactly like a rule or a hook.
Do this now (5 min)
Using the table above, pick one framework (or the plain 5-line habit) for your next real project, and write one sentence on why it fits your context - greenfield vs brownfield, solo vs team, ceremony-tolerant or not. If you can't name the reason, you don't have a context yet, so start with the 5-line habit.
Go deeper
Primary source (read this): GitHub Spec Kit and OpenSpec - skim both READMEs side by side to feel the heavy-vs-light contrast for yourself.
Secondary: Addy Osmani - Agent Harness Engineering - on treating all scaffolding (specs included) as earned and disposable harness.
Wisdom (test it on people): r/ChatGPTCoding - active, cross-tool debate on which spec framework fits which job.