Spec Driven Development: GitHub Spec Kit and Kiro

Writing more documentation is not the objective. You want a short agreement that lets a founder reject the wrong behavior, an engineer challenge the proposed design, and a reviewer identify the evidence needed to merge.

For a first attempt, choose a bounded feature in the repository you already use. An export, an approval rule or a notification preference exposes the method's value more clearly than asking an agent to specify an entire application.

What Is Spec-Driven Development?

Spec-driven development with AI agents means using a reviewed description of desired behavior to guide planning, task creation, implementation and verification. The spec says what must happen and why. The plan says how the existing application will make it happen. Tasks divide that plan into work you can check.

Before AI, related specification-driven practices used specifications as executable tests, as in behavior-driven development; that tradition is compatible with this workflow, but a Markdown spec is not itself an executable test. Cucumber's BDD documentation.

The practical change is that coding agents can consume those artifacts throughout implementation. GitHub Spec Kit, an open-source toolkit for structuring an agent's work, supplies the process around your agent. Kiro, AWS's coding environment, builds a spec workflow into the product. Neither removes the need to decide what the customer should experience.

Documentation verified on 13 October 2026: the command names, file paths and capabilities below come from the current GitHub, Kiro, Anthropic and OpenAI documentation. The feature walkthrough is an illustration, not a claimed production deployment or a measured productivity trial.

For builders, the consequence is a smaller implementation target: the agent should reuse the application around the feature instead of redesigning it. For operators and founders, the valuable review moves earlier: decide who can export data before reviewing the export button. For buyers, adopting the method does not require moving every developer to a new editor. Start with the agent you already have; buy additional structure when maintaining the artifacts becomes the problem.

Spec-Driven Development Tutorial: The Workflow

Keep the artifacts separate because each answers a different question. An architecture diagram cannot settle a missing product rule, and a task list cannot prove the feature works.

The founder or product owner owns the behavioral decision. The engineering lead owns whether the design fits the system. The agent can draft both, but fluent prose is not evidence that either decision is right.

Spec-Driven Development Tools: Choose the Amount of Structure

Choose tooling by where coordination breaks. GitHub Spec Kit suits a repository where you want a repeatable process around an existing agent. Kiro suits developers who want requirements, design and task execution in the coding environment. Plain files suit a first feature or a team that already has a reliable review habit.

GitHub Spec Kit: Commands and Files

GitHub Spec Kit provides reusable instructions, templates and supporting scripts; your selected coding agent performs the work. Its current README makes the core sequence explicit: establish project principles, specify the feature, plan it, create tasks, implement, then check for remaining gaps.

The current README requires Python 3.11 or newer, uv (a Python package installer), and a supported agent. Its setup example uses GitHub Copilot, GitHub's coding assistant. Run these in the terminal:

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Then launch your coding agent in that directory. Run each workflow instruction in the agent's chat and review its output before continuing. These are not shell commands.

The naming distinction matters. The README uses Copilot's default skills syntax, /speckit-specify. The detailed command reference uses the dot form, /speckit.specify. Codex's skills integration uses $speckit-specify. Use the syntax for the integration you installed; punctuation is not interchangeable. Integration reference.

These names and roles follow GitHub's Agentic SDD reference. Clarify, checklist and analyze are additional quality gates. The constitution establishes persistent project rules; do not rewrite it for every small feature.

For the export example, your specify instruction should describe who can export, which records qualify, the file contents and failure behavior. Give the existing stack and repository constraints to the plan step. Explicitly request acceptance tests: the tasks command documents test generation when requested, so a generated task list is not proof that suitable tests were included.

The files to review are:

• .specify/memory/constitution.md: project principles. Constitution template.
• specs/<feature-directory>/spec.md: feature behavior. Feature directories normally live under specs/; the directory name is generated or configured. Specify template.
• plan.md and tasks.md in that feature directory: implementation design and work breakdown. Planning also produces research.md, data-model.md and quickstart.md, with contracts/ for applicable external interfaces. Plan template, task reference.

After implementation, converge compares the codebase with the spec, plan and tasks. If it finds gaps, it appends work to tasks.md; it does not repair the code itself. Implement the added work, then check again. A “Converged” result is a useful review input, not a substitute for your tests or approval.

For an existing application, GitHub's adoption guide starts with a preserved baseline and initializes in place. Its command is specify init --here --force --integration <key>, where you replace <key> with the documented integration key, such as claude or codex. The guide warns that --force can replace conflicting managed files. Review the resulting diff. You do not need to reconstruct specs for the entire application before specifying its next change.

The wall: Spec Kit can expose contradictions between artifacts while still accepting a consistently wrong business rule. Its extra files earn their maintenance cost when several people or sessions need the same agreement.

Kiro Spec-Driven Development: Specs, Steering and Hooks

Kiro separates feature intent, persistent project guidance and automatic actions. Use specs for this feature, steering for repository-wide conventions, and hooks for repeatable checks.

In the IDE, Kiro's code editor, click + under Specs, or choose Spec from chat. Choose Feature, then Requirements-First. Review the requirements before accepting the technical design and task breakdown. The resulting feature directory contains .kiro/specs/<feature-name>/requirements.md, design.md and tasks.md. Run tasks from the task interface after reviewing them. Kiro specs documentation.

Kiro uses EARS, short for Easy Approach to Requirements Syntax, to express a condition and the expected system behavior. For this example: “When a member requests an export, the system shall deny the request and return no export file.” That is concrete enough to become a test. Feature Specs.

Kiro also offers Design-First and Quick Spec. Design-First starts from technical design; Quick Spec creates the artifacts without the intermediate approval gates. For a founder whose agent keeps misunderstanding intent, choose Requirements-First and use those reviews. Removing the review points would remove the part of the process that addresses the problem.

Steering supplies persistent Markdown context under .kiro/steering/. The foundation files are product.md, tech.md and structure.md, covering the product, stack and repository organization. In the IDE, Generate Steering Docs creates that starting context. Review it against the repository. Put “reuse the existing membership authorization policy” here when it applies across features; put “only owners can export” in the export spec. Steering documentation.

Hooks run shell commands or agent prompts when an event occurs. Current project hook files live at .kiro/hooks/<id>.json; PostFileSave is a documented trigger. A focused hook could run your existing export tests when the relevant source changes. Keep the same checks in continuous integration, the automated checks on proposed code changes, so a local hook is not the only place they run. Kiro's current capability table supports hooks in the IDE and CLI, not Web or Mobile. Hooks documentation.

The wall: an automatically generated requirement can formalize an assumption nobody approved. Review permissions, empty results and failure behavior before design. Spec mode adds structure; it does not supply missing product judgment.

Spec-Driven Development With Claude Code

Claude Code, Anthropic's coding agent, can follow this process with a feature spec and Plan Mode. You do not need to install a spec framework to try the method.

Create specs/workspace-export/spec.md yourself, or review a draft from the agent. Then start the terminal session in planning mode:

claude --permission-mode plan

Ask Claude to read that file, inspect the existing export-adjacent code, and propose an implementation plan tied to the acceptance criteria. Request unresolved questions and the exact checks it intends to run before approving implementation.

Plan Mode is designed for investigation and a proposed approach. Anthropic documents an exception in interactive terminal sessions where bypass permissions are available: its plan-mode edit blocks are not enforced. Start without bypass enabled when you want the approval boundary to hold. Permission-mode documentation.

After reviewing the proposal, save the accepted approach to specs/workspace-export/plan.md and its checklist to tasks.md, then authorize implementation. Those paths are this article's suggested convention, not files that Plan Mode promises to create automatically. The Claude Code Plan Mode guide covers the controls and approval transition.

Keep durable repository instructions in CLAUDE.md, using the team-memory guide, and feature-specific behavior in the spec. Otherwise a temporary export requirement can become a permanent instruction that affects unrelated work.

The wall: a plan left only in a conversation is easy to lose or contradict. Saving it helps only if subsequent implementation and review explicitly refer to it.

Codex: Plan Mode With the Same Spec File

Codex, OpenAI's coding agent, supports the same lightweight handoff. In an idle CLI chat, /plan starts planning and can include the request inline. Official command documentation.

A useful request is: “Read specs/workspace-export/spec.md. Inspect the existing membership policy, task query and tests. Propose the smallest implementation plan that satisfies every requirement. Identify missing decisions before implementation.”

Review that plan, save the agreed files, and then ask Codex to implement the tasks with a requirement-to-test completion report. Use AGENTS.md for persistent repository instructions; /init can scaffold it. The Codex CLI setup guide covers the starting environment.

OpenAI also documents keeping specs, plans and progress in Markdown for longer work. The useful property is that a later session can reopen the agreement. The wall: Plan Mode does not keep a separate feature spec current by itself. Make updating it part of your change review. OpenAI's documented workflow.

Spec-Driven Development Example: A Workspace CSV Export

A small CSV export, a download of records as comma-separated values, shows why deciding behavior first can prevent rework across several files. “Add CSV export” leaves the agent to guess the user role, data scope, pagination and file format. An attractive button can hide the wrong answer to every one of those questions.

The following is a worked illustration for an existing task-management application. The paths, requirement IDs and proposed tests are teaching examples, not claims about a repository tested or merged for this article.

The One-Page Spec

Save this as the feature's spec.md, or put the same behavioral content into Kiro's requirements.md:

Notice the decision hidden inside R2: “all matching results” is different from “the visible page.” Resolving it before implementation changes the query and test plan immediately. Resolving it after the demo can require revisiting both.

R4 deliberately names a decision that needs concrete examples. Before approving the spec, settle how spreadsheet-formula inputs are handled and record those examples. A sentence saying “make exports secure” would leave the agent to choose a policy on your behalf.

The Plan: Fit the Existing Application

The plan should reuse the existing session and membership policy, extract or reuse the task-list filter logic, and add an export response without changing the list response. Route the export through the server's authorization boundary. Derive workspace access from authenticated membership, then apply the requested filters within that scope.

Choose the repository's established CSV serializer if one exists. Specify the content and download headers, safe-field policy, error behavior and tests. Add the button using the application's current loading and error states.

The plan must also check the expected result size against the application's existing request and memory constraints. If an all-results export cannot fit, bring the conflict back to the feature owner. Decide on a bounded export or separately scope background processing. The agent should not silently invent a maximum or add a job system contrary to R6.

The Tasks: Make Each Change Verifiable

Turn the plan into work the reviewer can recognize:

1. Capture existing task-list behavior and the shared filter rules in regression checks.
2. Add request authorization tests for owner, member, removed owner and another workspace.
3. Implement the scoped query and CSV response using the agreed field policy.
4. Add the export control, loading state and failure presentation.
5. Complete the acceptance checks and inspect the diff for changes outside the feature.

These tasks are this example's breakdown. A toolkit may generate a different list; judge it by whether it covers the agreement.

For a TypeScript application, the reviewable code change might include server/exports/tasks.ts for authorization, filtering and the response; ui/tasks/ExportButton.tsx for the interaction; and tests/task-export.test.ts for the acceptance cases. These are illustrative paths, not required framework conventions. A new queue worker or database migration would signal a scope change to resolve before merge.

From Acceptance Criteria to a Merge Decision

Require evidence for the behavior, not a list of files the agent edited. A pull-request description should connect the requirements to checks such as these:

The reviewer should compare these checks with the spec, inspect the authorization and query code, and try the agreed user flow in the project's normal review environment. If the agent wrote both the implementation and tests, review the expected results independently. A test can faithfully confirm the same wrong assumption as the code.

For example, suppose review finds that the endpoint reads only the current page. Keep R2 if the owner still wants all matching results; correct the query and add a test with matches beyond that page. If the owner changes the scope, update R2, the plan and the tests together before approval.

Merge the feature when the evidence matches the agreement: include the reviewed spec, final plan, completed task record, implementation and tests in the same pull request. Record any accepted scope change there. After merging, either maintain the spec as the current contract or label it as a historical feature record. Leaving an old spec looking authoritative creates the next round of confusion.

The benefit comes from settling permission and pagination before their assumptions spread through the implementation. The spec, tests and code then preserve the same decision after merge.

What It Costs and When It Pays Back

The method's cost is review and maintenance time plus the agent work used to draft and implement. Spec Kit is open source, but the coding agent you connect still has its own usage terms. Plain Markdown adds no separate spec-tool subscription; it does not make model usage free.

Kiro's standard commercial pricing lists Free at $0 per month with 50 credits and Pro at $20 per user per month with 1,000 credits, before applicable taxes. Four Pro subscriptions therefore cost 4 × $20 = $80 per month, before additional credits and tax. That is seat arithmetic, not a prediction of how many features you can ship. Kiro's own pricing page.

Paid add-on credits cost $0.04 each. Kiro states that spec refinement, task execution and agent hook execution consume credits, and that a complex spec task can use more than a credit. There is no defensible conversion from “credits” to “completed features” without observing the actual workload. Kiro credit definitions.

The economic test is straightforward: the extra cost of specifying, reviewing and maintaining the feature must be lower than the rebuild work it avoids. Track those costs in your own process. A method that adds documents while leaving the same decisions until code review has not earned its overhead.

What Is Overhyped, and When Is It Overkill?

The overhyped promise is that a sufficiently detailed document makes the agent reliably correct. It does not. A spec can be wrong, an implementation can ignore it, and tests can repeat its mistaken assumptions.

The useful distinction is between stated intent and enforced behavior. A requirement says members cannot export; a server-side check and its tests help enforce that rule. A requirements checklist checks the description. It does not run the application. Treating those as equivalent creates false confidence.

Another failure is document drift. If a developer changes permission behavior but only edits code, the next agent may “fix” the application back to the stale spec. Require behavior changes to update the relevant agreement, or explicitly archive that agreement. More persistent context helps only when it remains accurate.

Act now if your agent repeatedly misses permissions, edge cases, integrations or acceptance criteria. Use the workflow for a feature whose ambiguity crosses components or reviewers.

Wait on a formal spec if you are still discovering whether anyone wants the feature. Build a disposable prototype or investigate the unknown first. A polished specification for an unvalidated idea can make the wrong investment feel settled.

Keep small fixes small when the intended change is obvious and localized: a typo, an established-style adjustment or a narrow bug with a clear regression test. State the intended behavior and verify it. A full constitution, plan and task cycle can cost more attention than that change needs.

The decision rule is not lines of code. It is how many consequential assumptions the agent would otherwise have to make.

Spec Driven Development: Your First Week

Pick a small feature already on the backlog. Have its owner approve a one-page behavioral spec, including exclusions and failure cases. Use your current agent in planning mode, or the corresponding Spec Kit or Kiro flow, to propose a repository-grounded plan.

Review the questions before implementation. Ask for a task list that connects to the requirements. At the pull request, check evidence against the same agreement and record the decisions that changed. Keep the process only as heavy as the ambiguity warrants.

Subscribe to the newsletter for practical ways to build and operate with AI.