# Why should you plan before you let AI write code?

Date: 2026-10-28 · Author: Robert Scales · https://guidetoartificialintelligence.com/en/learn/spec-driven-development-ai/

**Answer:** Because a coding agent builds exactly what it thinks you asked for, and a short written plan (requirements, design, task list) is the cheapest place to catch a misunderstanding. Spec-driven development makes that plan a file the agent reads and works through, while an instructions file such as AGENTS.md or CLAUDE.md holds the rules that apply to every task.

If you type "build me a booking page" into a coding agent, it will build *a* booking page within minutes. Whether it is *your* booking page depends on dozens of choices it made for you: who can book, how cancellations work, what happens when two people pick the same slot. When those guesses are wrong, you find out late, after the code is written, and fixing it costs far more prompts than a plan would have.

**Spec-driven development** is the habit of writing down what you want before any code exists, then having the agent build from that document. The idea is old in software teams. What changed in 2025 and 2026 is that tools made it part of the workflow: Amazon's Kiro editor is built around specs, and most agents now offer a plan mode that proposes steps before touching files.

## What does a spec look like?

Kiro's documentation describes a three-phase workflow that works with any tool, even if you write the files yourself:

1. **Requirements** (`requirements.md`): user stories and acceptance criteria, meaning testable statements of what "done" looks like.
2. **Design** (`design.md`): the technical approach, the data involved, and how the parts talk to each other.
3. **Tasks** (`tasks.md`): small, numbered implementation steps the agent can complete and check off one at a time.

Kiro generates these files with you, lets you comment on exact passages before moving on, and can then run independent tasks in parallel. For a well-understood feature it also offers a quick spec that writes all three files without stopping for approval. You can copy the same structure into Claude Code, Codex or Cursor by asking the agent to write the three files and wait for your review.

## A worked example: one feature, three short files

Say you want a waiting list for a yoga class app. Start by asking for the plan only:

```prompt
Before writing any code, write a spec for this feature in three files under specs/waitlist/:
- requirements.md: user stories with acceptance criteria written as "WHEN ... THEN ..." lines.
- design.md: which data you will store, which screens and API routes change, and any risks.
- tasks.md: numbered tasks small enough to finish and test one at a time.
Feature: when a class is full, students can join a waiting list. If someone cancels, the first person on the list gets the spot and an email.
Ask me questions about anything unclear instead of guessing. Do not write code until I approve the spec.
```

A good `requirements.md` for this might contain:

| User story | Acceptance criteria |
|---|---|
| As a student, I can join the waiting list of a full class | WHEN the class is full THEN a "Join waiting list" button appears; WHEN I join THEN I see my position |
| As a student, I get a freed spot automatically | WHEN a booked student cancels THEN the first person on the list is booked AND receives an email |
| As a student, I can leave the list | WHEN I leave THEN everyone behind me moves up one place |

Reading that table takes two minutes, and it is where you notice the missing case ("What if the first person doesn't want the spot anymore?"). Changing one line now is far cheaper than changing the database later. Once you approve, tell the agent to work through `tasks.md` one task at a time, running the tests after each.

> **Try it:** Pick a small feature you want in an app or script. Use the prompt above, then read only `requirements.md` and add one acceptance criterion the agent missed before you let it write any code.

## Planning versus rules: two different files

A spec belongs to one feature and is finished when the feature ships. **Instruction files** are different: they hold the standing rules for every task in the project, such as how to run tests, which folders are off-limits, or which coding style to follow. Keep the two apart so neither grows into a wall of text.

## How do you write instruction files the AI follows (AGENTS.md, CLAUDE.md, rules files)?

Most agents load a Markdown file of project rules at the start of each session. **AGENTS.md** is an open format that the AGENTS.md project says more than 60,000 open-source repositories use. Tools listed as reading it include OpenAI's Codex, Google's Jules, GitHub Copilot's coding agent, Cursor, Zed, Aider, Devin and Kilo Code. Claude Code reads **CLAUDE.md** instead; Anthropic's documentation suggests a CLAUDE.md that contains the line `@AGENTS.md` so both files share one set of rules. Other editors have their own rules files, but most can also read AGENTS.md, so start there.

What makes an agent actually follow the file:

- **Be specific and checkable.** "Run `npm test` before every commit" works; "write good code" doesn't. Anthropic notes that concise, verifiable instructions are followed more consistently.
- **Keep it short.** Anthropic suggests staying under about 200 lines per CLAUDE.md. Remove rules that contradict each other, since the agent may follow either one.
- **Cover what a new teammate would need.** The AGENTS.md site suggests describing the project, the commands to build and test it, style conventions, how testing works and any security notes.
- **Put local rules close to the code.** In a large project, a nested AGENTS.md in a subfolder applies to that folder, and the closest file wins. A direct instruction in your chat overrides the file.
- **Remember it is guidance, not a lock.** Claude Code treats CLAUDE.md as context rather than enforced configuration. Anything that must never happen, such as reading secrets or pushing to `main`, belongs in permission settings as well.

A minimal example:

```markdown
# AGENTS.md
### Project
Yoga class booking app. Next.js front end in web/, API in api/.
### Commands
- Install: npm install
- Test: npm test (must pass before every commit)
### Rules
- For any new feature, write a spec in specs/<feature>/ and wait for approval.
- Never edit files in api/payments/ without asking.
- Ask before adding a dependency.
```

Treat the file as living documentation: when the agent makes the same mistake twice, add one clear line that prevents it.

## Sources

- Specs: https://kiro.dev/docs/specs/
- AGENTS.md: https://agents.md/
- How Claude remembers your project (Claude Code memory): https://code.claude.com/docs/en/memory