Spec-Driven Workshop

Appearance

5 minModule 3 — Spec-Driven Development

L3.1: The Cost of No Specs ​

The Problem ​

The L1.1 runs were unpredictable because there were no specs. You probably felt that. But "unpredictable" is vague. The actual costs of no specs are specific and measurable:

  • Rework time: code generated from vague prompts often needs to be partially or fully rewritten. That's new generation time, plus review time, plus integration time.
  • Scope creep: without defined acceptance criteria, "done" is a moving target. Copilot will keep adding things. You'll keep accepting them. The feature will grow until something breaks.
  • Integration failures: code that looks correct in isolation — wrong types, wrong shape, incompatible interfaces — fails at integration. Finding that later costs more than preventing it with a spec.
  • Lost decisions: when you don't write down what a feature should do, you make the same decisions multiple times across prompts, across sessions, across team members.

The spec-driven workflow exists to eliminate all four of these costs.

The Solution ​

You write the spec before the code. The spec defines:

  1. What the feature does (goal + acceptance criteria)
  2. What it does not do (out of scope)
  3. How "done" is verified (definition of done)

With that in place, every code generation prompt becomes a reference to the spec — not an open-ended request.

"I'll add a spec if the feature turns out to be complex." Complexity is discovered during implementation when it's expensive. Specs expose complexity before implementation when it's cheap.

Write the spec first, always. For simple features, it takes five minutes and costs nothing. For complex features, it saves hours. The spec-kit tool makes this fast.

Exercise ​

Step 1 — Install spec-kit ​

spec-kit is a Python CLI tool that installs slash commands into your AI coding agent (including GitHub Copilot Chat). It requires uv — a fast Python package manager.

First, install uv if you don't have it:

bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the Specify CLI:

bash
# Install the latest stable release
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Verify the installation:

bash
specify check
  • Expected result: Specify CLI version and environment check printed to terminal.
  • Why this matters: spec-kit is the scaffolding tool for the spec-driven workflow. All subsequent exercises in M3 use it.

Initialize spec-kit in your project workspace:

Open a terminal in your project root and run (for GitHub Copilot):

bash
specify init --here --ai copilot

This creates the spec-kit configuration files and registers the slash commands into your workspace. After this step, /speckit.* commands become available in VS Code Copilot Chat.

Step 2 — Create your first feature spec ​

Open Copilot Chat in VS Code and enter this slash command there. Do not run it in the terminal.

text
/speckit.specify Add study session tracking
  • Expected result: spec-kit creates a new feature branch and a specs/<feature-branch>/spec.md file populated from the feature-spec template.
  • Why this matters: this is the documented entry point for the workflow. You start from a feature specification, not from a custom init scaffold.

Step 3 — Calculate your rework estimate ​

Look at the two runs from L1.1.

For each run, estimate:

  • How many lines of code were generated?
  • How many lines were in the wrong shape, wrong type, or wrong behavior and would need to be changed?
  • What percentage of the generated code was rework?

Write a single sentence: In my L1.1 runs, approximately __% of generated code would have required rework without specs.

  • Expected result: you have a concrete number, even if approximate.
  • Why this matters: the spec-driven workflow is justified by this number. Keep it. Reference it in M5 when you compare the spec-driven approach.

Checkpoint ​

  • [ ] I installed the Specify CLI and confirmed it works with specify check
  • [ ] I ran specify init --here --ai copilot and /speckit.* commands are available in Copilot Chat
  • [ ] I ran /speckit.specify and have a generated specs/<feature-branch>/spec.md
  • [ ] I estimated the rework percentage from my L1.1 runs
  • [ ] I understand the four specific costs of building without specs

← Module 3 Overview · Next Lesson: L3.2 Writing Specs That Guide AI →

Spec-Driven Development Workshop — structured AI development with GitHub Copilot