Here's a fun experiment: give the same prompt to an AI twice. You'll get two completely different outputs. Sometimes wildly different. And if you're working on anything more complex than a button component, that randomness will absolutely wreck your project.
I learned this after watching my AI coding agent build a user settings page... three times. Each version had different field names, different layouts, different everything. My codebase looked like it was built by three different developers who never talked to each other. Because, technically, it was.
The fix? An AI coding spec template that tells your AI exactly what to build. Not in vague terms. In explicit, detailed, "there's only one way to interpret this" terms.
Key Takeaways:
- Traditional PRDs don't work for AI—you need specs written for machine consumption
- Every AI spec needs 6 critical sections (most tutorials only cover 2-3)
- A good spec reduces "oops, wrong thing" iterations by 70%+
In This Article
- Why Your AI Keeps Building the Wrong Thing
- The 6 Sections Every AI Spec Needs
- Frontend-Specific Spec Template
- Real Example: Spec for a Dashboard Feature
- Common Spec Mistakes That Derail AI
- Spec Checklist Before You Prompt
- FAQ
Try this prompt⌘+Enterto launch
Why Your AI Keeps Building the Wrong Thing
Let me be direct: the problem isn't your AI tool. It's your input.
Most people write prompts like this:
"Build a dashboard with user stats and some charts"
Then they're shocked—SHOCKED—when the AI generates something that looks nothing like what they imagined. The charts are the wrong type. The stats show the wrong data. The layout is all wrong.
But here's the thing: that prompt could describe 10,000 different dashboards. Your AI isn't a mind reader. It made reasonable guesses based on vague instructions.
GitHub's engineering team recently declared that for AI coding agents, "the specification becomes the source of truth." This isn't just philosophy—it's practical reality. The spec IS the product definition now.
The difference between a vague prompt and a proper spec is the difference between saying "make me food" and handing someone a recipe. One produces chaos. The other produces dinner.
This ties directly into what we cover in our AI coding workflow guide—specs are the foundation everything else builds on.
The 6 Sections Every AI Spec Needs
After breaking dozens of projects with incomplete specs, I've landed on six sections that make the difference between "nailed it" and "what even is this."
| Section | Purpose | Example |
|---|---|---|
| Context | What exists, what we're building on | "Existing React 18 app with Tailwind, Zustand for state" |
| Objective | The single goal (one sentence) | "Add a user activity log to the settings page" |
| Requirements | Explicit features, behaviors, constraints | "Show last 50 activities, include timestamp and action type" |
| UI Specification | Visual details, layout, responsive behavior | "Card-based layout, 3 columns desktop, 1 column mobile" |
| Data Contract | Shape of data, types, sources | "ActivityItem: {id: string, action: string, timestamp: Date}" |
| Success Criteria | How we know it's done | "User can view, filter, and paginate activity list" |
This is really just context engineering applied to project planning. You're giving the AI everything it needs to succeed on the first try.
Let's break each section down.
1. Context: What Already Exists
Your AI doesn't know about your codebase unless you tell it. This section sets the stage:
- Tech stack (React, Vue, vanilla JS, etc.)
- Styling approach (Tailwind, CSS modules, styled-components)
- State management (Zustand, Redux, Context)
- Existing components it should use or match
- Relevant file paths
Bad: "We have a React app." Good: "React 18 app using Tailwind CSS, shadcn/ui components, and Zustand for global state. User authentication already exists via /contexts/AuthContext."
2. Objective: One Sentence, One Goal
Here's where most specs fall apart. People write five paragraphs explaining the vision. Your AI doesn't need a vision. It needs a mission.
One sentence. What are we building?
Bad: "We want to improve the user experience by giving users more insight into their account activity, which will help with engagement and potentially reduce support tickets."
Good: "Build an activity log component that displays the user's recent actions on their settings page."
Save the "why" for your team meetings. Your AI needs the "what."
3. Requirements: The Non-Negotiables
This is where you get specific. Every feature, every constraint, every behavior.
Write requirements as a checklist. Use the word "must" liberally.
If something is optional, mark it explicitly as optional. Otherwise, assume everything is a "must."
4. UI Specification: What It Looks Like
This is frontend-specific and critical. Don't make your AI guess the layout.
Include:
- Layout structure (grid, flexbox, exact columns)
- Spacing (use your design system tokens or explicit values)
- Typography hierarchy (what's H2, what's body text)
- Colors (especially if they indicate state)
- Responsive behavior (breakpoints, what changes)
- Animation (if any)
5. Data Contract: Shape of the Data
AI tools love to invent data structures. Unless you tell them exactly what the data looks like, they'll hallucinate fields that don't exist.
Define your types:
This prevents the nightmare scenario where your AI generates beautiful UI that expects activity.createdAt but your API returns activity.timestamp.
6. Success Criteria: Definition of Done
How do you know the feature is complete? This isn't just for the AI—it's for you.
This becomes your testing checklist after the AI delivers.
Try this prompt⌘+Enterto launch
Frontend-Specific Spec Template
Here's the template I use for every frontend feature. Copy it, fill in the blanks, get better results:
Data Source: [API endpoint or data source] Shape: [Expected response structure]
Success Criteria
- [Criteria 1]
- [Criteria 2]
- [Criteria 3]
Out of Scope
- [Explicitly list what this feature does NOT include]
Data Source: GET /api/dashboard/stats Refresh: Every 30 seconds via React Query
Success Criteria
- 4 stat cards render with correct data
- Trend indicators show correct direction and color
- Loading state shows skeletons
- Error state shows message + retry button
- Responsive layout works at all breakpoints
- Data refreshes every 30 seconds without UI flicker
Out of Scope
- Detailed stat breakdowns (separate feature)
- Date range selector
- Exportable data
PRE-FLIGHT CHECKLIST:
□ Context section names specific tech stack and relevant files □ Objective is ONE sentence □ Requirements use "must" language (no "might" or "could") □ UI spec includes exact spacing and breakpoints □ Data contract includes TypeScript types □ All states covered (loading, empty, error, success) □ Success criteria are testable (not "works well") □ Out of scope explicitly lists what NOT to build □ No ambiguous adjectives (clean, nice, good, modern) □ If referencing existing components, include file paths
