Spec template for spec-driven development (spec.md)
A spec for spec-driven development is a short markdown file that says what a change must do and how you will know it is done — why, the behaviour, the boundaries and the acceptance criteria — written before the coding agent starts, and kept after it finishes. Below is a template to copy, a filled-in example, how Spec Kit, OpenSpec and Kiro format theirs, and how a spec differs from CLAUDE.md.
I could write a spec that rivals an RFC, but at some point the context is too large and the model breaks down.
— a developer quoted in How to write a good spec for AI agents, Addy Osmani, 2026
What goes in a spec
- Status, version, owner, and who agreed it — so a reader knows whether it is still true.
- Why: the problem, and who has it. Two or three sentences.
- Requirements: each one a single observable behaviour, with an ID.
- Acceptance criteria for each requirement, in Given/When/Then.
- What must not change: the APIs, data and behaviour the change has to leave alone.
- Out of scope.
- Boundaries for the agent: what it may always do, what it must ask about, what it must never touch.
- Open questions, marked as open, not guessed.
- Decisions and changes, with dates.
What does not go in: the implementation plan and the task list. They belong in their own files — see “spec, plan and tasks” below.
The template
Save it as spec.md — or one file per feature, such as specs/export-orders.md. Everything in
square brackets is yours to fill in.
# Spec: [feature name]
Status: [draft / agreed / built /
superseded by ...]
Version: [x.y]
Owner: [name, role]
Agreed by: [name, role, date: the person
who decides]
Answers to: [goal, ticket or business
requirement]
## Why
[Two or three sentences: the problem, who
has it, and what changes for them when
this ships.]
## Requirements
- R1: [one behaviour, observable from
outside]
- R2: [ ]
- R3: [NEEDS CLARIFICATION: what is still
unknown]
## Acceptance criteria
R1
Given [the starting state]
When [one action]
Then [what anyone can see happen]
R2
Given [ ]
When [ ]
Then [ ]
## Must not change
- [existing behaviour, API or data to
leave alone]
## Out of scope
- [what this does not do, that someone
might assume]
## Boundaries for the agent
- Always: [e.g. run the tests before
finishing]
- Ask first: [e.g. schema changes, new
dependencies]
- Never: [e.g. touch secrets or the
CI config]
## Open questions
- [question], for [who], by [date]
## Decisions
- [date]: [what was decided, by whom, and
why]
## Changes since the last version
- [x.y], [date]: [what changed, why, who
agreed]
Spec example
# Spec: Export the orders list to CSV
Status: agreed
Version: 1.1
Owner: product owner
Agreed by: operations lead, 14 Oct 2026
Answers to: OPS-212: the monthly report
takes a day
## Why
Account managers rebuild the monthly
orders report by hand. They need the
filtered list as a spreadsheet.
## Requirements
- R1: An account manager can export the
orders list as it is filtered on screen.
- R2: The export holds only orders the
user may see.
- R3: An export holds at most 10,000 rows.
## Acceptance criteria
R1
Given the list filtered to "Shipped,
last 30 days"
When the account manager selects Export
Then a CSV downloads with exactly the
rows on screen
R3
Given a filter that matches 12,000
orders
When the account manager selects Export
Then they see "Narrow the filter to
10,000 rows or fewer"
## Must not change
- The JSON response of the /orders API.
## Out of scope
- Scheduled exports. Excel files.
## Boundaries for the agent
- Ask first: adding a CSV library.
- Never: change the /orders API.
## Changes since the last version
- 1.1, 14 Oct 2026: limit raised from
5,000 to 10,000 rows (OPS-219), agreed
by the operations lead.
More on writing the criteria in the acceptance criteria template.
Spec, plan and tasks: keep them apart
The spec says what and why. The plan says how: architecture, libraries, data model — a
technical specification by another name. The tasks are the
steps. Spec Kit keeps them in separate files — spec.md, plan.md, tasks.md — and its spec
template asks for success criteria that “must be technology-agnostic and measurable”. Mixing them
is one developer’s complaint about these tools: “they seem to miss the mark by coupling specification
(what the software should be) and execution (how to get there)”
(Hacker News, July 2026).
Kept apart, the spec can be agreed by someone who will never read the plan, and the plan can change without reopening the agreement.
How Spec Kit, OpenSpec and Kiro format a spec
- Spec Kit.
Requirements:
FR-001: “System MUST [specific capability]”, with user stories in priority order; unknowns marked[NEEDS CLARIFICATION: …]. Scenarios: Given/When/Then under each user story. - OpenSpec. Requirements:
### Requirement:with SHALL; a change lists its requirements as added, modified or removed. Scenarios:#### Scenario:with WHEN and THEN. - Kiro. Requirements:
EARS: “WHEN [condition/event] THE SYSTEM SHALL [expected
behavior]”. Scenarios: user stories with acceptance criteria, in
requirements.md.
The template above works with any of them, or with none: paste it into the agent’s chat, or keep it in the repository and point the agent at it.
spec.md vs CLAUDE.md and AGENTS.md
| Aspect | spec.md | CLAUDE.md or AGENTS.md |
|---|---|---|
| Covers | One feature or change | The whole project |
| Says | What this change must do, and why | How to work here: commands, conventions, layout |
| Read | When the change is worked on | At the start of every session |
| Changes | When the requirement changes | When the conventions change |
Anthropic’s documentation describes CLAUDE.md files as “markdown files that give Claude persistent instructions for a project”, and says to keep them “to facts Claude should hold in every session: build commands, conventions, project layout” (Claude Code docs). A feature’s requirements are not facts for every session; they go in the spec.
How to write a good spec for an AI agent
- Keep it short enough to read. Addy Osmani’s summary: “Aim for a clear spec covering just enough nuance … to guide the AI without overwhelming it.”
- Describe behaviour, not code. What a user or another system can see.
- One requirement, one behaviour, one ID, so the agent, the tests and the reviewer can point at it.
- Give every requirement acceptance criteria. They become the tests.
- Write what must not change. Otherwise nothing tells the agent to leave it alone.
- Set boundaries in three tiers — always, ask first, never — as Osmani suggests.
- Mark what is unknown instead of letting the agent guess.
- Have it agreed before the agent starts, by whoever decides — not only by the developer running the agent. See who reviews the spec.
- Split large features into specs that can each be built and checked on their own.
Each rule with the research behind it, and a vague spec rewritten by them: how to write a spec for an AI coding agent.
Keeping a spec current after the change
Opinions split. Spec Kit lets each team choose: keep each feature folder as a historical record,
keep spec.md as a living contract, or let discoveries flow back from the code. Others delete
specs once the work merges: “Why would I want to keep these files around forever? If you’re
keeping these files you’re just compounding drift onto drift and making it harder for the agent.
For everything else, there is git history”
(Hacker News, September 2026).
Whichever you choose, say so in the status line — a spec marked “built” or “superseded” is not mistaken for the current truth. What happens when nobody does is spec drift; what git can and cannot do about it is in requirements in git. One spec followed from version 1 through a change request to version 2: spec-driven development example.
Where Specroot fits
This is the problem Specroot works on: a spec that stays true after the change, agreed by the people who decide, with the work built from each version easy to find. Specroot for teams using AI coding agents.
Read next
- Spec Kit vs OpenSpec vs BMAD: what each leaves out — Spec Kit, OpenSpec and BMAD compared, with Superpowers, Kiro and GSD: how each works, what users say about it, and the gaps all of them share.
- Requirements in git: what version control does not track — Keeping specs and requirements in git gives you history, diffs and review. What it does not give you, and how to make requirements in GitHub or GitLab work.
- Acceptance criteria template: Given/When/Then examples — Free acceptance criteria templates (Given/When/Then and checklist), with examples for user stories and APIs, and how they differ from the definition of done.