Requirements, Specs & Design

What changes

In a classical SDLC a requirement passes through a person before it becomes code. A developer notices that the ticket contradicts last quarter's decision, asks, and builds something slightly different from what was written. That informal correction disappears when the reader is an agent, which fills gaps with plausible guesses and keeps going.

The tools now say this outright. GitHub launched Spec Kit in September 2025 as "our experiment" in moving from "code is the source of truth" to "intent is the source of truth". Its workflow runs Specify, Plan, Tasks, Implement. Kiro keeps three files per feature, requirements.md, design.md and tasks.md, and writes requirements in EARS notation: "WHEN [condition/event] THE SYSTEM SHALL [expected behavior]" (vendor docs, as of October 2026). The premise is the same: if the agent implements whatever the spec says, the spec is where the product is decided.

The failure that follows from a bad spec is well documented. When Answer.AI handed 20 real tasks to Devin, the agent "would spend days pursuing impossible solutions rather than recognizing fundamental blockers" (see the case). GitHub's guidance for its coding agent reads like the remedy: keep "Tasks lacking clear definition" for humans, and give issues "Complete acceptance criteria" (vendor guidance, as of October 2026). An agent that cannot tell a task is unsatisfiable needs the spec to say so, or needs to be told to ask.

Two shifts follow, one for each half of this chapter.

• Requirements become an artefact the agent consumes. They must be complete enough to implement and specific enough to verify. How much time that is worth depends on the size of the change.
• Design decisions become context, not delegation. An architect still decides. What changes is where the decision is recorded: somewhere the agent reads on every run. Anthropic's Claude Code guidance lists "Architectural decisions specific to your project" among the things an instruction file should include, and "File-by-file descriptions of the codebase" among the things to leave out (vendor guidance, as of October 2026).

Developers are wary of AI here. In the Stack Overflow 2025 survey, 69.2% of respondents said they "don't plan to use" AI for project planning, against 28.9% for writing code (survey). Use is rising anyway. Inside Anthropic, design and planning grew from 1.0% to 9.9% of Claude Code use between February and August 2025 (Anthropic, T3, 200,000 transcripts classified by the vendor on its own product). Whether "deciding" becomes the next constraint after verification is a reasoned expectation, not a finding (where the constraint goes next); this chapter does not settle it.

The ladder for this phase

The maturity model keeps two rows for this chapter, requirements and design, because they climb differently. The criteria below are the same as there; here each grid is followed by what the evidence means. A level is what a human reviews, given the authority the AI holds, and it is scored per task type (the rules).

Requirements

What the rows mean. The step from L1 to L2 is not "the AI writes better drafts". It is a change of authorship plus a new gate: the agent produces the whole spec, the spec lives where the implementing agent will read it, and a named person approves it before code starts. Without a record of that approval for every spec of the task type, the team is at L1 with extra paperwork.

L3 has a mechanism but no record: Kiro can generate a spec with the gates off, and nobody has published what that does to defect or rework rates. So the L3 criterion is narrow on purpose, routine inbound items rather than features, and the oracle principle still applies. For a bug report, the natural check is a reproduction test that fails before the fix. That pairing is the book's proposal, not a documented practice.

The L4 row is deliberately small. Berkeley's RDI group describes a "Demand Autonomy" level in which the AI "decides what should be built", and says evaluation infrastructure for it "barely exists" (Berkeley RDI, July 2026, position piece, no data). This book keeps that out of the grid: deciding what to build is a product decision with an accountable owner. The only L4 candidate is clerical work on the ticket queue, and it has no published precision figures.

Design

What the rows mean. Design has the thinnest evidence of any phase in this book, and the gaps point one way. The lab studies say an LLM can draft a plausible ADR, not that it can choose well under constraints that live outside the repository. The production bots agree from the other side: Uber's uReview post states that the tool "today only has access to the code", so design review stays with people.

The L3 cell is empty because nobody has published an architecture fitness function that gates agent changes and reports what it caught. The idea has a practitioner sponsor: the April 2026 Thoughtworks Technology Radar recommends "architectural fitness functions" as one countermeasure to what it calls codebase cognitive debt, "the growing gap between a system's implementation and a team's shared understanding of how and why it works". A recommendation is not a result.

So staying at L1–L2 for design is a choice, not a failure to climb. The productive work is the second half of the L2 criterion: once a person makes a decision, record it where the agent will follow it.

The case: three spec-driven tools, read by a practitioner

No organisation has published a controlled study of spec-driven development. The most useful single source is qualitative. In October 2025 Birgitta Böckeler of Thoughtworks tried Kiro, Spec Kit and Tessl on tasks of different sizes and wrote down what happened.

A vocabulary for spec depth. Böckeler separates three ways of using a spec:

• Spec-first: "A well thought-out spec is written first, and then used in the AI-assisted development workflow for the task at hand."
• Spec-anchored: "The spec is kept even after the task is complete, to continue using it for evolution and maintenance".
• Spec-as-source: "The spec is the main source file over time, and only the spec is edited by the human, the human never touches the code."

She placed Spec Kit and Kiro as essentially spec-first, and Tessl as "the only one of these three tools that explicitly aspires to a spec-anchored approach". The taxonomy matters for migration. Spec-first is an L2 practice. Spec-as-source claims that humans can stop reviewing code, an L3 or L4 claim about coding for which no evidence has been published.

The size problem. When Böckeler asked Kiro to fix a small bug, "it quickly became clear that the workflow was like using a sledgehammer to crack a nut." Spec Kit "felt like overkill for the size of the problem". Her general verdict: each tool offers one opinionated workflow, and "neither of them is suitable for the majority of real life coding problems." An effective tool, she argues, "would at the very least have to provide flexibility for a few different core workflows, for different sizes and types of changes."

The review problem. At L2 a human must review the markdown these tools produce. Böckeler: "To be honest, I'd rather review code than all these markdown files." If the spec is the product, an unread spec is an unreviewed product.

The control problem. Under the heading "False sense of control?", she reports: "Even with all of these files and templates and prompts and workflows and checklists, I frequently saw the agent ultimately not follow all the instructions." A spec is an instruction to the agent, not a check on it. It constrains the output only as far as something verifies the output against it.

Her conclusion fits this chapter's argument: "I'm very skeptical that lots of up-front spec design is a good idea, especially when it's overly verbose." The Thoughtworks Radar placed SDD at Assess, not Trial, in November 2025. It called the workflows elaborate and opinionated, noted that results vary with task size and type, and wondered whether hand-crafted rules for AI will repeat the "bitter lesson" (practitioner panel opinion).

The outcome data that exist

Since Böckeler wrote, three studies have measured something. All three are weak, and they should be read together.

An association study. The EPIC framework scored the specs of 114 open-source spec-driven repositories, found through Spec Kit and OpenSpec layouts and common spec file names, against ISO/IEC/IEEE 29148. Repos in the top third for spec quality spent "11.8% of their commits on bug fixes, compared with 20.4% in the bottom third". They also had 15.4% lower cyclomatic complexity per thousand lines. Bugs per thousand lines differed by 5.1%, which was not significant.

The authors state the limit themselves: "Without multivariate controls or stratified analyses, project characteristics and development practices remain potential confounders". One confounder is visible in their data. The top-third repos had a median of 12.5 contributors against 3. Better-resourced projects may write better specs and also fix fewer bugs, for the same underlying reason.

An uncontrolled pilot. A single-organisation Spec Kit pilot followed 14 engineers (8 mid-level, 6 senior; juniors excluded) on three web projects through two months of baseline and two months with Spec Kit. Rollbacks fell from 2–4 to 0–1 a month, and late-stage hotfixes per sprint fell from 3–5 to 1–2. Median lead time per feature moved from 8–12 to 6–9 working days. Writing the spec and plan cost 45–90 minutes per medium-sized feature.

The paper lists its own gaps: "The absence of a parallel control group", and "Temporal confounds (e.g. improving AI model capabilities during the study period) cannot be excluded". The rollback numbers are encouraging. The overhead figure is the most transferable result, because it is the one a team can check against its own calendar.

An LLM-judged experiment. A Spec Kit Agents study ran 128 runs over 32 feature tasks in five open-source repos. An LLM judge scored quality on a 1–5 scale: 3.46 with no spec, 3.51 with stock Spec Kit, and 3.66 with the authors' augmented variant, which raised run time from 24.0 to 37.2 minutes. In 60 human preference votes between stock and augmented output, 33 were ties, 19 favoured stock Spec Kit and 8 the augmented variant.

Read together: better specs go with fewer bug fixes, perhaps not causally; a spec habit in one organisation went with fewer rollbacks for about an hour per medium feature; and stock tooling barely moved judged quality. Nothing has been published on Kiro or Tessl beyond vendor material. A spec habit is promising. A spec tool is unproven.

The design half: what humans reject

The best production data on agent design comes from the closure reasons in Microsoft's ten-month log of GitHub's Copilot coding agent in dotnet/runtime (the main case is in case studies). Of 253 agent PRs closed without merging, 16% were closed as "wrong approach" and 8% as "design rejected". On the PRs that did merge, only 1.8% of human review comments (92 comments) were architectural.

On scoped tasks the agent seldom gets the architecture wrong in a way reviewers comment on. When it does, the whole PR is thrown away: about a quarter of the closed PRs failed on design. People caught them, as L2 requires. The cheaper fix is to give the agent the design before it starts, not to review harder afterwards.

The other side of the record shows what happens when nobody holds the design. In 2025 researchers scanned 1,645 apps showcased by the app generator Lovable and found 303 endpoints across 170 of them whose data could be read without authentication (CVE-2025-48757). The researchers say the platform's security scan only checked that a row-level security policy existed, not that it worked. The CVE record notes that Lovable disputes it, on the grounds that customers own their app's data protection. In early 2026 Wiz found that Moltbook, whose founder said "I didn't write a single line of code", exposed 1.5 million API tokens and 35,000 email addresses through a client-side key and no row-level security. It was fixed about three hours after Wiz made contact. Wiz's diagnosis: today's AI tools "don't yet reason about security posture or access controls on a developer's behalf".

Neither had a design phase, which is the point: who may read which rows was left to a generator, and nobody reviewed it. Security architecture is the design decision that cannot be delegated. The security, permissions and blast radius chapter covers the code surface these cases sit on.

Worked example: how much spec a change can afford

This is illustrative arithmetic. It names no organisation and uses the one published overhead figure.

Spec + plan overhead (Spec Kit pilot):     45-90 min per medium feature
Medium feature lead time (pilot, after):   6-9 working days = 48-72 h
  Overhead as share of lead time:          0.75 h / 72 h = 1.0%
                                           1.5 h / 48 h  = 3.1%
One-sentence change, done directly:        ~20 min (illustrative)
  Same overhead applied to it:             45-90 min = 2.3x-4.5x the change

For a medium feature, an hour of spec work is a rounding error on lead time, and buys an artefact the agent and the reviewer can both check against. For a one-line fix the same ritual costs several times the change: Böckeler's sledgehammer, in minutes. Anthropic's guidance draws the line in one sentence: planning "adds overhead", so "If you could describe the diff in one sentence, skip the plan." Spec depth is a dial set per task, not a policy set per team.

Migration steps

Climb one rung at a time, for one named task type, writing down the evidence at each rung. Requirements can climb to L2 now; design should climb to L2 and stop. Chapter 14, The 90-Day Pilot, recommends maintenance as the lowest-risk first pilot, so treat this phase as a later climb.

L0 → L1: let AI draft, keep human authorship.

1. Allow AI to draft user stories, PRDs and ADR text, and to summarise legacy code into a draft spec. A human rewrites and owns every artefact that leaves the draft stage.
2. Record usage by tool telemetry, not self-report, so you know which task types it is used for.
3. Start an ADR log if you have none; the next rung depends on written decisions.

L1 → L2 for requirements: an interview, a spec, a fresh session.

1. Pick one named, recurring task type, such as "medium features in service X". Not "all requirements".
2. Adopt the practice before the tool. Anthropic's version: for larger features "have Claude interview you and write a spec before you start implementing", then "start a fresh session to execute it". Any agent can do this; Spec Kit and Kiro package the same steps.
3. Use a fixed spec shape. The most useful specs "name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works". Add acceptance criteria in a testable form; EARS is one option. Appendix A, Templates, carries a spec template.
4. Set the size rule before the first spec, in writing: if the diff can be described in one sentence, no spec.
5. Keep the spec in the repository next to the code, and record a named approval for every spec before implementation starts. That approval log is the L2 evidence.
6. Attribute agent-written specs (label, trailer or front matter), and track rework for the task type: specs revised after implementation began, and PRs closed for "wrong approach".

L1 → L2 for design: the agent proposes, a person decides, the decision becomes context.

1. Have the agent propose options in plan mode or a design file for changes that touch more than one component. A person chooses and writes the reason.
2. Turn each accepted decision into a short ADR, and put the decisions that constrain everyday code into the agent's instruction file. Keep the entry to the rule and link the ADR for the reasoning. The wiki compares the instruction-file formats.
3. Where a decision can be checked mechanically (a dependency rule, a layer boundary, a ban on a library), enforce it with a deterministic check in CI rather than prose. The coding chapter covers instruction files and hooks in depth.
4. Record closure reasons on agent PRs, including "wrong approach" and "design rejected", so you can see whether the recorded decisions are reaching the agent.

L2 → L3 for requirements: only routine inbound items, only with a verifier. There is no published case to copy, so this rung is the book's proposal.

1. Limit it to one class of routine inbound item, such as bug reports against a single service. Features stay at L2.
2. Give the class a verifier the agent cannot edit. For a bug report, that is a reproduction test that fails on the current code and that the implementing agent may not change (the oracle principle).
3. Write the routing rules that send ambiguous, security-related or cross-team items to a human, and enforce them in the tooling.
4. Compare escaped defects and rework for the generated tickets against a human-written baseline over 90 days before you call it L3.

Design above L2: don't. There is no L3 evidence and no tested verifier. If you build architecture fitness functions, run them as checks at L2 and publish what they catch.

Guardrails

The guardrails for this phase protect the acceptance criteria, the decisions that must not be reopened, and the boundary of what the agent may decide at all.

• Freeze the acceptance criteria once approved. The implementing agent may propose a spec change, but may not edit the acceptance criteria or the verification step it will be judged by. A spec whose success condition the agent can rewrite is not a spec at L3, by the oracle principle. Protect the files with code ownership or a hook, not with a sentence asking the agent to leave them alone.
• Put mandatory rules in deterministic checks. Anthropic's guidance makes the distinction itself: "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens." Böckeler's observation that the agent did not "follow all the instructions" is the reason. Anything that must hold goes in a test, a lint rule or a hook.
• Keep security architecture human-owned and tested. Who can read which data, where secrets live, which endpoints need authentication: a named person decides these, and a test the agent cannot edit checks them. Lovable's scanner checked that a policy existed, not that it worked. Test the behaviour. The security, permissions and blast radius chapter sets the permission envelope that goes with each level.
• Keep the instruction file short and human-written. The April 2026 Thoughtworks Radar puts "Agent instruction bloat" in its Caution ring: "As instructions grow, the likelihood increases that important rules are ignored", and "hand-written versions are often more effective than LLM-generated ones" (opinion). Recorded decisions only work if they survive in a file the agent follows; the coding chapter covers the evidence on instruction files.
• Treat inbound text as untrusted once there is no human gate. At L3, a bug report written by an outsider becomes an input the agent acts on without review. That is a prompt-injection surface, and the permission envelope for L3 in the security chapter applies.

The wiki's notes on plan review and editing and context engineering cover the mechanics of reviewing a plan and of what reaches the agent's context.

Metrics

Measure whether the spec habit pays for itself, and whether recorded decisions reach the agent. Pair each flow metric with a stability metric, as Chapter 17, Measuring Success and When to Roll Back, sets out for every phase.

• Spec overhead: minutes per spec, by task size, against lead time for the same task type. The one published reference is 45–90 minutes per medium feature (T3). If small changes carry that cost, the size rule is not working.
• Closure reasons on agent PRs: the share closed as "wrong approach" or "design rejected". dotnet/runtime's 16% and 8% are a reference, not a target. A falling share after decisions move into the instruction file is the signal that the design work is reaching the agent.
• Spec churn after implementation starts: how often an approved spec is revised mid-build. High churn means the interview missed things, or the size rule sent the wrong tasks through the spec path.
• Bug-fix share and early reverts for spec'd work against un-spec'd work of the same type: the share of commits that are bug fixes (EPIC's measure) and lines reverted within two weeks (the pilot's). Both are stability metrics a team already has in version control.
• Spec review time: how long approvers spend per spec. Near zero for long specs means nobody is reading them, which is the review problem in 5.3.

Do not measure the number of specs written, or the share of specs drafted by AI. Both are volume metrics. They rise whether or not the specs are any good.

Anti-patterns

• The sledgehammer. Every change, however small, goes through the full requirements, design and tasks workflow. People route around it, and the process loses credibility for the features that need it. The fix is a written size rule.
• The unread spec. The agent writes pages of markdown, and an approver skims and clicks approve. The phase looks like L2 and behaves like L3 without a verifier. Write shorter specs, and record who read what.
• The spec as a control. Treating a detailed spec as a guarantee of compliance. The spec says what to build; tests, hooks and review decide whether it was built.
• The generated instruction file. Letting an agent write its own instruction file, then adding a rule after each mistake until recorded decisions stop reaching it.
• Delegated security architecture. Letting a generator decide access control because the app "works". Lovable and Moltbook show where that ends.
• "AI decides what to build." Turning product strategy or user feedback directly into roadmap items with no accountable owner. No evidence supports it.
• The impossible spec. Contradictory or unreachable acceptance criteria, and no instruction to stop and ask. The agent will pursue it, sometimes for days, or satisfy it by a shortcut. Tell it to raise clarifying questions, and give it a way to report that a task cannot be done.

The wiki's spec-driven agent development playbook covers tooling. Its essay on the AI-native SDLC artifact chain traces how the spec becomes the input to every later phase, including code review and testing, where the spec's verification step turns into a check.