Catalog My learning Blog
AI-Assisted Coding Course: Agentic Development in 30 Days · Phase 2 · Lesson 10 · 5 min read

Spec-Driven Development: GitHub Spec Kit and Kiro

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: An EARS Requirements File and a Task List
  4. Real-World Examples
  5. Review Questions & Answers

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.

ArtifactAnswersWritten byReviewed for
Principles or constitutionWhat rules always apply?Team, onceConsistency with architecture
Specification (requirements)What and why, for whom?Human with agent draftingCompleteness, testable criteria
Technical plan (design)How, with which components?Agent with human reviewFit with existing system, risks
TasksIn what small steps?AgentEach task small and verifiable
ImplementationThe codeAgent, task by taskDiff 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.

Code
# 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 test

Each 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.

Principles apply to every feature. The specification says what and why, the plan says how, the task list breaks it into small verified steps, and the agent implements one task at a time against the criteria.
Principles apply to every feature. The specification says what and why, the plan says how, the task list breaks it into small verified steps, and the agent implements one task at a time against the criteria.

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.
Key TakeawaysSpec-driven development keeps the source of truth for larger features in repository files instead of in chat conversations. It records principles, specification, technical plan and tasks, implemented one small task at a time. Tools such as GitHub Spec Kit and Kiro package the flow. Write requirements in a testable form such as EARS, link tasks to the criteria they satisfy, and reserve the full process for work that spans sessions, people or high risk.

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.