Spec Writing Is the New Coding Skill: What Spec Kit and Kiro Make You Write

GitHub Spec Kit asks your team to produce 7 planning artifacts for every feature before an agent writes a line of code. AWS Kiro asks for 3. Both tools have made spec writing the step that decides whether agent output is usable, and both quietly move the most valuable work on your team from the keyboard to the document. The question for anyone running delivery is who writes those documents, and who reads them.

The short answer. Spec writing for AI agents means producing a requirements document, a design document and an ordered task list before an agent implements anything. GitHub Spec Kit splits that into about 7 files per feature plus a constitution. AWS Kiro uses 3 files plus steering files. The hard part in both is writing acceptance criteria a reviewer can check.

What spec-driven development asks you to write

Spec-driven development is a workflow where a human-approved document, not a chat prompt, is the input to a coding agent. The agent drafts most of the document. A person edits and approves it. Then the agent implements against it.

That sounds like old-fashioned requirements engineering, and in structure it is. What changed is the economics. When writing code was the expensive step, a long specification was overhead. When an agent writes the code in minutes, the specification is the only part of the work where a human decision still shapes the result.

Birgitta Böckeler of Thoughtworks gave the field its most useful vocabulary in her October 2025 review of Kiro, Spec Kit and Tessl. She separates three levels of commitment, and the level you pick decides how much writing your team signs up for.

Spec-first, spec-anchored, spec-as-source

In a spec-first workflow, a spec is written before the task and then left behind. In a spec-anchored workflow, the spec is kept and updated as the feature evolves. In spec-as-source, the human edits only the spec and never touches the code.

Böckeler classes Kiro as mostly spec-first. Spec Kit's own essay, spec-driven.md, reaches for something closer to spec-as-source. The evidence from public repositories, covered below, says almost everyone actually practises spec-first, whatever the tool's ambition. That gap matters more than any feature difference between the two products.

GitHub Spec Kit: seven artifacts per feature and a constitution

Spec Kit is an MIT-licensed toolkit from GitHub that installs as a command-line tool and a set of slash commands for your coding agent. The repository had about 142,000 stars when we read it, and its integrations page lists more than 40 agent targets, including Claude Code, GitHub Copilot, Cursor, Gemini and Kiro's own command-line tool.

The README describes the loop plainly: create a constitution once per project, then repeat specify, plan, tasks and implement for every feature. Each step writes files into a numbered feature folder such as specs/001-feature-name.

The constitution is a rules file with teeth

The constitution lives in a memory folder and holds principles that every change must respect. Böckeler called it "basically a very powerful rules file," which is accurate. The shipped template is mostly blank: 5 named principle slots, 2 extra sections, governance rules, and a version line with ratification and amendment dates.

The methodology essay goes much further. It describes nine articles, including a Library-First rule, a Test-First rule marked "NON-NEGOTIABLE", and a Simplicity rule capping initial work at 3 projects. Here is the detail worth knowing: the tasks template itself says tests are "OPTIONAL - only include them if explicitly requested." The essay and the template disagree, so your constitution is where your team settles it. We think that is the single most important paragraph your senior engineers will write all quarter.

spec.md describes what and why, with numbered requirements

The specify step produces spec.md from a template with three mandatory sections. User Scenarios and Testing holds prioritised user stories, each with a reason for its priority, an independent test, and acceptance scenarios written as Given, When, Then. Requirements holds numbered functional requirements, FR-001 onward, phrased as "System MUST". Success Criteria holds measurable outcomes, SC-001 onward.

The template also forces honesty about gaps. Anything underspecified gets an inline marker, for example "[NEEDS CLARIFICATION: auth method not specified]". An optional clarify command then questions you about every marker. That one convention is worth copying even if you never install the tool.

plan.md, research, contracts, then a task graph

The plan step writes plan.md with a Technical Context block covering language, dependencies, storage, testing, platform, performance goals and scale. It runs a Constitution Check gate before research and again after design. Violations must be justified in a Complexity Tracking table that names the simpler alternative and why it was rejected.

The same step generates research.md, data-model.md, quickstart.md and a contracts folder. Then the tasks step writes tasks.md: IDs like T001, a [P] marker for tasks that can run in parallel, and a story label like [US1] that ties every task back to a user story. A Foundational phase must complete before any story work begins.

AWS Kiro specs: three files and one sentence pattern

Kiro is an agentic development environment from AWS, launched in preview on 14 July 2025 with specs as its headline feature. Its pitch was explicit: Kiro is "great at vibe coding" but its strength is getting prototypes into production through specs and hooks.

The spec model is lean. Per the Kiro documentation, requirements.md "captures user stories, acceptance criteria, or bug analysis in structured notation". design.md documents architecture, sequence diagrams and implementation considerations. tasks.md is an implementation plan of discrete, trackable tasks. All three sit in a .kiro/specs folder that lives in version control.

EARS acceptance criteria make requirements testable

Kiro writes acceptance criteria in EARS, the Easy Approach to Requirements Syntax. The documented pattern is "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]". The docs' own example reads: WHEN a user submits a form with invalid data THE SYSTEM SHALL display validation errors next to the relevant fields.

That constraint is the most useful thing in either tool. A sentence in that shape names a trigger and a single observable result, so a reviewer can say yes or no to it. Kiro uses the same requirements to drive property-based tests, which generate many random inputs to check the stated behaviour holds.

The workflow runs Requirements, then Design, then Tasks by default, with a Design-First variant that reverses the first two. A Review button on each document opens a comment mode, so approval happens phase by phase. A Quick Spec mode generates all three files in one pass, and the plain vibe mode saves no spec at all.

Steering files and bugfix specs do the constitution's job

Kiro has no constitution. Its equivalent is steering: product.md, tech.md and structure.md in a .kiro/steering folder, which the docs say are "included in every interaction by default". Steering files can also load conditionally when matching files are open.

Bugfix specs are where Kiro is ahead. They replace requirements.md with bugfix.md, which has three sections: current behaviour, expected behaviour, and unchanged behaviour. The third is written as "WHEN [condition] THEN the system SHALL CONTINUE TO [existing behavior]". A regression list written before the fix is the cheapest insurance an agent-written patch can carry, and we would add it to every spec, not only bug fixes.

Spec Kit vs Kiro: the required spec artifacts side by side

Put the two next to each other and the difference is not philosophy. It is granularity. Both ask for requirements, design and tasks. Spec Kit splits design into five files and adds a governing document. Kiro keeps design in one file and pushes project context into steering.

A spec writing template that works in either tool

Neither tool's template is what we would hand a team on day one. Spec Kit's spec.md is thorough but long. Kiro's requirements.md is tight but lacks a regression list outside bug fixes. The version below takes the parts of each that earn their place and drops the rest.

It maps directly onto both tools. The top half becomes spec.md or requirements.md. The middle becomes plan.md or design.md. The bottom becomes tasks.md in either. Write the top half yourself and let the agent draft the rest for you to edit.

# Feature: [name]
  maps to: spec.md (Spec Kit) or requirements.md (Kiro)

## Why this, why now
  One paragraph. The problem, who has it, what it costs today.

## User stories, in priority order
  US1 (P1): As a [role], I want [action], so that [outcome].
    Independent test: [how to verify US1 alone].
    WHEN [event] THE SYSTEM SHALL [one observable result].
    WHEN [error condition] THE SYSTEM SHALL [safe result].

## Must not change
  WHEN [condition] THE SYSTEM SHALL CONTINUE TO [current behaviour].

## Out of scope
  [Things a reasonable agent might build that you do not want].

## Open questions
  [NEEDS CLARIFICATION: question, and who can answer it].

## Success criteria
  SC-001: [measurable outcome, with the number].

# Design   maps to: plan.md or design.md
## Constraints the agent cannot see in the code
## Data and interfaces touched
## Options considered, option chosen, and why

# Tasks    maps to: tasks.md
  T001 [P] [US1] [task] in [exact file path].

Three sections do most of the work. "Must not change" borrows Kiro's bugfix discipline. "Out of scope" exists because agents over-build, and Böckeler watched one go "way overboard" on a single constitution rule. "Constraints the agent cannot see" is the only design content an agent cannot infer by reading your repository, which is why it belongs to a human.

Keep each acceptance line to one trigger and one result. If a line needs "and" twice, it is two requirements. That rule alone does more for review speed than any tool choice, a point also made in our breakdown of how context engineering replaced prompt engineering.

What spec writing costs in review hours

The best public cost data is still one practitioner's notebook. Colin Eberhardt of Scott Logic rebuilt an application with Spec Kit and logged everything in a November 2025 write-up. His run took 33 minutes 30 seconds of agent time, produced 689 lines of code and 2,577 lines of markdown, and needed 3.5 hours of his review.

His plain iterative prompting run took 8 minutes of agent time and produced about 1,000 lines of code with no markdown. It needed a 15 minute code review and 9 minutes of testing and fixes. He judged the regular approach "around ten times faster". The two runs did not build identical output, so treat the comparison as directional, which Eberhardt himself does.

Ceremony scales badly downward

Böckeler's own tests found the same problem from the other direction. Kiro turned a small bug into 4 user stories with 16 acceptance criteria, which she called "a sledgehammer to crack a nut". Spec Kit produced 8 files for a feature she sized at 3 to 5 story points. Her verdict: "I'd rather review code than all these markdown files."

Token spend follows the same shape. In the Carnegie Mellon and Google study, one team on Reddit reported that spec-driven runs consumed two to three times as many tokens and took about twice as long. That is a single self-report, but it fits Kiro's pricing page, which says executing a spec task "typically" costs more than 1 credit. Kiro Pro is $20 a month for 1,000 credits, and spec and vibe prompts draw on the same pool. We cover the wider pattern in the bill for cleaning up vibe-coded software.

Who on the team does the valuable work now

Here is the shift that matters for anyone running delivery. In both tools, the hours that decide quality are spent writing the constitution or steering files, writing acceptance criteria, and reviewing the plan before tasks run. None of that is typing code. All of it needs someone who knows the system and the customer.

The Agarwal et al. preprint shows how teams actually behave. It is based on 21 interviews, 154 Reddit posts and comments, and a sample of 266 public repositories dominated by Spec Kit and OpenSpec files. It is a preprint and not yet peer reviewed. Its numbers describe public GitHub projects, not enterprise teams.

The author has become the senior role

If 98.3% of tracked spec files have one author, the spec is one person's model of the feature. That person now holds more leverage over the output than whoever presses implement. On most teams it should be the engineer with the deepest system knowledge, paired with whoever owns the customer outcome.

The preprint also found that 77.6% of spec files contain implementation detail, despite both tools telling authors to separate what from how. Our reading: engineers write specs the way they think, which is in code. That is not a failure. It is a sign the spec author and the senior engineer are already the same person. The product side of this shift is covered in what changes when product managers have agents that write code.

Review moves upstream, and juniors lose a rung

Reviewing a 300-line plan is harder than reviewing a 300-line diff, because there is no test to run against it. The bottleneck we described in the shift from writing code to reviewing it moves one step earlier, onto documents.

The people who lose most are junior engineers. Implementing a well-scoped ticket was how they learned the system, and in spec-driven workflows the agent takes that ticket. We would deliberately assign juniors the task-list review and the "must not change" section. Both force them to read the system closely, and both are low-risk places to be wrong. The wider pipeline problem is in our analysis of the junior developer pipeline.

Where the spec-writing argument is weakest

The case that spec writing is the new coding skill rests on evidence that is thinner than its advocates admit. Here is where it breaks.

First, the evidence base is small. The cost data is one practitioner's log. The usage data is one preprint built mostly from open-source repositories, where incentives to maintain documentation differ from a paid product team. No controlled comparison of spec-driven and iterative workflows on matched tasks has been published that we could find.

Second, practitioners already route around the method. The same preprint found people "commonly skipped SDD for small tasks, bugs, and one-off scripts", and 82.0% of specs described new features. If most engineering hours go to maintenance and fixes, spec writing is a skill for a minority of the week.

Third, the specs mostly go stale. With 81.5% of spec files committed once, the spec-anchored ideal is rare in practice. The paper records agents departing from specs mid-implementation and specs decaying as code changed. Böckeler warns that spec-as-source risks "the downsides of both MDD and LLMs: Inflexibility and non-determinism." Model-driven development promised the same separation of design from code two decades ago and never took off for business applications.

Fourth, the agents do not always obey. Böckeler "frequently saw the agent ultimately not follow all the instructions," including regenerating classes that already existed. A spec does not guarantee the output matches it. It only gives you something to check the output against, and that check still needs a human.

Our position, stated plainly: spec writing is a real skill and it is becoming the high-value part of feature work. It is not yet the new coding. For a bug or a small change, a good prompt and a fast code review still win.

Frequently asked questions

Where to start with spec writing this month

Pick one upcoming feature that has genuine ambiguity, not a bug. Have your most senior engineer on that area write only the top half of the template above, by hand, in under an hour. Then run it through whichever tool your team already uses, and record two numbers: the minutes spent reviewing generated documents and the minutes spent reviewing code.

Before you scale it, write the constitution or steering files as a team decision, not an individual one. Settle the test-first question explicitly, because the tools contradict themselves on it. If the review minutes exceed the code minutes on that first feature, shrink the process to Kiro-sized files before you abandon it.

Related reading