Writing Better Specs
A good spec is the single most powerful tool you have when working with AI.
Think of it this way:
If you give an AI a blurry photo, you get a blurry result. If you give it a blueprint, you get a building.
The time you invest in writing a clear spec pays for itself many times over in fewer iterations, fewer bugs, and fewer "that's not what I meant" moments.
What Makes a Spec "Good"?
A good spec is not a technical document. It doesn't need diagrams, UML, or engineering jargon. It just needs to be clear, complete, and unambiguous.
| Quality | What It Means |
|---|---|
| Clear | Anyone reading it — including an AI — understands what to build |
| Complete | It covers normal cases, edge cases, and error cases |
| Unambiguous | There's only one way to interpret each requirement |
| Testable | You can check if each requirement was met |
| Prioritized | It separates "must have" from "nice to have" |
The Anatomy of a Great Spec
Every good spec should answer five questions:
1. What are we building?
A one-paragraph summary of the feature or app. This gives the AI context before it dives into details.
Example:
We're building a booking page for a small yoga studio. Customers can see available class times, book a spot, and receive a confirmation email. The studio owner can manage classes and see who's booked.
2. Who is it for?
Describe the users and what they need to do.
Example:
- Customers — browse classes, book spots, cancel bookings
- Studio owner — create classes, set capacity, view bookings, cancel classes
3. What should happen in the happy path?
Describe the normal flow step by step.
Example:
- Customer visits the booking page
- They see a calendar showing available classes for the next 7 days
- They click a class to see details (time, duration, available spots)
- They enter their name and email
- They click "Book Now"
- They see a confirmation message
- They receive a confirmation email
4. What should happen in the unhappy path?
This is where most specs fall short — and where most bugs come from.
Example:
- If a class is full → show "This class is fully booked" and suggest other times
- If the customer enters an invalid email → show "Please enter a valid email address"
- If the booking system fails → show "Something went wrong. Please try again." and log the error
- If the customer tries to book the same class twice → show "You're already booked for this class"
- If the studio owner cancels a class → all booked customers get a cancellation email
5. What are the rules and constraints?
Any business rules, security requirements, or design constraints.
Example:
- Customers can book up to 2 spots per class
- Cancellations must be made at least 2 hours before class
- The studio owner cannot delete a class that has bookings — they must cancel it instead
- No payment is required (classes are free or paid separately)
- The page must work on mobile phones
Spec Writing Patterns
Here are three patterns you can use depending on what you're building.
Pattern 1: The Feature Spec
Best for: adding a single feature to an existing app.
💡 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.
## Feature: [Name]
### Summary
[One paragraph describing the feature]
### Users
- [User type 1] — [what they can do]
- [User type 2] — [what they can do]
### Happy Path
1. [Step 1]
2. [Step 2]
3. [Step 3]
### Error Handling
- If [problem] → [what happens]
- If [problem] → [what happens]
### Rules
- [Rule 1]
- [Rule 2]
Pattern 2: The App Spec
Best for: building a new app from scratch.
## App: [Name]
### Purpose
[One paragraph describing what the app does]
### Pages / Screens
- **Page 1** — [what it shows and what users do there]
- **Page 2** — [what it shows and what users do there]
- **Page 3** — [what it shows and what users do there]
### Data
- [Thing 1] has: [fields]
- [Thing 2] has: [fields]
- [Relationship between things]
### User Flows
[Describe the main flows through the app]
### Must Have (MVP)
- [ ]
- [ ]
- [ ]
### Nice to Have
- [ ]
- [ ]
Pattern 3: The Bug Fix Spec
Best for: describing a problem you need fixed.
## Bug: [Short description]
### Current Behavior
[What's happening now]
### Expected Behavior
[What should happen instead]
### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]
### Environment
- Browser/Device: [e.g., Chrome on Mac, Safari on iPhone]
- App version: [if applicable]
### Notes
[Any additional context, screenshots, or error messages]
Common Spec Writing Mistakes
| Mistake | Why It Hurts | How to Fix |
|---|---|---|
| Being too vague | AI guesses wrong, you waste time iterating | Be specific about every behavior |
| Only describing success | The app breaks silently on errors | Always describe what happens when things go wrong |
| Mixing priorities | AI builds nice-to-haves before essentials | Separate "must have" from "nice to have" |
| Skipping context | AI builds something that doesn't fit your app | Always include a one-paragraph summary of your app |
| Assuming the AI knows | AI doesn't know your business rules | Spell out every rule explicitly |
| Writing one giant spec | AI gets overwhelmed and produces messy code | Break into small, independent tasks |
How to Use a Spec With AI
Once you have a good spec, here's how to hand it to an AI tool effectively.
Step 1: Give the big picture first
Start with the summary so the AI understands the context.
I'm building a yoga studio booking app. Here's the spec for the booking feature...
Step 2: Paste the relevant section
Don't paste the entire app spec at once. Paste the section relevant to what you're building right now.
Here's the spec for the booking page:
[booking page spec section]
Step 3: Add technical context
If you know what tech stack you're using, mention it.
This is a Next.js app with a PostgreSQL database. The app is deployed on Vercel.
Step 4: Ask for one thing at a time
Build the booking page according to this spec. Start with the UI, then add the backend logic.
Step 5: Review against the spec
After the AI generates code, go through your spec line by line and check:
- Does it handle the happy path?
- Does it handle the error cases?
- Does it follow the rules?
- Does it work on mobile (if required)?
Real Example: Before and After
Before (Vague Spec)
Make me a contact form.
The AI will build something generic. It might not save submissions. It might not validate emails. It might not tell the user what happens after they submit.
After (Good Spec)
## Feature: Contact Form
### Summary
A contact form on the website that lets visitors send messages to the business owner. Submissions are saved to the database and emailed to the owner.
### Happy Path
1. Visitor fills in name, email, subject, and message
2. They click "Send Message"
3. They see "Thanks for reaching out! We'll get back to you within 24 hours."
4. The submission is saved to the database
5. An email is sent to hello@mybusiness.com
### Error Handling
- If email is invalid → show "Please enter a valid email address"
- If required fields are empty → highlight the missing fields in red
- If the database save fails → show "Something went wrong. Please try again."
- If the email fails to send → still save to database and show success (email can be retried later)
### Rules
- Name is required (max 100 characters)
- Email is required and must be valid
- Subject is required (max 200 characters)
- Message is required (max 5000 characters)
- No HTML or scripts allowed in any field
- Rate limit: max 3 submissions per hour per IP address
See the difference? The good spec leaves nothing to chance. The AI knows exactly what to build, and you know exactly what to check.
The Bottom Line
A great spec is the shortest path to a great app. It's not extra work — it's the work that saves you from doing extra work.
You don't need to be a developer to write a good spec. You just need to be clear about what you want, what could go wrong, and what rules apply.
Ready to Write Your First Spec?
Download the AI Project Template — a complete set of fill-in-the-blanks documents that guide you through writing clear, actionable specs for any project.
Download the Starter Template →