Spec-driven development with AI coding agents.

What is spec-driven development?

Spec-driven development means you agree on what to build before an AI agent writes the code. The spec holds the goal, the constraints, the technical design, and a set of small tickets with acceptance checks. The agent builds against that spec instead of guessing from a chat, and people review the spec, not only the diff.

It is not a return to long design documents. A spec covers one feature, an agent drafts most of it in minutes, and it keeps changing while you build. The difference is that the changes are written down and reviewed, so the next session, and the next teammate, start from the same place.

Why AI coding agents need a spec

Without one, the same three problems show up on every team that codes with agents:

• Every session starts from zero. What the agent learned about the feature disappears with the chat, so you re-explain the constraints and last week's decisions again.
• Every agent has its own plan. Your agent knows one thing, your teammate's knows another, and the code ends up with a bit of both.
• Review comes too late. The wrong approach shows up in a huge pull request, when fixing it means throwing work away.

Bigger context windows and memory tools help an agent recall more. They don't decide what is true. A spec does, because people agreed on it. (More on that in Tuskway vs AI memory tools.)

The parts of a good spec

Context

The goal, who it's for, the constraints, the decisions already made and the questions still open.

Tech design

How it will work, split into sections: API, data, UI, rollout. Small sections let an agent read only the part its ticket needs.

Tickets

Small units of work, each tied to a design section, with a goal, acceptance checks, dependencies and the areas of the code it touches.

Review

Comments on specific lines, answered and resolved, with a history of who changed what.

The workflow, step by step

In Tuskway, each step is one command your agent runs from the tool you already use:

1. 1

   /start-epicCapture the context.

   Describe the feature. The agent writes the goal, constraints and open questions into the epic's notes.

2. 2

   /write-designAgree on the design.

   The agent drafts the tech design in sections. Teammates comment on lines; an agent works through the threads and resolves them.

3. 3

   /draft-ticketsSplit it into tickets.

   Each brief gets a goal, acceptance checks, dependencies and the files to touch, then publishes to GitHub Issues, GitLab, Linear or Jira.

4. 4

   /tackle-ticketBuild.

   Any agent picks a ready ticket, reads its brief and design section, builds it, and moves it to review when the pull request opens.

A ticket brief an agent can finish

The brief is where spec-driven development pays off. A good one is short, self-contained and testable:

# T3 · Retry failed card payments

Goal
  Recover payments that fail for temporary reasons,
  without charging twice.

Acceptance
  - Retries after 1 min, 10 min and 1 h
  - Never charges the same order twice
  - Retry keys expire after 24 h

Design section   tech-design/payments.md
Depends on       T1 · Checkout API
Areas            lib/payments/retry.ts
                 app/api/webhooks/stripe.ts

The design section link keeps the agent's context small. The dependencies and areas tell you what can run in parallel and what would collide.

Spec-driven development for a team

Toolkits like GitHub Spec Kit and Kiro keep specs as markdown files in the repository. That works well for one developer on one branch. On a team, the spec has to be in one place every agent reads, whatever branch or tool it runs in; it needs line comments and an approval step; and the tickets have to reach your tracker. That is what Tuskway adds. See Tuskway vs specs in the repo and Tuskway vs AGENTS.md.

Questions