The product spec template that AI coding agents actually follow

Most product spec templates were designed for humans to read in a meeting. They have executive summaries, stakeholder lists, timelines, and enough context that a PM can present them to a room.

AI coding agents don't need any of that. They need the five things that prevent hallucinated scope: a goal, user stories with acceptance criteria, edge cases, failure states, and an explicit out-of-scope list. Everything else is noise that eats context window.

This is the template I use to ship features with Claude Code, Cursor, and Codex. It's also the format ClearSpec generates automatically when you describe what you want to build.

Why a spec template matters for AI coding

If you've been vibe coding — describing features in chat and iterating — you've already felt the ceiling. The first pass is fast. The fifth revision is not. And the tenth "actually, I also need it to handle the case where..." is slower than writing the code yourself.

The reason is simple: AI agents are literal executors. They build what the spec says. If the spec is a sentence, the agent fills in every gap with its best guess — and its best guess about your domain is usually wrong.

A spec template solves this by giving you a checklist of what the agent needs to know. Fill in the sections, hand it to the agent, and the first pass comes back dramatically closer to what you actually wanted.

The template

Here's the full template. Copy it, fill in the brackets, and paste it into your agent's context (CLAUDE.md, Cursor Rules, or just the chat).

# [Feature Name]

## Goal
[One paragraph. What is this feature and why does it exist?
Not "add auth" — "let returning users sign in with the same
OAuth provider they used before so their data is still attached."]

## User Stories
- As a [persona], I can [action] so that [benefit]
  - Acceptance: [measurable criterion]
  - Acceptance: [measurable criterion]
- As a [persona], I can [action] so that [benefit]
  - Acceptance: [measurable criterion]

## Acceptance Criteria
- [ ] [Global criterion that applies to the whole feature]
- [ ] [Performance target: e.g. "completes in under 2 seconds"]
- [ ] [Security requirement: e.g. "no tokens exposed in URLs"]

## Edge Cases
| Scenario | Expected Behavior |
|----------|-------------------|
| [What if X is empty?] | [Fallback behavior] |
| [What if the user does Y twice?] | [Idempotent behavior] |
| [What if the external API is down?] | [Graceful degradation] |

## Failure States
| Trigger | Behavior | Recovery |
|---------|----------|----------|
| [Network timeout] | [User-facing error message] | [Retry logic] |
| [Invalid input] | [Validation error] | [Clear message] |
| [Database unavailable] | [503 with no leaked details] | [Queue + alert] |

## Dependencies
- [External API, library, or service this feature relies on]
- [Environment variables or secrets required]

## Out of Scope
- [Feature X — will be addressed in a later iteration]
- [Migration Y — not part of this change]
- [Anything the agent might over-deliver on]

## Verification
- [ ] Automated: [Integration test for the happy path]
- [ ] Automated: [Edge case and failure state tests]
- [ ] Manual: [QA walkthrough on staging]

How each section prevents a specific failure mode

Goal. Without it, the agent guesses the "why" and makes wrong trade-offs. A goal that says "reduce signup friction" produces different code than one that says "support OAuth so users don't need a password."

User Stories. The agent needs to know who it's building for. "A returning user" and "an admin" interact with the same feature differently. Listing personas prevents the agent from building a generic version that fits nobody.

Acceptance Criteria. This is the contract. If you can't write a test for it, the agent can't verify its own work. "It works" isn't a criterion. "Completes in under 2 seconds on a standard connection" is.

Edge Cases. This is where vibe coding breaks down. The happy path works on the first try. The sad path — empty lists, duplicate submissions, expired tokens — is where the agent hallucinates unless you tell it what to expect.

Failure States. Different from edge cases. Edge cases are unusual inputs; failure states are infrastructure problems. What happens when the database is unreachable? When the third-party API returns a 500? The agent needs explicit instructions here or it'll silently swallow errors.

Out of Scope. The most underrated section. Without it, Claude Code will helpfully add email/password auth when you asked for OAuth, rewrite your CSS framework while fixing a button, or add a feature you mentioned once in a comment. Agents over-deliver by default. The out-of-scope list is the leash.

Dependencies. Saves the agent from inventing its own solutions. If you specify "use Supabase Auth," the agent won't roll its own JWT implementation.

Verification. Gives the agent permission to write tests — and tells it what to test. Without this section, some agents skip tests entirely; others write superficial ones that only cover the happy path.

Filling in the template without domain expertise

Here's the thing: most developers skip specs not because they disagree with them, but because filling one out feels like homework. You know you need auth, but you don't immediately know all the edge cases for OAuth token expiry across providers.

That's exactly the problem ClearSpec solves. You type a plain-English description — "add Google and GitHub OAuth with session management" — and it generates a structured spec in this format, including edge cases and failure states you'd probably miss on your own. The AI asks a few clarifying questions (or you can skip them and let it fill in sensible defaults), then produces a complete spec you can hand directly to Claude Code.

It's free for your first few specs — try it here.

A worked example

Here's what the template looks like filled in for a real feature:

Goal: Implement a file upload system for user profile avatars, stored in S3 with CDN delivery, replacing the current Gravatar-only approach.

User stories:

• As a user, I can upload a profile photo from my settings page so that my avatar is personalized
  • Acceptance: Uploads accept JPEG, PNG, and WebP under 5MB
  • Acceptance: Avatar appears within 3 seconds of upload completion
• As a user, I can crop my uploaded photo before saving so that I control what's visible
  • Acceptance: Client-side crop UI with square aspect ratio lock

Edge cases:

• User uploads a 200MB raw photo → reject with clear size error before upload starts
• User uploads a valid JPEG with a .txt extension → accept based on magic bytes, not extension
• User's S3 upload succeeds but CDN propagation is slow → show previous avatar with a "processing" indicator

Failure states:

• S3 returns 503 → show "Upload temporarily unavailable, try again in a moment," retry 3x with exponential backoff
• Image processing lambda times out → keep the original avatar, log the failure, alert on-call

Out of scope:

• Animated GIFs (future iteration)
• Team/organization avatars (different feature)
• Gravatar removal (keep as fallback when no custom avatar exists)

Notice how the out-of-scope section prevents the agent from adding GIF support "while it's in there." That one line saves you an hour of rework.

Using the template with different agents

Claude Code: Drop the filled template into your CLAUDE.md under a ## Current Feature header, or paste it into the chat. Claude Code's context engineering means the spec persists across the session. For a deep dive on writing an effective CLAUDE.md project file, see How to write a CLAUDE.md that actually controls your AI coding agent.

Cursor: Add the spec to .cursorrules or paste it into Agent mode. Cursor's context window is shorter, so you may want to trim the verification section and let the agent infer tests from acceptance criteria.

Codex / GPT-based agents: These benefit most from the explicit structure because they're more likely to over-deliver without the out-of-scope leash. Include the full template.

Generate one instead of writing one

If filling in seven sections per feature sounds tedious, that's fair — it is tedious, which is why most people don't do it, which is why most AI-coded features need five revision passes instead of one.

ClearSpec automates the tedious part. Describe the feature in a sentence, optionally answer a few questions, and get a structured spec in this format. Then hand it to your agent and watch the first pass actually match what you wanted.

Try it free →