Spec-Driven Development

Here's a common story:

You ask an AI to "build me a dashboard." It gives you something. You say "no, I meant with charts." It adds charts. "Actually, I need a filter by date." It adds a filter. "And users should be able to export to CSV." It adds export. After 20 rounds of back-and-forth, you have something that kind of works — but it's messy, has features you don't need, and is missing things you assumed would be there.

This is the most expensive way to use AI.

Spec-driven development is the opposite approach: you write down exactly what you want before you ask the AI to build anything. Then you hand that plan to the AI and get much better results in much less time.

Why Planning Beats Guessing

When you give an AI a vague request, it has to guess what you mean. And AI guesses are expensive:

Problem	What Happens
Misunderstandings	The AI builds the wrong thing, you go back and forth fixing it
Missing features	You realize later something important was left out
Scope creep	The app keeps growing with no clear direction
Inconsistent design	Different parts of the app don't work well together
Wasted time	You pay for AI credits and hours of back-and-forth

When you write a spec first, the AI knows exactly what to build. You get what you asked for, the first time.

The Spec-Driven Workflow

Here's the simple process:

Your Idea
    ↓
Write Down What You Want (Requirements)
    ↓
Plan How It Should Work (Architecture)
    ↓
Break It Into Small Pieces (Tasks)
    ↓
Ask AI to Build Each Piece
    ↓
Check That It's Right
    ↓
Test It
    ↓
Launch

Let's walk through each step.

Step 1: Write Down What You Want (Requirements)

Before you open any AI tool, open a blank document and write down:

• What is this feature supposed to do? (in plain English)
• Who will use it?
• What should happen when it works correctly?
• What should happen when something goes wrong?

Example — instead of saying "make me a login system":

💡 New to Markdown? The examples on this page use Markdown — a simple way to format text with symbols like # for headings and - for bullet lists. If any of this looks unfamiliar, check out our Markdown Crash Course — it covers everything you need in 2 minutes.

## Login System Requirements

### What It Should Do
- New users can create an account with their email and a password
- Existing users can log in with their email and password
- Users who forget their password can reset it via email
- Users can log out

### Security Rules
- Passwords must be at least 8 characters
- After 5 failed login attempts, the user must wait 1 minute
- Users should be logged out automatically after 24 hours

### What Should Happen If...
- Wrong email or password → show an error message (don't say which one was wrong)
- Someone tries to create an account with an email that already exists → tell them
- The email service is down → still let existing users log in

This doesn't require any coding knowledge. You're just describing what you want.

Step 2: Plan How It Should Work (Architecture)

You don't need to design the technical details. But you should think about:

• Where does data live? (a database, a spreadsheet, a file?)
• What screens or pages are needed?
• How do they connect to each other?

Draw it out if it helps. A simple diagram on paper or in a tool like Excalidraw is enough.

Example for a task management app:

Pages:
  Login page → Dashboard (shows your tasks)
  Dashboard → Create Task form
  Dashboard → Task Details page
  Dashboard → Settings page

Data:
  Each task has: title, description, due date, status (pending/done)
  Each user has: name, email, password
  Users can only see their own tasks

Step 3: Break It Into Small Pieces (Tasks)

Instead of asking the AI to build everything at once, break it into small, independent pieces:

## Tasks

### Task 1: User Registration
- [ ] Create a sign-up page with email and password fields
- [ ] Save new users to the database
- [ ] Show a success message after registration

### Task 2: User Login
- [ ] Create a login page
- [ ] Check email and password against the database
- [ ] Redirect to dashboard on success
- [ ] Show error on wrong credentials

### Task 3: Dashboard
- [ ] Show list of tasks for the logged-in user
- [ ] Button to create a new task
- [ ] Each task shows title and status

Step 4: Ask AI to Build Each Piece

Now feed each task to your AI tool, one at a time, with your requirements:

Build Task 1: User Registration

Requirements:
- A sign-up page with email and password fields
- Save new users to the database
- Passwords must be at least 8 characters
- Show a success message after registration
- If the email is already taken, show an error

Tech context:
- This is a [your app type] app
- It uses [your database or platform]

Step 5: Check That It's Right

After the AI generates the code, test it:

• Does it do what you asked for?
• Try the edge cases: what happens if you leave a field empty? What if you enter an invalid email?
• Does it feel right? Is the error message helpful?

Step 6: Test It

Have someone else try to use it. Watch them. Do they get confused? Does something break?

Step 7: Launch

Once everything works and you've checked for security issues (see Security Basics), you're ready to launch.

Why This Works Better With AI

AI tools are incredibly responsive to clear instructions. When you give them a well-written spec:

• They get it right more often — less back-and-forth fixing mistakes
• They write better code — clear requirements lead to cleaner implementation
• You save money — fewer AI credits wasted on wrong approaches
• You build faster — each piece is done right the first time

A Simple Template to Get Started

Copy this for your next feature:

# [Feature Name] Requirements

## What It Should Do
- [ ]
- [ ]
- [ ]

## Rules / Constraints
- [ ]
- [ ]

## What Should Happen When Something Goes Wrong
- If [problem] → [what should happen]
- If [problem] → [what should happen]

## Pages / Screens Needed
- [ ]
- [ ]

The Bottom Line

Better plans produce better AI-generated apps. The 30 minutes you spend writing a spec will save you hours of fixing misunderstandings later.

You don't need to be a developer to write a good spec. You just need to be clear about what you want.

---

Ready to Put This Into Practice?

Download the AI Project Template — it walks you through writing requirements, features, security rules, and more, one simple step at a time.

Download the Starter Template →