Write a Spec an Agent Can Build From: A Step-by-Step Guide

Ask an agent for “an export button on the monthly view” and you will get an export button. It will probably run, and it may even look right. It may also ignore the filters on the screen, ignore who is allowed to see which rows, and quietly decide what the file should be called. You asked; it answered the question as written. The meaning you carried in your head never reached it.

A spec is how you move that meaning out of your head and into the repository. It earns its keep on features that touch several files, not on a one-line bug fix. One caveat up front: the case for spec files specifically rests on vendor practice and judgement, not on a controlled trial. The evidence for asking questions first is firmer, and that is where we start.

What the Evidence Says

01 · Evidence · ICLR 2026 · Vendor guides · Thoughtworks

Clarifying questions help; spec files are still a judgement call

A study accepted to ICLR 2026 looked at coding agents working on GitHub issues that were underspecified. The agents struggled to tell a well-specified instruction from an underspecified one. When they were pushed to ask clarifying questions, results improved by up to 74%.

The practice side agrees. Both Anthropic and OpenAI publish best-practice guides for their coding agents, and both advise interviewing before coding rather than after. On the cautious side, the Thoughtworks Technology Radar placed spec-driven development at “Assess” in November 2025, meaning worth exploring but not yet proven. Birgitta Böckeler, writing on martinfowler.com, compared the spec tools and warned that reviewing the generated code still matters more than reviewing the markdown.

Hold both thoughts. A spec is cheap insurance against misunderstanding; it is not a substitute for reading what the agent built.

Step 1: Plan Before the Agent Writes Code

02 · Done when you have a plan you have read

Make the agent look before it leaps

Both major coding agents have a mode that keeps them from editing anything while they read the code and propose an approach. Use it per task, at the start, so the first thing you review is a plan rather than a diff.

Claude Code

Codex

One practical detail: Claude Code saves its plan files by default to ~/.claude/plans/, which sits outside your repository. A plan that lives only there will not travel with the code, which is the first reason to carry the useful parts into a spec file in Step 3.

Step 2: Settle the Open Decisions First

03 · Done when no unknown is left as a guess

An unmarked unknown becomes a silent guess

Before a larger feature, ask the agent to interview you. Let it put questions to you about the parts the request leaves open, and answer them in writing. The goal is not a long conversation; it is that every real fork in the road gets a decision from a person.

Whatever you cannot answer yet, mark it. Write [OPEN] next to the question rather than letting anyone assume. The same idea appears elsewhere: GitHub Spec Kit uses a [NEEDS CLARIFICATION] marker for exactly this. A spec that still contains an open marker is not ready to build, and that rule is easy for an agent to follow.

Step 3: Write the Spec as a File in the Repo

04 · Done when the spec is committed

Five sections, one screen

Keep the spec short enough to read in a single screen. Five sections are enough: the Problem you are solving, the Scope it covers and does not, the Decisions already made, the Acceptance criteria, and the Tasks. Commit it as specs/<feature>.md so it is reviewed, versioned and found by the next person, or the next agent.

This is where the wider tooling sits. GitHub Spec Kit and Kiro both build workflows around spec files; Thoughtworks, as noted, files the whole approach under “Assess.” You do not need any of them. A markdown template and a habit will do.

specs/_template.md

Then tell the agent about the template and the rules around it, once, in the instruction file it reads on every run (CLAUDE.md for Claude Code, AGENTS.md for Codex).

Instruction file, section “Specs”

Step 4: Write Acceptance Criteria a Test Can Check

05 · Done when every criterion has a check

If a test cannot fail it, it is not a criterion

“It should work properly” cannot be checked by anyone, human or machine. A criterion needs a trigger and an observable result. A well-worn format for this is EARS, the Easy Approach to Requirements Syntax, created at Rolls-Royce in 2009. Its event pattern reads in one line: When <trigger>, the <system> shall <response>.

The sentence is rigid on purpose. It forces you to name what sets the behaviour off and what must come out, and the second half is very nearly the assertion a test would make. Here are three illustrative rows, using the CSV export from earlier, moving from vague to checkable to the test behind it.

Notice that the third row replaced a fuzzy worry (“big months”) with a precise edge case the agent can actually handle. Rewriting a vague line into EARS often reveals that it was hiding a decision you had not made yet.

Step 5: Split the Work into Tasks the Agent Can Finish

06 · Done when each task has an end

Small enough to finish, ordered enough to follow

Break the feature into tasks, each small enough that one fresh session can complete it. A good task names what it depends on and states a done-when condition that points back at the criteria. Something like “done when AC1 passes” leaves no room for the agent to declare victory early.

• Size. One task, one coherent change, one pull request that a person can review without a headache.
• Dependencies. Write “depends on” next to any task that cannot start before another finishes, so the order is in the file, not in someone's memory.
• Done when. Tie every task to the criteria that prove it, so finishing is a check, not a feeling.
• One home. Keep the task list inside the spec file. The checklist then shows progress, and a new session can read where the work stands.

Step 6: Build from the Spec, and Check Against It

07 · Done when the diff matches the spec

The spec only works if the build keeps faith with it

Run each task in a fresh session so the agent starts from the spec instead of from a long, drifting conversation. Give it a rule for the moment the spec and the code disagree: stop and ask, then update the spec. And when the work comes back, review the diff against the spec, and tie each acceptance criterion to the “how it was checked” section of your pull-request template, so the evidence travels with the change.

Instruction file, section “Working from a spec”

The Playbook in Six Lines

1. Plan first, in the agent's plan mode, before it touches any code.
2. Let it interview you, and mark every unanswered question [OPEN].
3. Commit a one-screen spec: Problem, Scope, Decisions, Acceptance criteria, Tasks.
4. Write each criterion so a test can fail it.
5. Cut the work into tasks with dependencies and a done-when condition.
6. Build one task per fresh session, and review the diff against the spec.

An agent always fills the gaps you leave. The spec is simply where you decide which gaps it gets to fill.

Every gap gets filled. Decide which ones the agent may.