Home › Agent workflows › Spec-driven development AGENTS.md

Spec-driven development AGENTS.md

AGENTS.md workflow for spec-driven development: write a spec, then a plan, then tasks, and implement against them.

AGENTS.mdAgent workflows

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Spec-driven workflow

For any feature bigger than a small fix, work through three documents in `specs/<feature>/` before writing code.

## 1. `spec.md` (what and why)
- Problem, users, and goals; explicit non-goals.
- User-visible behavior as numbered requirements (`R1: A signed-in user can export orders as CSV`), with acceptance criteria written as Given/When/Then.
- Edge cases and error states. Open questions at the top, marked `[?]`.
- No implementation details here. Ask the user to confirm the spec before continuing.

## 2. `plan.md` (how)
- Architecture and data model changes, APIs/contracts, libraries, and why. Reference existing code to reuse.
- Security, performance, and migration considerations.
- How each requirement (R1, R2...) will be verified.

## 3. `tasks.md` (steps)
- A checklist of small tasks, each tied to requirements, in dependency order, each with its test.
- Mark tasks done (`[x]`) as you complete them so work can resume in a new session.

## Implementing
- Do tasks in order. Write or update the test for a task first, then the code.
- If you discover the spec or plan is wrong, stop and update the document (and tell the user) instead of silently diverging.
- Keep commits per task, referencing the task.

## Done
All tasks checked, every requirement has a passing test, and the docs reflect what was built.