How to write a spec an AI coding agent can actually build

Short answer: an AI coding agent needs a spec that is executable as written. That means a clear problem statement backed by evidence, explicit users and flows, numbered requirements with priorities and testable acceptance criteria, explicit non-goals, listed assumptions, and a definition of done. A PRD written for human alignment usually fails as agent input because it is ambiguous in exactly the places where an agent guesses instead of asking.

Coding agents like Claude Code, Cursor, and Codex have made writing code cheap. They haven't made deciding what to build cheap. When the input is a vague ticket or a narrative PRD, the agent will still produce a lot of confident code. The question is whether it's the right code.

Why a normal PRD fails as agent input

A good PRD is a persuasion and alignment document. It tells the story of the problem, explains the rationale, and leaves room for the team to work out details together. Those are strengths for humans and weaknesses for agents:

The agent isn't being careless. It's doing exactly what an underspecified document asks it to do.

Spec-driven development, and the half that's missing

The engineering world has converged on a name for writing the spec first: spec-driven development. GitHub Spec Kit structures the work as phases, Specify, Plan, Tasks, Implement, and Converge, with each phase producing a Markdown artifact that feeds the next. AWS's Kiro IDE takes a similar spec-first approach.

In her review of these tools on Martin Fowler's site, Birgitta Böckeler points out two open problems: it's unclear whether spec-driven development is meant for developers or product people, and it's hard to know when a spec should stay functional versus include technical detail.

Our answer is to split the spec in two:

• The product spec is owned by the PM. It covers the problem, users, evidence, requirements, acceptance criteria, non-goals, and assumptions. It answers what and why.
• The technical plan is owned by the engineer and the agent. It covers architecture, files to change, data migrations, and sequencing. It answers how.

Most spec-driven tooling is excellent at the second half. This post is about the first half, the part only someone who talked to customers can write.

Anatomy of a build-ready product spec

Here are the sections that matter, in the order an agent needs them.

1. Problem statement, with evidence

One paragraph: who has the problem, what it costs them, and how you know. "How you know" is the part most specs skip. Link the customer quotes or data behind the problem. It keeps the agent, and the reviewer, anchored to reality when trade-offs come up.

2. Target users and primary flow

Name the user and walk through the main flow step by step. Agents build flows much more reliably than they build features described in the abstract.

3. Goals and non-goals

Goals say what success looks like. Non-goals are the most underrated section in any spec written for an agent. "We are not changing the permissions model" saves hours of reviewing code you never wanted.

4. Numbered requirements with acceptance criteria

Every requirement gets a stable ID, a priority, and acceptance criteria a test could check:

### REQ-003 (P0): Export filtered report as CSV
As a finance admin, I can export the currently filtered report
as a CSV file.

Acceptance criteria:
- Given a report with active filters, when I click Export → CSV,
  then the file contains only rows matching those filters.
- Column headers match the on-screen column names.
- Exports over 50,000 rows are queued and delivered by email
  instead of downloading in the browser.

Evidence: EV-002, EV-005

If you can't write the acceptance criteria, the requirement isn't ready, and no amount of agent capability will fix that.

5. Assumptions, with impact if wrong

List what you're assuming but haven't verified, and what breaks if you're wrong. "ASM-002: finance admins already have export permission. If wrong, REQ-003 needs a permission change and a security review." High-impact assumptions should be resolved before build, not discovered in code review.

6. Open questions and definition of done

Unresolved questions must be either answered or explicitly deferred. A spec with open questions in its P0 requirements isn't build-ready. The definition of done should say what tests must pass and what a reviewer checks.

Is your spec build-ready? Hard blockers

Before handing a spec to an agent, check for these. Any one of them is a blocker:

• No clear problem statement or target user
• No non-goals
• A P0 or P1 requirement without acceptance criteria
• No described user flow
• An unresolved assumption with high impact if wrong
• Requirements that haven't been broken into implementable tickets

Handing the spec to Claude Code, Cursor, or Codex

Once the product spec is solid, the handoff is mechanical:

1. Put the spec in the repository

   Commit it as Markdown, for example specs/report-export.md. Agents read files in the repo reliably, and the spec gets versioned alongside the code it describes.

2. Slice requirements into tickets

   One ticket per requirement is a good default. Each ticket references its REQ ID and copies the acceptance criteria, so it can stand alone.

3. Give the agent a structured prompt

   State the goal, the constraints, the order of work, the tests to write, the definition of done, and the anti-goals. Ask it to produce a technical plan for review before writing code.

4. Review against acceptance criteria, not vibes

   Review each change against the REQ it claims to satisfy. Tests should map to acceptance criteria one to one where possible.

A handoff prompt might look like this:

Read specs/report-export.md.

Goal: implement REQ-001 through REQ-004.
Constraints: no schema changes outside the reports module;
reuse the existing CSV utility.
Order: REQ-001 → REQ-003 → REQ-002 → REQ-004.
Tests: one test per acceptance criterion, named after the REQ ID.
Done when: all acceptance-criteria tests pass and lint is clean.
Do NOT: change permissions, add new export formats, or touch
billing.

First, propose a technical plan and wait for approval.

How Praxiom does this

Praxiom's Spec Packet is a build-ready product spec generated from your research. It carries the problem, target users, flows, goals, and non-goals, plus numbered requirements (REQ-###) with priorities and acceptance criteria, assumptions (ASM-###) with their impact if wrong, and evidence (EV-###) linked back to the customer quotes behind them.

Each packet gets a readiness score with explicit hard blockers, like the list above, so you know whether it's build-ready or still a draft. When it is, Praxiom generates one ticket per requirement and a coding-agent prompt with the goal, constraints, sequence, tests, definition of done, and anti-goals, ready to paste into Claude Code or Codex.

Spec template

Copy this as a starting point:

# Spec: <feature name>

## Problem
<who, what it costs them, how we know> (Evidence: EV-001, EV-002)

## Users and primary flow
1. ...

## Goals
- ...

## Non-goals
- ...

## Requirements
### REQ-001 (P0): <title>
<user story>
Acceptance criteria:
- Given ..., when ..., then ...

## Assumptions
- ASM-001: <assumption>. If wrong: <impact>.

## Open questions
- ...

## Definition of done
- ...