Spec-Driven AI Development: Make Your Agents Accountable

Spec-driven development means every task starts with a written specification, a precise, bounded description of what will change, why, and how success is measured, before implementation begins. The spec is the contract between whoever defines the work and whoever executes it. In spec-driven AI development, the executor is a coding agent, and the spec doubles as its prompt.

Without a spec, the agent must infer everything from one message: scope, constraints, affected files, definition of done. That inference is where agentic coding goes wrong, the full argument lives in our guide to engineering with AI agents.

Hand a bare prompt to a coding agent, in any agentic IDE, and three failure modes appear reliably:

A spec fixes all three: it names the files in scope, states the acceptance test, and lists what must not change. It also enables parallelism, agents running simultaneously need bounded, non-overlapping scopes, and leaves an audit trail. Six months later, the spec attached to a merged PR tells you exactly what was decided and why. A chat log rarely can.

AIDEN runs spec-driven development as a board workflow: cards move through Stories → Spec Review → In Progress → Review → Done. Four steps take a plain-English idea to a reviewable pull request:

1. 1

   Write a story card

   One or two sentences on the board. For example: “Add email/password authentication. Users can sign up, log in, and log out. Use JWT tokens in httpOnly cookies.”
2. 2

   AI drafts the spec

   AIDEN reads your story and its analysis of the codebase, then drafts a full spec: exact files to create or modify (src/lib/auth.ts, src/app/api/auth/login/route.ts), acceptance criteria (valid login returns 200 with a set-cookie header; invalid credentials return 401), an exclusion list (the User schema, the /api/payments routes), and example request/response shapes.
3. 3

   You approve: the enforced gate

   The card sits in Spec Review until you act. Edit anything that is too broad or missing a constraint, then approve. Since v1.5.21 this gate is enforced: no agent starts coding without an approved spec.
4. 4

   The spec becomes the agent's prompt

   AIDEN opens a git worktree on a new branch and launches your Claude Code or Codex CLI with the approved spec as its working prompt. The agent can run your tests and iterate, a best-effort convention explained in the AI agent harness, and when it is done, the PR is one click away, spec attached as the description.

AIDEN is not alone in this bet: AWS's Kiro is also built around specs as the unit of work, see how the two compare in AIDEN vs Kiro.

Whether AIDEN drafts the spec or you write it yourself, five rules determine whether the agent produces useful output or a mess:

1. 1

   Be specific about scope

   “Add authentication” is not a spec. “Add email/password sign-up and login to the existing Express server in src/server.ts, using bcrypt for hashing and JWT for session tokens” is. Vague scope produces vague code.
2. 2

   Name the files and functions involved

   List the files the agent should create, modify, or read. If a specific function needs to change, name it. This kills the hallucinated-scope failure mode, the agent cannot touch what is not on the list.
3. 3

   Define the acceptance test

   Write a concrete, verifiable success condition: “/api/auth/login returns 200 and a set-cookie header with an httpOnly JWT for valid credentials, and 401 with an error message for invalid ones.” A testable assertion gives the agent something to verify its work against before you ever see the diff.
4. 4

   Say what NOT to change

   Explicitly list what must stay untouched: “Do not modify src/lib/stripe.ts, the User database schema, or any API route outside /api/auth/.” Often the most valuable part of the spec, it is what prevents collateral damage.
5. 5

   Include example inputs and outputs

   For anything that handles data, show a concrete example: a sample request body, a response payload, an example SQL row. Agents are far more accurate matching a concrete example than interpreting an abstract description.

Across the dimensions that matter for production software: