Phase 1: Spec-Driven Development · 40 min · GitHub Spec Kit · Claude Code · Python

Spec-Kit and the SDD Toolchain

The tool doesn't make you spec-driven. Whether anything checks the spec against the code, continuously, does.

Hiring signal: Being able to name which SDD maturity level your team actually operates at — not just 'we write specs' — shows you understand that the tool is secondary to whether anything enforces the spec-code relationship.

What you will learn

Name the three SDD maturity levels: spec-first, spec-anchored, spec-as-source
Map real tools (GitHub Spec Kit, Amazon Kiro, Tessl) to the maturity level they primarily target
Diagnose when a team's claimed 'spec-first' practice is hollow because nothing checks specs against code after the first draft
Assess a team's actual SDD maturity and recommend a concrete next step

Introduction

Spec-Kit and the SDD Toolchain

A team lead, newly convinced that spec-driven development is worth adopting, asks the obvious next question: "so which tool do we buy?" It's the wrong first question, and answering it before answering a different one wastes real budget. The right first question is: once we write a spec, what — if anything — actually checks that the code still matches it three weeks later? Teams that skip straight to tool selection frequently end up writing beautiful specs once, at project kickoff, that are exactly as stale as the after-the-fact documentation from two lessons ago by the time anyone reads them again. The tool doesn't create discipline. It can only support whatever discipline already exists.

Three maturity levels, not one destination

Spec-first is the entry level: specs are written before code, genuinely used to guide generation, but nothing automated checks whether the code still matches the spec after that first pass. This is real progress over no-spec-at-all — the initial generation is grounded in explicit acceptance criteria instead of a vague prompt — but it's fragile. The moment someone edits the code directly (a hotfix, a "quick" refactor) without touching the spec, drift starts, silently, exactly like the undocumented retry-logic change from lesson one of this phase.

Spec-anchored adds enforcement: a CI check runs on every pull request and flags — or blocks — a merge where code changed in a way that isn't reflected in a corresponding spec update. This is the level where "the spec is the source of truth" stops being a slogan and starts being something the build pipeline actually verifies. It costs more to set up than spec-first (you need real tooling in CI, not just a habit), but it's the level where drift becomes visible instead of invisible.

Spec-as-source is the most advanced level: the spec isn't just checked against the code, it's the thing the code is treated as derived from, continuously, with bidirectional synchronization tooling keeping them tied together as both evolve. At this level, editing the spec is expected to propagate, and editing the code without the spec noticing is the anomaly the tooling actively surfaces, not an occasional CI failure you might miss.

Match the level to your actual constraints, not your ambition
Spec-as-source tooling is genuinely powerful and genuinely overkill for a two-person side project with no compliance requirement — the setup cost buys you protection against a drift problem you don't have yet at that scale. A regulated fintech team with five squads and an audit requirement is under-invested if they're still at spec-first. Maturity level is a fit question, not a status symbol.

Unlock the full lesson

You've read the first 2 sections. The rest of this lesson covers Where real tools map onto this ladder, The hollow spec-first trap, Build It — plus a hands-on lab, quiz, and project artifact.

Create a free account to unlock Phase 0 and Phase 1 of every course — no credit card.