Spec-Driven and Test-Driven Development,
with GitHub Spec-Kit and Specky.

How specifications and tests turn AI coding agents from unpredictable assistants into reliable engineering partners.

Eleven chapters, one thesis: intent first, code last.

Why "prompt and pray" fails on anything bigger than a script.

Technical debt is code you owe. Intent debt is understanding you owe: every behavior shipped without a written, testable requirement is a decision your future team must reverse-engineer from the code itself.

Symptoms: onboarding measured in months, "do not touch" modules, rewrites that lose features nobody documented, and AI agents that cannot help because the repository carries no machine-readable intent.

Same agent, same model. The discipline is the difference.

In SDD, the specification is the source of truth. Code is a projection of it.

A spec in SDD is not a Word document that dies after kickoff. It is a structured, versioned artifact that states what the system must do, why, and how success is verified. Humans and AI agents both read it, both are accountable to it, and every implementation decision traces back to a line in it.

Four artifacts, each derived from the previous one.

Four principles that make SDD work in practice.

The SDD loop: every change flows through the spec.

What separates a usable spec from a wish list.

Red, green, refactor: the smallest loop in software engineering.

Write a test that fails because the behavior does not exist yet. Write the minimum code that makes it pass. Improve the design while the tests stay green. Repeat in cycles of minutes, not days. The test suite becomes a living, executable specification of behavior.

Minutes per loop. The speed is the point.

Robert C. Martin's formulation, still the sharpest.

Applied to agents, the laws become a contract: the agent must show the failing test before it is allowed to write the implementation. Spec-Kit and Specky both encode this ordering into their task templates.

What a test-first suite buys you, especially with agents in the loop.

SDD and TDD answer different questions. Neither replaces the other.

Acceptance criteria are the translation layer between spec and test.

## FR-007 Account lockout
WHEN a user fails authentication
  5 times within 15 minutes,
THE SYSTEM SHALL lock the account
  for 30 minutes
AND SHALL notify the user by email.

Acceptance criteria:
- 5th failure inside window locks
- 4 failures do not lock
- lock expires after 30 minutes
- email job enqueued exactly once

def test_fifth_failure_locks_account():
    # FR-007 / AC-1
    fail_login(user, times=5, window="15m")
    assert account(user).locked

def test_four_failures_do_not_lock():
    # FR-007 / AC-2
    fail_login(user, times=4, window="15m")
    assert not account(user).locked

def test_lock_expires_after_30_minutes():
    # FR-007 / AC-3
    ...

An outer spec loop wrapping an inner test loop.

Spec-Kit turns SDD from a philosophy into a repeatable workflow.

Install the Specify CLI, initialize a project, and the kit scaffolds a constitution, spec templates, and agent commands. From then on, every feature follows the same phased path, and every artifact lands in a predictable place in the repository, reviewable like code.

Three layers: CLI, templates, and your agent.

Four commands, four artifacts, four gates.

/specify: describe the what and why, get a structured spec.

> /specify Build a team dashboard where managers see open tasks per member,
  filter by sprint, and export the view to CSV. Managers only; members see
  their own tasks. No real-time updates needed in v1.

Created branch: 003-team-dashboard
Created spec:   specs/003-team-dashboard/spec.md

## User stories          3 stories, 11 functional requirements
## Acceptance criteria  per requirement, EARS formatted
## Non-goals            real-time sync, member-level analytics
## Open questions       2 × [NEEDS CLARIFICATION]
  - CSV export: include archived tasks? 
  - "manager" defined by org chart or project role?

The command creates a branch and a numbered spec folder. Open questions block the next phase until a human answers them.

/plan: technical choices, constrained by the constitution.

> /plan Use the existing React + FastAPI stack. Postgres for storage.
  Reuse the auth middleware. CSV generation server-side.

Reading constitution.md ... 9 articles loaded
Created plan:      specs/003-team-dashboard/plan.md
Created contracts: specs/003-team-dashboard/contracts/dashboard-api.yaml
Created data model: specs/003-team-dashboard/data-model.md

Constitution check
  ✓ Art. III  test-first mandate acknowledged in plan
  ✓ Art. VII  no new framework without justification
  ✗ Art. V   observability: missing structured logging section
Plan gate: 1 violation to resolve before /tasks

The plan inherits every requirement ID from the spec. Constitution violations are surfaced as gate failures, not buried in prose.

/tasks orders the work, /implement executes it test-first.

> /tasks
Created tasks: specs/003-team-dashboard/tasks.md · 18 tasks
  T001  setup: migration for dashboard_views table
  T002 [P] contract test: GET /api/teams/:id/dashboard  (FR-001)
  T003 [P] contract test: GET .../export.csv            (FR-009)
  T004  unit tests: sprint filter logic                  (FR-004)
  T005  implement: dashboard query service  depends: T002, T004
  ...

> /implement
T002 ... wrote test, ran suite: FAIL (expected, endpoint missing)
T005 ... implemented service, ran suite: PASS 14/14
Gate: coverage on changed lines 96%, traceability 18/18 tasks linked

Tests are tasks of their own and always precede the implementation tasks they verify. The agent must show red before green.

Project law: principles that every spec, plan, and task must obey.

# Article III · Test-first (non-negotiable)
All implementation tasks MUST be preceded
by failing tests derived from acceptance
criteria. Red before green, no exceptions.

# Article VII · Simplicity
Start with the simplest design that meets
the spec. New frameworks require written
justification in plan.md.

NEVER merge with failing gates.
NEVER resolve a [NEEDS CLARIFICATION]
  by guessing.

One method, many agents. Spec-Kit is deliberately agent-agnostic.

The artifacts, not the agent, carry the project. Switching agents mid-project costs nothing because the spec, plan, and tasks are plain Markdown in git.

Specky turns natural language into production-grade specs through guided discovery.

Where Spec-Kit gives you the phased skeleton, Specky leans into the conversation: it interviews you about the feature, scans existing codebases, drafts EARS-notation requirements, and will not let a phase close until its quality gate passes. It installs as agent commands for both GitHub Copilot and Claude Code from a single source.

Four capabilities that define the Specky workflow.

Spec-Kit and Specky: same philosophy, different center of gravity.

From conversation to gated delivery in five moves.

New project: constitution first, then features in numbered folders.

Existing codebase: specify the seam, not the whole system.

What actually lands in the pull request.

The reviewer's question changes from "does this code look fine" to "does this code satisfy this spec", a question with an answer.

Four gates between an idea and a merge.

The matrix: requirement, test, code, status. No orphans in either direction.

| Requirement | Tests                                  | Implementation              | Status |
|-------------|----------------------------------------|-----------------------------|--------|
| FR-001      | test_dashboard_contract.py::3 cases    | api/dashboard.py            | PASS   |
| FR-004      | test_sprint_filter.py::5 cases         | services/filters.py         | PASS   |
| FR-007      | test_lockout.py::4 cases               | auth/lockout.py             | PASS   |
| FR-009      | test_csv_export.py::3 cases            | services/export.py          | PASS   |
| NFR-002     | test_perf_dashboard.py::p95_under_200  | (query index, migration 14) | PASS   |
| FR-011      | MISSING                                | views/archive.py            | GAP    |

Two failure smells the matrix exposes instantly: requirements with no test (unverified intent) and code with no requirement (unrequested behavior). Both block the merge gate.

Five ways spec-driven work goes wrong.

Five ways test-first work goes wrong, doubly so with agents.

The pattern across early adopters is consistent in direction.

Treat any specific percentage with care: published numbers vary by team, codebase, and baseline. The directional pattern above is what recurs.

Crawl, walk, run: ninety days to a working practice.

The only metric that matters in week 3: did the pilot team voluntarily start their second feature with /specify.

If you remember five things from these fifty slides.