How to Write Software Requirements for AI Coding

TL;DR: AI tools need clear, unambiguous requirements. Vague requirements = hallucinated features. Learn the patterns that work.

Table of Contents

1. Why Requirements Matter for AI
2. Requirement Patterns
3. Anti-Patterns to Avoid
4. User Story Format
5. Acceptance Criteria
6. Examples
7. Templates

---

Why Requirements Matter for AI

AI coding tools pattern-match against training data. Without clear requirements, they:

• Invent features based on assumptions
• Implement the "average" solution
• Add complexity you didn't ask for

Clear requirements act as constraints:

Clear Requirement → Constrained AI → Correct Implementation

---

Requirement Patterns

Pattern 1: Specific Over General

❌ "The app should handle user input well" ✅ "Validate email format on blur, show error below field, block submit if invalid"

Pattern 2: Measurable Outcomes

❌ "The page should load fast" ✅ "Page load < 2 seconds on 3G, < 500ms on broadband"

Pattern 3: Explicit Scope

❌ "Users can manage their account" ✅ "Users can: view profile, edit name, change email, delete account. NOT: change password (handled by auth provider)"

Pattern 4: Edge Cases Defined

❌ "Show user's projects" ✅ "Show user's projects (max 100). If zero, show empty state with 'Create your first project' CTA"

---

Anti-Patterns to Avoid

Anti-Pattern	Problem	Fix
Assumed knowledge	"Implement standard auth"	Define exactly which auth flows
Ambiguous terms	"Make it user-friendly"	Specify exact UX requirements
Missing boundaries	"Add pagination"	Specify page size, max pages, UI
Tech in requirements	"Use React Query"	Keep requirements tech-agnostic

---

User Story Format

The Template

As a [user type],
I want [goal/desire],
So that [outcome/benefit].

Good Examples

As a project owner,
I want to delete projects I no longer need,
So that my dashboard stays organized.

As a new user,
I want to see a guided onboarding,
So that I understand how to use the app quickly.

AI-Optimized Stories

Add implementation hints without dictating tech:

As a project owner,
I want to delete projects,
So that my dashboard stays organized.

Notes for implementation:
- Confirm before delete (modal)
- Soft delete (recoverable for 30 days)
- Cascade delete tasks/docs
- Show success toast after delete

---

Acceptance Criteria

Given-When-Then Format

GIVEN [precondition]
WHEN [action]
THEN [expected result]

Example: Project Deletion

Acceptance Criteria:

1. GIVEN I am on a project's detail page
   WHEN I click the delete button
   THEN a confirmation modal appears

2. GIVEN the confirmation modal is open
   WHEN I click "Cancel"
   THEN the modal closes, project unchanged

3. GIVEN the confirmation modal is open
   WHEN I click "Delete"
   THEN the project is soft-deleted
   AND I'm redirected to dashboard
   AND a success toast appears

4. GIVEN I have only one project
   WHEN I delete it
   THEN the dashboard shows empty state

---

Examples

Complete Requirement: Search Feature

## Search Projects

### User Story

As a user with many projects,
I want to search projects by name,
So that I can find specific projects quickly.

### Acceptance Criteria

1. GIVEN I have 10+ projects
   WHEN I type in the search box
   THEN matching projects filter instantly (debounce 300ms)

2. GIVEN I search for "marketing"
   WHEN there are matches
   THEN show matching projects, highlight matched text

3. GIVEN I search for "xyz123"
   WHEN there are no matches
   THEN show "No projects found" message

4. GIVEN I clear the search box
   WHEN it's empty
   THEN show all projects again

### Scope

- Search by project name only (not description)
- Case-insensitive
- Client-side filtering (no API call)

### NOT including

- Full-text search of project content
- Filters (status, date, etc.)
- Saved searches

---

Templates

Download

• PRD Template — Full requirements structure
• SDD Template Pack — Complete spec kit

Related

• How to Write a Tech Spec
• Spec-Driven Development

---

Clear requirements, clear code. Generate yours →

---

Last updated: January 2026