← back to the archiveCover illustration for “Spec-driven development: write the spec, let agents build”
TERM6mo ago·Published · Updated ·by Andy Padia

Spec-driven development: write the spec, let agents build

In short: Spec-driven development makes a written spec, plan and task list the source of truth that AI coding agents build from and are checked against.

Spec-driven development is a way of working with AI coding agents where you write the spec first and let agents build from it. The specification covers what to build, why, the constraints and the acceptance criteria. A plan and task list are derived from it, and agents implement against those tasks. GitHub's Spec Kit announcement of 2 September 2025 calls specs the shared source of truth.

Spec-driven development in plain words

Instead of directing a builder brick by brick over the phone, you hand them drawings everyone agreed on, and you check the house against the drawings.

How it works

GitHub's post describes four phases:

  1. Specify: you describe the goal and the reasons, and the agent drafts a spec with user journeys and success criteria.
  2. Plan: you supply the stack, architecture and constraints, and the agent produces a technical plan.
  3. Tasks: the agent breaks spec and plan into small, reviewable chunks that can be tested in isolation.
  4. Implement: the agent works through the tasks while you review focused changes.

The post treats the spec as a living artifact. When requirements change, you update the spec and regenerate the plan, in place of patching code through conversation.

The Spec Kit repository, MIT licensed, ships this as a specify CLI with agent commands such as /speckit-specify, /speckit-plan, /speckit-tasks and /speckit-implement.

Example

As an illustration, specs/password-reset.md states: reset links expire in 30 minutes, are single-use, and never reveal whether an email exists. The plan names the token table and email service; tasks include "test: expired token returns 410". The agent cannot drop a requirement unnoticed, because the tests encode it.

Where you'll meet it

  • GitHub's open-source Spec Kit, which the post says works with GitHub Copilot, Claude Code and Gemini CLI
  • Plan files produced by plan modes in coding agents
  • Teams using agents on regulated or long-lived systems
  • Agent-first IDEs that produce task lists and plans as artefacts

What it changes for you

For developers, writing clear requirements becomes a core engineering skill again. For tech leads and product managers, specs become shared, versioned artefacts that both people and agents read. For organisations, it gives an audit trail of intent, which matters when an agent wrote the code.

Spec-driven development vs vibe coding

Vibe coding steers by how the output feels. Spec-driven development steers by written criteria that can be checked.

Common mistake

My view: writing specs so detailed they become the code in English. Specify behaviour and constraints; leave implementation choices to the plan, where the agent can propose and you can review.

Plan mode · Agentic coding · Vibe coding · Evals · AGENTS.md and CLAUDE.md

Specify behaviour and constraints, and leave implementation choices to a plan you can review.

#field-guide#coding-agents#specifications#workflow#ai-coding

Sources

  1. github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit
  2. github.com/github/spec-kit
← older drop
Shadow AI: AI tools used without IT approval
newer drop →
SWE-bench: the benchmark for AI fixing real GitHub issues

related drops

explore all 557 drops →
← back to the archiveday 175