Spec-Driven Development: GitHub Spec Kit and Kiro
On this page
Learning Objective
Understand spec-driven development, where a written specification, design and task list in the repository drive the agent's work, compare tools such as GitHub Spec Kit and Kiro, and write a requirements document in a form agents and reviewers can check.
Concept Explanation
Plan mode works well for a change you can finish in a session. Larger features span days, several sessions, maybe several agents and people. Conversations are a poor place to keep the decisions: they get compacted, cleared and lost. Spec-driven development moves the source of truth from the chat into files in the repository. The idea is old, writing down requirements before building, but agents give it new force, because a precise written spec is exactly the context an agent needs, and because agents can draft, check and implement against it.
The typical flow has four artifacts. Principles, sometimes called a constitution, capture project-wide rules: architecture, testing standards, security requirements. A specification describes what to build and why, from the user's perspective, without implementation details. A technical plan or design describes how: components, data model, interfaces, trade-offs. A task list breaks the plan into small, ordered, testable steps. The agent implements tasks one at a time, checking them off, and each task maps to a reviewable change.
GitHub's open-source Spec Kit, released in September 2025, packages this flow as slash commands for many agents, such as /speckit-specify to write the spec, /speckit-plan for the technical plan, /speckit-tasks to break it down and /speckit-implement to execute, with templates that keep the documents consistent. Amazon's Kiro IDE, launched in July 2025, builds the same idea into the editor: a spec consists of requirements.md, design.md and tasks.md, and the requirements use EARS notation.
EARS, the Easy Approach to Requirements Syntax developed at Rolls-Royce, constrains requirements to a few templates such as "WHEN a trigger occurs, THE SYSTEM SHALL respond" and "IF an unwanted condition, THEN THE SYSTEM SHALL respond". The value is testability: each requirement names a condition and an observable response, which maps directly to a test case. Vague requirements such as "the export should be fast" become "WHEN an admin requests an export of up to 100,000 rows, THE SYSTEM SHALL deliver the file within 30 seconds".
Spec-driven development has costs. Writing and reviewing specs takes time, and specs drift from code if nobody updates them. It pays off for features that span sessions or people, for regulated or high-risk work where decisions must be traceable, and for teams that delegate to background agents, which work best from a precise written task. For small changes, a good prompt and plan mode are enough.
| Artifact | Answers | Written by | Reviewed for |
|---|---|---|---|
| Principles or constitution | What rules always apply? | Team, once | Consistency with architecture |
| Specification (requirements) | What and why, for whom? | Human with agent drafting | Completeness, testable criteria |
| Technical plan (design) | How, with which components? | Agent with human review | Fit with existing system, risks |
| Tasks | In what small steps? | Agent | Each task small and verifiable |
| Implementation | The code | Agent, task by task | Diff matches task and tests pass |
Worked Example: An EARS Requirements File and a Task List
This specification for a CSV export feature uses EARS so each requirement maps to a test. The task list derived from it gives the agent small, ordered steps.
# specs/user-export/requirements.md
## Story
As an admin, I want to export the filtered user list as CSV so that I can analyze it in a spreadsheet.
## Acceptance criteria (EARS)
1. WHEN an admin clicks Export on the Users page, THE SYSTEM SHALL generate a CSV of all users
matching the current filters, not only the visible page.
2. THE SYSTEM SHALL include exactly the columns id, email, name, created_at, plan.
3. IF a field begins with =, +, - or @, THEN THE SYSTEM SHALL prefix it with a single quote
to prevent spreadsheet formula injection.
4. IF a user without the admin role calls the export endpoint, THEN THE SYSTEM SHALL return 403.
5. WHEN the export contains more than 100,000 rows, THE SYSTEM SHALL generate it in the
background and email a download link valid for 24 hours.
# specs/user-export/tasks.md
- [ ] 1. CSV serializer with escaping and formula-injection guard (criteria 2, 3) + unit tests
- [ ] 2. GET /api/admin/users/export with role check and filter reuse (criteria 1, 4) + API tests
- [ ] 3. Background job and signed link for large exports (criterion 5) + job test
- [ ] 4. Export button on Users page wired to the endpoint + component testEach task cites the criteria it satisfies, so a reviewer can check the diff against the spec, and a new session can resume by reading the two files and picking the first unchecked task.
Real-World Examples
- GitHub released Spec Kit as an open-source toolkit in September 2025, describing spec-driven development as making the specification the primary artifact from which agents generate plans, tasks and code; it supports GitHub Copilot, Claude Code, Gemini CLI and other agents.
- Amazon launched the Kiro IDE in July 2025 with spec mode producing requirements.md in EARS notation, design.md and tasks.md, positioning it as a structured alternative to vibe coding for production work.
Review Questions & Answers
Conversations are compacted, cleared and lost between sessions, while files persist, can be reviewed and versioned, and give any new session or agent the same precise context.
Project principles or a constitution, a specification of what and why, a technical plan or design of how, and a task list of small ordered steps.
Each requirement follows a template with an explicit condition and an observable system response, which maps directly to a test case and leaves little room for ambiguity.
For small, self-contained changes that fit in one session, where a clear prompt and plan mode give the same benefit with much less overhead.