Skip to main content
Spec-driven development for AI coding agents turns intended software behavior into reviewable requirements, design, and work artifacts before execution. People review decisions at each boundary. Agents use the accepted artifacts to implement the change, then return evidence that people compare with the accepted intent. Specification-driven development is another name for the same broad method. It is not one fixed file tree or one vendor workflow. The useful pattern is a controlled path from intent to implementation and back to evidence. Microsoft describes specifications as a shared source for requirements, constraints, acceptance criteria, and edge cases before AI-assisted implementation. A 2026 research paper separates three levels of rigor: spec-first, spec-anchored, and spec-as-source. The right level depends on the cost and life of the work. (Microsoft, Piskala, arXiv:2602.00180)
A human reviews requirements, webhook design, and implementation tasks before an abstract coding-agent process runs and returns source-diff and test evidence.

​
Use a reviewed artifact sequence

The files vary by framework, but a complete workflow must preserve five kinds of information:
  1. Requirements define observable behavior. Record the user outcome, scope, non-goals, constraints, edge cases, and acceptance criteria. A human reviews them before technical choices narrow the solution.
  2. Design explains the chosen solution. Record architecture, interfaces, data, failure behavior, security boundaries, and open assumptions. A human checks whether the design satisfies the requirements.
  3. A plan or task set makes the design executable. Name the work order, dependencies, affected areas, and validation for each meaningful unit. A human checks that the tasks preserve the design intent.
  4. Implementation changes the system. The agent follows the reviewed artifacts, reports discoveries, and stops when a new decision changes accepted behavior or risk.
  5. Evidence connects the result to the intent. Tests, source diffs, traces, screenshots, or runtime checks show what changed. A human compares that evidence with the acceptance criteria.
This sequence does not require a large document for every change. A small, reversible fix can use a short requirement and a focused plan. A multi-phase system change needs more durable state.

​
Put human review where decisions compound

Review each artifact before it becomes an input to more expensive work:
  • Review requirements before design. Remove vague outcomes and decide what remains out of scope.
  • Review the design before planning. Check technical assumptions, failure paths, interfaces, and operating limits.
  • Review the plan or tasks before execution. Check order, task boundaries, repository scope, and verification steps.
  • Review implementation evidence before acceptance. Compare the current result with the accepted requirements, not with the agent’s summary.
The review depth depends on risk. Authentication, data migration, tenancy, billing, and public interfaces need more evidence than a local documentation fix.

​
Compare three current specification workflows

The comparison uses current primary sources. They are GitHub Spec Kit v0.16.1, Kiro Specs captured August 10, 2026, and GSD Core v1.10.0. These profiles describe artifact shape and workflow. They do not show that one framework produces better code. For a direct two-framework decision, use GitHub Spec Kit vs. Kiro Specs. The framework chooser covers other planning methods and artifact models.

​
Inspect the same reliable-webhook case

The public spec-planning-frameworks repository applies several frameworks to one reliable-webhook-delivery brief. The brief requires signed delivery, idempotency, retry backoff with jitter, dead-letter handling, replay, audit history, tenant isolation, observability, and acceptance tests. It leaves the queue, database, web framework, signing algorithm, limits, retention, hosting, and interface decisions open.

​
GitHub Spec Kit completed its planning flow

The July 19 run used Spec Kit 0.13.1.dev0 at commit 57cc518d. It produced a constitution, checklist, research record, data model, four contracts, and quickstart. Inspect the specification, plan, and 69-task list. The run selected Fastify, PostgreSQL, and Prisma. Those are run decisions, not shared case requirements. (Run provenance)

​
GSD created project state but not a phase plan

The run used @opengsd/gsd-core@1.7.0. It produced project context, 18 requirements, a five-phase roadmap, and state. The run then created Phase 1 context. The phase-plan run stalled and was interrupted. No completed plan is present. (Run provenance)

​
Kiro is a manual, source-faithful example

The authenticated Kiro workflow was unavailable for the comparison. The repository contains three original, source-faithful files: requirements, design, and tasks. Each file follows Kiro’s documented artifact model. Every file states that it was not generated by Kiro. The files are inspectable workflow evidence, not vendor output. (Example provenance)

​
What this case can and cannot show

The repository compares artifact shapes and workflow evidence for one TypeScript backend case. It does not compare implemented systems, code quality, model quality, delivery time, or production reliability. A completed document also does not prove that its requirements are correct. The framework versions used in the July run are older than the current sources in the comparison table. The generated files preserve the behavior of those pinned runs. Do not treat an unmerged benchmark branch or a local experiment as published results.

​
Watch for eight failure modes

  1. Vague requirements. Terms such as fast, reliable, secure, or scalable do not define an observable finish line.
  2. Hidden assumptions. The specification chooses a queue, database, identity boundary, or limit without naming the decision.
  3. Stale specifications. Code or runtime behavior changes while the document continues to describe an earlier system.
  4. Tasks that lose intent. A task list names files and edits but drops the reason, constraint, or acceptance criterion.
  5. Ceremony larger than the work. The framework creates more artifacts and reviews than a small, reversible change needs.
  6. Unreviewed generated detail. An agent fills gaps with plausible architecture, limits, or edge-case behavior that nobody accepted.
  7. Source and runtime drift. The repository, deployed system, configuration, or external service no longer matches the specification’s evidence.
  8. False confidence from completion. A complete document looks authoritative even when tests, implementation evidence, or human review are missing.
The remedy is not always more text. Name the decision, link the evidence, assign the review point, and remove artifacts that do not help a later decision.

​
Choose the smallest durable artifact

​
Use a technical specification for one bounded design

Choose a technical specification when one feature or system change needs requirements, interfaces, risks, and acceptance criteria in one reviewed document. This works well when the implementation can fit inside one coherent design.

​
Use an AI coding plan for one implementation pass

Choose an AI coding plan when the outcome and design are already known. The plan must connect ordered code changes to verification. The planning guide explains how repository research and new evidence can revise that plan.

​
Use a project framework for durable state

Choose a project framework when work spans phases, agents, or context windows. The framework must preserve decisions, current state, completed evidence, and the next safe action. The cost of that state must remain smaller than the cost of rebuilding context.

​
Keep the specification current

Implementation exposes facts that planning cannot know. Record a discovery when it changes the work. Ask a human to review it when it changes behavior, risk, or scope. Then choose a persistence rule. Update the main specification, create a follow-on specification, or maintain a living specification beside the code. Spec Kit documents these as flow-back, flow-forward, and living-spec policies. (Spec Kit v0.16.1) The living documentation guide explains how to keep current system truth separate from historical plans and decisions.

​
Review the artifact before the agent runs

Open-source Plannotator can display and annotate local Markdown plans and specifications. It can return feedback to supported coding-agent sessions and compare revised submissions. Use the local plan review workflow to inspect requirements, design decisions, and tasks before execution.
Plannotator provides a review surface. It does not make the specification correct, execute a framework, or replace implementation evidence.

​
Source record

  • Method sources: Microsoft article published June 10, 2026, and arXiv:2602.00180 submitted January 30, 2026. Both were checked August 10, 2026.
  • Current framework sources: GitHub Spec Kit v0.16.1, GSD Core v1.10.0, and Kiro Specs documentation updated August 4, 2026. All were checked August 10, 2026.
  • Same-case evidence: plannotator/spec-planning-frameworks at commit 7bfffe891436c02e0b9ecccc65ceb0b64c2a0701, dated July 19, 2026.
Last reviewed August 10, 2026. Researched and maintained by the Plannotator documentation team.
Last modified on August 10, 2026