Spec-Driven Development: Plan First, Then Let AI Build

Spec-driven development is a workflow where you (and your AI agent) write down what you're building, and how, before any code is written. You agree on a short specification, turn it into a technical plan and a task list, then let the agent implement one task at a time against that plan. It's the most effective way to move from chaotic "prompt and pray" vibe coding to building software that holds together.

Why "just prompt it" stops working

Pure vibe coding is great for small things. But as projects grow, prompt-by-prompt building causes predictable problems:

• Inconsistent architecture: each prompt solves its own problem its own way.
• Forgotten requirements: the agent doesn't remember what you said 40 prompts ago.
• Rewrites: you discover a missing requirement (user roles, time zones, multiple currencies) after building on the wrong assumption.
• Unreviewable diffs: you can't evaluate a change if you never agreed on what the change should be.

A spec gives both you and the agent a shared source of truth that survives across sessions, models and tools.

The spec-driven workflow

1. Specify: what and why. Users, features, rules, out-of-scope.
2. Clarify: the agent asks questions about gaps and edge cases.
3. Plan: how. Tech choices, data model, files affected, risks.
4. Tasks: break the plan into small, testable steps.
5. Implement: one task at a time, with tests, committing after each.
6. Verify: check the result against the spec's acceptance criteria.

You don't need special tools. A Markdown file and an agent with a planning step are enough.

A spec template you can copy

# Feature: Team invitations

## Problem
Workspace owners can't add teammates, so every account is single-user.

## Users & stories
- As an owner, I can invite someone by email so we can work together.
- As an invitee, I can accept an invite and land in the workspace.

## Requirements
1. Owners can invite by email; invites expire after 7 days
2. Invitee accepts via emailed link; must sign up or log in first
3. Owners can revoke pending invites
4. Max 20 members per workspace on the free plan

## Out of scope
Roles beyond owner/member, SSO, bulk invites.

## Acceptance criteria
- An expired or revoked link shows a clear error
- A user can't accept an invite meant for a different email
- Members can't invite others

## Open questions
- What happens if the invitee already belongs to another workspace?

Then:

Read specs/team-invitations.md. Ask me clarifying questions about gaps, edge cases
and security. After I answer, write specs/team-invitations.plan.md with: data model
changes, files to create/modify, the security checks, test plan, and an ordered task
list where each task is small enough to review in one sitting.

Plan mode in your AI tool

Most agents now have a built-in planning step that researches your code without editing anything:

• Claude Code: press Shift+Tab to switch to plan mode. Claude explores, then presents a plan to approve or revise.
• Cursor: use Plan mode in the agent panel to generate an editable plan before building.
• Google Antigravity: agents produce an implementation plan artifact you can comment on before work starts.
• GitHub Copilot: a well-written issue acts as the spec for the coding agent, and agent mode can plan before editing.
• AI app builders: many have a chat or plan mode where you can discuss before generating.

Even without a dedicated mode, ending a prompt with "show me a plan before writing code" works.

Dedicated spec-driven tools

• GitHub Spec Kit↗ (opens in a new tab): an open-source toolkit that adds commands to your agent for writing a project "constitution" (principles), specs, plans and tasks, and works with Claude Code, Copilot, Cursor, Gemini/Antigravity and others.
• Kiro↗ (opens in a new tab): an AI IDE from AWS built around specs, generating requirements, design and task documents and keeping them in sync with the code.

They're helpful for larger projects and teams, but start with plain Markdown files; the habit matters more than the tooling.

How detailed should a spec be?

Match the detail to the risk:

Tips for spec-driven vibe coding

1. Keep specs in the repo (e.g. a specs/ folder) so every session and every tool can read them.
2. Write acceptance criteria as testable statements. They become your test cases.
3. Make the agent ask questions. "What's missing from this spec?" surfaces edge cases you didn't think of.
4. Review the plan harder than the code. Fixing a plan takes seconds; fixing code built on a bad plan takes hours.
5. Implement one task per session and commit after each, using Git as your safety net.
6. Update the spec when reality changes. A stale spec misleads future sessions.
7. Put project-wide rules in AGENTS.md, not in every spec.
8. Include security requirements in the spec itself. See the security checklist.

For a full worked example from spec to deployed product, follow build and deploy a full-stack app with AI.

Frequently asked questions

Isn't this just waterfall development?

No. Specs here are short (often one page), written in minutes with the agent's help, and cover one feature at a time. It's lightweight planning, not months of documentation.

Does spec-driven development slow you down?

It adds a few minutes at the start and saves hours of rework. The bigger the feature, the bigger the payoff.

Can the AI write the spec for me?

It can draft one from a rough description, and it's good at finding gaps. But you should decide the requirements; you know your users and business.

Do I need GitHub Spec Kit or Kiro?

No. They add structure that helps teams and big projects, but a Markdown spec and your agent's plan mode get you most of the benefit.