The spec comes first.And you read it before the code.

The loop: spec, review, plan, review, tasks, build

Instead of one big prompt and a pile of code, the work goes through documents, each one checked by you before the next is written.

1. Spec: what and why

   What the feature must do, for whom, and what it must not do. No file names, no technology choices yet.

2. Plan: how

   The approach: which parts change, in what order, with what risks. The plan answers to the spec.

3. Tasks: small steps

   A checklist the agent can work through and tick off, each task small enough to check.

4. Build

   Only now the agent writes code, against documents you have already read.

A short spec template

A spec does not need to be long. Six headings are enough to catch most misunderstandings:

# Feature name

## Goal
## Non-goals
## Users
## Requirements
## Edge cases
## Open questions

Non-goals and Open questions are the ones people skip and agents need most. An agent that is told what not to build, and what is still undecided, asks instead of guessing.

Doing it in Claude Code, Codex and Cursor

All three can write the documents, and each has a plan mode for the planning step: Claude Code plan mode, Codex plan mode and Cursor plan mode.

To make the review step automatic, put one rule in CLAUDE.md or AGENTS.md: after writing a spec or plan, send it to you with request_review in DotMD and wait. The agent then stops after every document and waits for your comments or your approval, using no tokens while it waits. DotMD can add the rule for you: see CLAUDE.md and AGENTS.md.

Review that scales

Chat is a poor place to review a document. You read the spec rendered in DotMD instead, select the passage that is wrong and press ⌥⌘M. The comment is tied to its lines, so the agent knows exactly what you mean. You can write all the comments first and send them once.

When the agent has fixed them, every change is shown in the file: old text red, new text green, next to the comment it answers. Accept or Reopen each one. DotMD also lists the changes nobody asked for. See Reviewing changes.

For a second opinion, let another agent review first. A spec written by Claude Code and commented by Codex reaches you with the obvious gaps already marked, and you decide which remarks the writer gets: Agent reviews agent.

Tools for spec-driven development

• Plain Markdown in the repo. A docs/specs folder and the template above is a complete setup.
• Plan modes. Each agent's own way of planning before it builds.
• GitHub Spec Kit. An open-source toolkit that gives your agent commands for each step and writes spec.md, plan.md and tasks.md for you: GitHub Spec Kit.

Whatever you pick, the documents are Markdown files, and DotMD reads any of them.

Questions about spec-driven development

More questions