03.06Practice

Spec-driven development with AI coding agents

How AR Labs runs spec-driven development with AI coding agents: a campaign plan (PRP) and a per-task spec grounded in today's code.

On this page

The problem it prevents
Two levels of specification
How a per-task spec is made
A spec's machine-readable header
Specs ride the pull request
Where it came from

AR Labs practises spec-driven development with AI coding agents (AI agents that write code, such as Claude Code or Codex): no agent writes code without a written specification. A campaign, work planned in one PRP and split into a tree of tasks, starts from that PRP, a product requirement prompt (a plan agents build from, in Rasmus Widing's format, adapted). Every task then gets its own spec, written by an agent that has just read the codebase as it stands, and the spec travels in the same pull request as the code it describes, so the reviewer sees both together. The practice suits anyone whose agents invent helpers that already exist or build from plans the code has outgrown. The coding pipeline shows where specs sit among the other steps.

The problem it prevents

An agent given a goal and nothing else fills the gaps with plausible guesses: it invents a helper that already exists, picks a pattern the codebase does not use, or quietly widens the scope. A plan written weeks earlier has the opposite problem: by the time the work starts, the code it describes may have moved. Specs that are written per task and checked for staleness address both.

Two levels of specification

Document	Answers	Written	Lifetime
PRP (product requirement prompt)	What the whole campaign must achieve and at what design level it will be built	Once per campaign, after the design interview (an agent questioning a person until the design is settled)	Split into tasks, then kept as background research
Per-task spec	How to build this one slice in the code as it is today	Immediately before the task is implemented	Archived when the task closes

A PRP keeps the goal and justification sections of a classic product requirements document and adds what an agent needs: the files and references to read, the architectural patterns to use, the vertical slices in order, and the validation that proves the work. It stays at design level. If a PRP section contains method signatures or file-by-file edit instructions, it has crossed into the per-task spec's territory and gets pulled back to intent.

A per-task spec grounds one task in the codebase. It is written as a design document a person can learn from, in terms of components, data flows and responsibilities, not line numbers and pasted code blocks. The implementer works from understanding the design rather than copying prescribed edits.

How a per-task spec is made

FIG. 01

flowchart LR
  A["Read the task and its parent"] --> B["Sweep the codebase"]
  B --> C["Research risks and edge cases"]
  C --> D["Write the spec"]
  D --> E{"One task or several?"}
  E -->|"leaf"| F["Implement"]
  E -->|"compound"| G["Fan out into child tasks"]

Gather intent. Read the task's goal and acceptance criteria, its parent, any sibling tasks and the campaign plan's relevant research.
Ground it in the code. Scan for the modules the task touches, their integration points and the project's test setup. Record the full commit hash the research was done against, and the list of files the spec expects to change.
Turn risks into proof obligations. For each risk the task exists to retire, pick the strongest proof that applies, preferring an automated test (see evidence of completion).
Write the spec, including the Gherkin scenarios the tests will be built from and a table that says, for each criterion, what to observe, how to verify it and which committed artefact proves it.
Classify it. If the task holds three or more distinct units of work with substantial integration between them, it is a container, and it is split into child tasks, each of which gets its own spec. Otherwise it goes to implementation.

A spec's machine-readable header

Every spec opens with a small block that scripts read:

---
bead: app-42.3
base_sha: 4be1c0d9a7e2f35b8c61d0a9e47f2b3c5d8e9f10
file_scope:
  - server/sessions.ts
  - server/sessions.test.ts
classification: leaf
---

base_sha is the commit every claim in the spec was true against. file_scope lists the files it expects to change, relative to the repository root. Before a task may enter implementation, a guard (a script that runs before the tracker accepts the change) compares the two: if any file in scope has changed since base_sha, the move is refused and the spec must be refreshed. A spec without the header still works, but it is not checked.

classification records whether the task is a leaf or a container, which lets an unattended run take the right branch without waiting for a person.

Specs ride the pull request

The spec is part of the deliverable. It is written on the task's branch, reviewed next to the code and merged with it. It is never merged to main ahead of the code, because a spec on main with no code behind it describes something that does not exist yet. For a container, the shared parent spec rides the pull request of the child that builds the shared foundation.

Once a task closes, its spec has done its job. It is archived rather than maintained, and anything durable it taught the project is copied into the project's design record first.

Where it came from

We evaluated GitHub's Spec Kit and Thoughtworks' writing on spec-driven development and kept our own PRP format, because it already covered the path from specification to implementation and a second system would have duplicated it. The vertical-slice structure and acceptance criteria written as Gherkin scenarios follow Matt Pocock's workflow and behaviour-driven development (Dan North).