Writing Product Specifications

The quality of your product specification directly determines how well agentful can build your product. A well-written spec leads to autonomous development success. A vague spec leads to confusion, decisions, and delays.

Why Product Specifications Matter

Product specifications are the single source of truth for agentful. It's where you define:

What you're building (overview and features)
How it should work (acceptance criteria)
With what technologies (tech stack)
When it's done (success criteria)

agentful reads your specification on every iteration. The clearer and more specific it is, the less it needs to ask you for decisions.

The Golden Rule

Be specific. Be explicit. Use checklists.

Vague requirements force agentful to stop and ask. Specific requirements let agentful work autonomously.

Specification Structures: Flat vs Hierarchical

agentful supports two organizational structures for your product specifications. Both are valid - choose based on your project's complexity and team needs.

Structure Overview

Aspect	Flat Structure	Hierarchical Structure
File Location	`PRODUCT.md` or `.claude/product/index.md`	`.claude/product/domains/*/index.md`
Best For	Small to medium projects (3-15 features)	Large projects (15+ features)
Domain Concept	Sections within one file	Separate directories per domain
Maintainability	Easy for single author	Better for team collaboration
Scalability	Can get unwieldy past ~20 features	Scales to 50+ features
Navigation	Scroll through one file	Separate files per domain

Visual Comparison

Flat Structure (Single File):

.claude/product/index.md
├── Overview
├── Tech Stack
└── Features (by domain section)
    ├── Domain 1: Authentication
    │   ├── Feature 1.1
    │   └── Feature 1.2
    ├── Domain 2: Content Management
    │   ├── Feature 2.1
    │   └── Feature 2.2
    └── Domain 3: Analytics
        ├── Feature 3.1
        └── Feature 3.2

Hierarchical Structure (Directory Tree):

.claude/product/
├── index.md (overview + tech stack)
└── domains/
    ├── authentication/
    │   └── index.md (features 1.1, 1.2)
    ├── content-management/
    │   └── index.md (features 2.1, 2.2)
    └── analytics/
        └── index.md (features 3.1, 3.2)

Decision Matrix

Choose Flat Structure if:

✓ Your project has 15 or fewer features
✓ You're a solo developer or small team
✓ All features fit in 3-6 logical domains
✓ You want simpler file management
✓ You prefer everything in one place

Choose Hierarchical Structure if:

✓ Your project has 15+ features
✓ Multiple team members own different domains
✓ You have 6+ distinct business domains
✓ Domains have complex interdependencies
✓ You want parallel domain development
✓ You need granular progress tracking

Key Terminology Difference

Important: "Domain" means different things in each structure:

Flat: Domains are section headers in your single file (organizational tool)
Hierarchical: Domains are actual directories in your filesystem (architectural tool)

Both structures let you organize features by business domain - the difference is physical vs logical organization.

Migration Path

You can always start flat and migrate to hierarchical:

Start: Flat structure for rapid iteration
Grow: Hit ~15 features or multiple contributors?
Migrate: Split into domain directories (see migration guide below)

Organizing Features by Domain

Both flat and hierarchical structures use domain-based organization. This approach helps agentful better understand feature relationships, dependencies, and implementation order.

What Are Domains?

Domains are high-level business areas that group related features together. Think of them as logical containers for functionality that belongs together.

Examples of domains:

Authentication & User Management - User accounts, profiles, permissions
Content & Data Management - CRUD operations, search, categorization
Communication & Collaboration - Messaging, notifications, sharing
Commerce & Transactions - Orders, payments, inventory
Analytics & Reporting - Dashboards, charts, exports

Why Use Domains?

Better Organization: Related features stay together, making the spec easier to navigate
Clearer Dependencies: Domains show what functionality depends on what
Focused Development: agentful can complete one domain before moving to the next
Parallelizable Work: Different domains can often be developed in parallel
Easier Maintenance: Future features have a clear place to belong

How to Structure Domains

Use a three-level hierarchy:

Domain 1: [Domain Name]
  ├─ Feature 1.1 - [Priority]
  ├─ Feature 1.2 - [Priority]
  └─ Feature 1.3 - [Priority]
 
Domain 2: [Domain Name]
  ├─ Feature 2.1 - [Priority]
  └─ Feature 2.2 - [Priority]

In flat structure, these domains become section headers in one file.

In hierarchical structure, these domains become separate directories with their own files.

Example: Task Management App

Instead of a flat list:

## Features
1. User Authentication - CRITICAL
2. Task Management - HIGH
3. Real-time Updates - MEDIUM
4. User Profile - LOW
5. Team Collaboration - MEDIUM

Use domains:

## Features
 
### Domain 1: Authentication & User Management
#### 1.1 User Authentication - CRITICAL
[Details...]
 
#### 1.2 User Profile - LOW
[Details...]
 
### Domain 2: Task & Project Management
#### 2.1 Task Management - HIGH
[Details...]
 
#### 2.2 Real-time Updates - MEDIUM
[Details...]
 
### Domain 3: Team Collaboration
#### 3.1 Team Features - MEDIUM
[Details...]

Domain Best Practices

Start with Critical Domains: Begin with domains that contain CRITICAL priority features
Limit Domain Count: 3-6 domains is optimal for most projects
Balance Features: Each domain should have 2-5 features
Clear Boundaries: Features should clearly belong to one domain (no overlap)
Logical Flow: Order domains by dependency (authentication → content → analytics)

Identifying Your Domains

Ask yourself:

What are the main business areas?
- E-commerce: Products, Orders, Customers, Marketing
- SaaS: Users, Billing, Content, Analytics
- Social: Profiles, Connections, Content, Messaging
What features belong together?
- Group features that share data models
- Group features used by the same users
- Group features with similar technical requirements
What depends on what?
- Authentication usually comes first
- Core content before analytics
- Basic CRUD before advanced features

Product Specification Templates

Template 1: Flat Structure (Single File)

Best for: Projects with 3-15 features, solo developers, small teams

File locations:

PRODUCT.md (root directory)
OR .claude/product/index.md (recommended)

# Product Specification
 
## Overview
 
[2-3 sentences describing what you're building and who it's for]
 
## Goals
 
- [ ] [Primary goal 1]
- [ ] [Primary goal 2]
- [ ] [Primary goal 3]
 
## Tech Stack
 
### Frontend
- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
- **Language**: [TypeScript / JavaScript]
- **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
- **State Management**: [Zustand / Context API / Redux / Jotai]
 
### Backend
- **Runtime**: [Node.js / Bun / Deno]
- **Framework**: [Next.js API Routes / Express / Fastify / NestJS / Hono]
- **Language**: [TypeScript / JavaScript]
 
### Database
- **Database**: [PostgreSQL / MySQL / SQLite / MongoDB / PlanetScale]
- **ORM**: [Prisma / Drizzle / TypeORM / Mongoose]
 
### Authentication
- **Method**: [JWT / NextAuth / Clerk / Auth0 / Lucia]
 
### Testing
- **Unit**: [Vitest / Jest]
- **E2E**: [Playwright / Cypress]
 
### Deployment
- **Hosting**: [Vercel / Netlify / Railway / Fly.io]
 
## Features (Domain-Based Organization)
 
Organize features into domains as sections, then prioritize within each domain:
 
### Domain 1: [Domain Name]
 
#### 1.1 [Feature Name] - CRITICAL
**Description**: [What this feature does in one sentence]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific, testable requirement 1]
- [ ] [Specific, testable requirement 2]
- [ ] [Specific, testable requirement 3]
 
**Technical Notes** (Optional):
- [API endpoints, components, libraries, etc.]
 
---
 
#### 1.2 [Feature Name] - HIGH
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
**Technical Notes** (Optional):
- [Relevant implementation details]
 
---
 
### Domain 2: [Domain Name]
 
#### 2.1 [Feature Name] - HIGH
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
---
 
#### 2.2 [Feature Name] - MEDIUM
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
---
 
### Domain 3: [Domain Name]
 
#### 3.1 [Feature Name] - MEDIUM
**Description**: [What this feature does]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
 
---
 
#### 3.2 [Feature Name] - LOW
**Description**: [What this feature does]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
 
---
 
**Note**: Repeat for as many domains and features as needed. Aim for 3-6 domains with 2-5 features each.
 
## Architecture Notes (Optional)
 
### Folder Structure
 
If you have a preferred structure:
 
    src/
    ├── app/              # Next.js app router
    ├── components/       # React components
    ├── lib/              # Utilities
    ├── hooks/            # Custom hooks
    └── styles/           # Global styles
 
Or:
 
    src/
    ├── app/              # Next.js app router
    ├── components/       # React components
    │   ├── ui/          # Reusable UI components
    │   └── features/    # Feature-specific components
    ├── lib/              # Utilities and helpers
    ├── hooks/            # Custom React hooks
    ├── services/         # API services
    └── types/            # TypeScript types
 
### Design Patterns
 
- [Any specific patterns to use]
- [Any patterns to avoid]
 
### Constraints
 
- [Performance requirements]
- [Accessibility requirements]
- [Browser support requirements]
 
## Third-Party Integrations (Optional)
 
- [API 1]: [Purpose and usage notes]
- [API 2]: [Purpose and usage notes]
 
## Out of Scope (for MVP)
 
List what you're explicitly NOT building:
 
- [Feature X] - Will add in v2
- [Feature Y] - Out of scope
- [Feature Z] - Not needed
 
## Success Criteria
 
The product is complete when:
 
1. [All critical features implemented and tested]
2. [All tests passing with 80%+ coverage]
3. [No type errors (adapts to stack)]
4. [No security vulnerabilities]
5. [Deployed to production]
 
## Notes
 
[Any additional context, links, or documentation]

Template 2: Hierarchical Structure (Directory Tree)

Best for: Projects with 15+ features, multiple team members, complex domains

File structure:

.claude/product/
├── index.md                    # Overview + Tech Stack
└── domains/
    ├── authentication/
    │   └── index.md            # Auth features
    ├── content-management/
    │   └── index.md            # Content features
    └── analytics/
        └── index.md            # Analytics features

Main file: .claude/product/index.md

# Product Specification
 
## Overview
 
[2-3 sentences describing what you're building and who it's for]
 
## Goals
 
- [ ] [Primary goal 1]
- [ ] [Primary goal 2]
- [ ] [Primary goal 3]
 
## Tech Stack
 
### Frontend
- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
- **Language**: [TypeScript / JavaScript]
- **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
- **State Management**: [Zustand / Context API / Redux / Jotai]
 
### Backend
- **Runtime**: [Node.js / Bun / Deno]
- **Framework**: [Next.js API Routes / Express / Fastify / NestJS / Hono]
- **Language**: [TypeScript / JavaScript]
 
### Database
- **Database**: [PostgreSQL / MySQL / SQLite / MongoDB / PlanetScale]
- **ORM**: [Prisma / Drizzle / TypeORM / Mongoose]
 
### Authentication
- **Method**: [JWT / NextAuth / Clerk / Auth0 / Lucia]
 
### Testing
- **Unit**: [Vitest / Jest]
- **E2E**: [Playwright / Cypress]
 
### Deployment
- **Hosting**: [Vercel / Netlify / Railway / Fly.io]
 
## Domains
 
This product is organized into the following domains:
 
1. **Authentication & User Management** - User accounts, profiles, permissions
   → See `.claude/product/domains/authentication/index.md`
 
2. **Content Management** - CRUD operations, search, categorization
   → See `.claude/product/domains/content-management/index.md`
 
3. **Analytics & Reporting** - Dashboards, charts, exports
   → See `.claude/product/domains/analytics/index.md`
 
## Architecture Notes (Optional)
 
### Folder Structure
[Your preferred structure]
 
### Design Patterns
[Patterns to use/avoid]
 
### Constraints
[Performance, accessibility, browser support]
 
## Third-Party Integrations (Optional)
 
- [API 1]: [Purpose and usage notes]
- [API 2]: [Purpose and usage notes]
 
## Out of Scope (for MVP)
 
List what you're explicitly NOT building:
 
- [Feature X] - Will add in v2
- [Feature Y] - Out of scope
- [Feature Z] - Not needed
 
## Success Criteria
 
The product is complete when:
 
1. [All critical features implemented and tested]
2. [All tests passing with 80%+ coverage]
3. [No type errors (adapts to stack)]
4. [No security vulnerabilities]
5. [Deployed to production]
 
## Notes
 
[Any additional context, links, or documentation]

Domain file: .claude/product/domains/authentication/index.md

# Domain: Authentication & User Management
 
## Domain Overview
 
This domain handles all user identity and access management functionality including registration, login, profile management, and permissions.
 
## Dependencies
 
- Depends on: Database setup
- Required by: All other domains (content, analytics, etc.)
 
## Features
 
### 1.1 User Registration - CRITICAL
 
**Description**: New users can create accounts with email verification
 
**User Stories**:
- As a new user, I want to register with email so that I can access the platform
- As a security-conscious user, I want email verification so that my account is secure
 
**Acceptance Criteria**:
- [ ] Registration form with: email, password, confirm password fields
- [ ] Email validation: required, valid format, not already registered
- [ ] Password validation: required, min 8 chars, uppercase + lowercase + number
- [ ] Password confirmation must match
- [ ] On success: create user, send verification email, show "check your email" message
- [ ] On failure: inline error with specific reason (email taken, weak password, etc.)
- [ ] Verification link expires in 24 hours
- [ ] Verification link can be resent from login page
 
**Technical Notes**:
- Use bcrypt for password hashing (cost factor 12)
- Use JWT for verification token (expires in 24h)
- Rate limit registration: max 3 attempts per hour per IP
 
---
 
### 1.2 User Login - CRITICAL
 
**Description**: Registered users can authenticate with credentials
 
**User Stories**:
- As a registered user, I want to login so that I can access my account
- As a user, I want secure sessions so that my account isn't compromised
 
**Acceptance Criteria**:
- [ ] Login form with email and password fields
- [ ] Email validation: required, valid format
- [ ] Password validation: required, min 8 characters
- [ ] On success: verify email is verified, store JWT in httpOnly cookie, redirect to /dashboard
- [ ] On failure: inline error with specific reason (not found, wrong password, not verified)
- [ ] Show "resend verification" link if email not verified
- [ ] Rate limiting: max 5 attempts per 15 minutes per IP
- [ ] JWT valid for 7 days
 
**Technical Notes**:
- JWT includes: userId, email, role, issuedAt, expiresAt
- httpOnly cookie: secure=true, sameSite=strict, httpOnly=true
- Use existing auth pattern in src/lib/auth.ts
 
---
 
### 1.3 User Profile - HIGH
 
**Description**: Users can view and edit their profile information
 
**User Stories**:
- As a user, I want to update my profile so that my information is current
- As a user, I want to see my profile data so that I know what's stored
 
**Acceptance Criteria**:
- [ ] Profile page at /profile
- [ ] Display: name, email, registration date, last login
- [ ] Edit form: name (optional), email (optional, requires verification if changed)
- [ ] Profile picture upload (max 2MB, jpg/png)
- [ ] "Save Changes" button with loading state
- [ ] Success toast: "Profile updated"
- [ ] Error handling with specific messages
 
---
 
### 1.4 Password Reset - MEDIUM
 
**Description**: Users can reset forgotten passwords via email
 
**User Stories**:
- As a user, I want to reset my password so that I can regain access
 
**Acceptance Criteria**:
- [ ] "Forgot password" link on login page
- [ ] Request form: email field
- [ ] On submit: send reset link if email exists (always show success message to prevent email enumeration)
- [ ] Reset email contains link to /reset-password?token=xxx
- [ ] Reset link expires in 1 hour
- [ ] Reset form: new password, confirm password
- [ ] On success: show success message, redirect to login
- [ ] Invalid/expired tokens show clear error message
 
**Technical Notes**:
- Use separate reset token (different from auth JWT)
- Invalidate all user sessions after password reset
- Rate limit: max 3 reset requests per hour per email
 
---
 
## Domain Success Criteria
 
This domain is complete when:
 
1. All CRITICAL and HIGH features implemented and tested
2. Unit tests for auth utilities (hashing, token generation)
3. Integration tests for all auth flows
4. E2E tests for critical user journeys (register → verify → login → profile)
5. Security audit passes (no SQL injection, XSS, CSRF vulnerabilities)

Domain file: .claude/product/domains/content-management/index.md

# Domain: Content Management
 
## Domain Overview
 
This domain handles all content creation, editing, organization, and retrieval functionality.
 
## Dependencies
 
- Depends on: Authentication & User Management domain
- Required by: Analytics domain
 
## Features
 
### 2.1 Create Content - CRITICAL
 
**Description**: Authenticated users can create new content items
 
**User Stories**:
- As a user, I want to create content so that I can share information
 
**Acceptance Criteria**:
- [ ] Create page at /content/new
- [ ] Form fields: title (required), body (required, rich text), tags (optional), category (dropdown)
- [ ] Title validation: required, 5-100 chars
- [ ] Body validation: required, 20-10000 chars
- [ ] Rich text editor: bold, italic, links, lists, headings
- [ ] "Publish" button (saves immediately)
- [ ] "Save Draft" button (saves as draft status)
- [ ] Success toast: "Content published" or "Draft saved"
- [ ] Redirect to content detail page after publish
 
---
 
### 2.2 View Content List - CRITICAL
 
**Description**: Users can browse all published content
 
**User Stories**:
- As a user, I want to see all content so that I can find what interests me
 
**Acceptance Criteria**:
- [ ] Content list page at /content
- [ ] Grid layout showing content cards
- [ ] Each card shows: title, excerpt (150 chars), author name, date, category tag
- [ ] Responsive grid: 1 col mobile, 2 tablet, 3 desktop
- [ ] Pagination: 12 items per page
- [ ] Filter by category (dropdown)
- [ ] Search by title (debounced 300ms)
- [ ] Loading skeleton while fetching
- [ ] Empty state: "No content found"
 
---
 
### 2.3 View Content Detail - CRITICAL
 
**Description**: Users can read full content items
 
**User Stories**:
- As a user, I want to read full content so that I can get detailed information
 
**Acceptance Criteria**:
- [ ] Detail page at /content/[id]
- [ ] Display: title, author, date, category, body (rich text rendered)
- [ ] Show author info: name, avatar, bio
- [ ] "Edit" button (only for content author)
- [ ] Loading state while fetching
- [ ] 404 page if content not found or deleted
- [ ] SEO metadata: title, description, OG tags
 
---
 
### 2.4 Edit Content - HIGH
 
**Description**: Content authors can edit their own content
 
**User Stories**:
- As a content author, I want to edit my content so that I can correct mistakes
 
**Acceptance Criteria**:
- [ ] Edit page at /content/[id]/edit (only for author)
- [ ] Pre-fill form with existing content
- [ ] Same validation as create
- [ ] "Update" button with loading state
- [ ] "Cancel" button returns to detail view
- [ ] Success toast: "Content updated"
- [ ] 403 error if user tries to edit others' content
 
---
 
### 2.5 Delete Content - MEDIUM
 
**Description**: Content authors can delete their own content
 
**User Stories**:
- As a content author, I want to delete content so that I can remove outdated info
 
**Acceptance Criteria**:
- [ ] Delete button on detail page (only for author)
- [ ] Confirmation dialog: "Delete this content? This cannot be undone."
- [ ] On confirm: soft delete (set deletedAt timestamp)
- [ ] Success toast: "Content deleted"
- [ ] Redirect to /content
- [ ] Deleted content doesn't appear in lists
 
---
 
## Domain Success Criteria
 
This domain is complete when:
 
1. All CRITICAL and HIGH features implemented and tested
2. Rich text editor properly sanitizes HTML (XSS prevention)
3. Soft delete works correctly (content hidden but recoverable)
4. Authorization checks prevent editing/deleting others' content
5. Pagination and search perform well with 1000+ items

Domain file: .claude/product/domains/analytics/index.md

# Domain: Analytics & Reporting
 
## Domain Overview
 
This domain provides insights into content performance, user engagement, and platform metrics.
 
## Dependencies
 
- Depends on: Content Management domain
- Required by: None (leaf domain)
 
## Features
 
### 3.1 Content Analytics Dashboard - HIGH
 
**Description**: Content creators can view performance metrics for their content
 
**User Stories**:
- As a content creator, I want to see analytics so that I can understand engagement
 
**Acceptance Criteria**:
- [ ] Dashboard page at /analytics
- [ ] Only accessible to authenticated users
- [ ] Summary cards: total views, total likes, avg engagement rate
- [ ] Date range filter: last 7 days, 30 days, 90 days, custom
- [ ] Line chart: views over time (Chart.js or similar)
- [ ] Top 5 content table: title, views, likes, comments
- [ ] Loading states for all data
- [ ] Empty state if no analytics data
 
**Technical Notes**:
- Use aggregation queries for performance
- Cache analytics data for 5 minutes
- Store view events in separate analytics collection
 
---
 
### 3.2 Content Performance Detail - MEDIUM
 
**Description**: View detailed analytics for a single content item
 
**User Stories**:
- As a content creator, I want to see per-content analytics so that I can optimize
 
**Acceptance Criteria**:
- [ ] Analytics tab on content detail page (only for author)
- [ ] Show: total views, unique views, likes, comments, shares
- [ ] Views over time chart
- [ ] Referrer breakdown: direct, search, social, external
- [ ] Device breakdown: mobile, tablet, desktop
- [ ] Date range filter (same as dashboard)
 
---
 
### 3.3 Export Analytics Report - LOW
 
**Description**: Users can export analytics data as CSV
 
**User Stories**:
- As a content creator, I want to export analytics so that I can analyze in Excel
 
**Acceptance Criteria**:
- [ ] "Export CSV" button on dashboard
- [ ] Button shows loading state while generating
- [ ] CSV includes: content id, title, views, likes, comments, date range
- [ ] File download triggers automatically
- [ ] Filename format: analytics-YYYY-MM-DD.csv
 
---
 
## Domain Success Criteria
 
This domain is complete when:
 
1. All HIGH priority features implemented and tested
2. Analytics queries are optimized (don't slow down content loading)
3. Charts render correctly on all screen sizes
4. CSV export handles special characters properly
5. Date range filtering works across all features

Migrating from Flat to Hierarchical

When your flat file becomes unwieldy (15+ features or multiple contributors):

Step 1: Create domain directories

mkdir -p .claude/product/domains/authentication
mkdir -p .claude/product/domains/content-management
mkdir -p .claude/product/domains/analytics

Step 2: Split your flat file

Move overview + tech stack to .claude/product/index.md
Create index.md in each domain directory
Move feature sections to appropriate domain files
Add domain overview and dependencies to each file

Step 3: Update the main index

Add "## Domains" section listing all domains
Include file paths for each domain
Maintain same numbering scheme (1.1, 1.2, 2.1, etc.)

Step 4: Test the structure

# agentful will read the hierarchical structure automatically
agentful status

Key: Feature numbering stays consistent (1.1, 2.1, etc.) regardless of structure.

# Product Specification
 
## Overview
 
[2-3 sentences describing what you're building and who it's for]
 
## Goals
 
- [ ] [Primary goal 1]
- [ ] [Primary goal 2]
- [ ] [Primary goal 3]
 
## Tech Stack
 
### Frontend
- **Framework**: [Next.js 14 / React + Vite / Vue + Nuxt / SvelteKit]
- **Language**: [TypeScript / JavaScript]
- **Styling**: [Tailwind CSS / CSS Modules / styled-components / shadcn/ui]
- **State Management**: [Zustand / Context API / Redux / Jotai]
 
### Backend
- **Runtime**: [Node.js / Bun / Deno]
- **Framework**: [Next.js API Routes / Express / Fastify / NestJS / Hono]
- **Language**: [TypeScript / JavaScript]
 
### Database
- **Database**: [PostgreSQL / MySQL / SQLite / MongoDB / PlanetScale]
- **ORM**: [Prisma / Drizzle / TypeORM / Mongoose]
 
### Authentication
- **Method**: [JWT / NextAuth / Clerk / Auth0 / Lucia]
 
### Testing
- **Unit**: [Vitest / Jest]
- **E2E**: [Playwright / Cypress]
 
### Deployment
- **Hosting**: [Vercel / Netlify / Railway / Fly.io]
 
## Features (Hierarchical Domain-Based Structure)
 
Organize features into domains, then prioritize within each domain:
 
### Domain 1: [Domain Name]
 
#### 1.1 [Feature Name] - CRITICAL
**Description**: [What this feature does in one sentence]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific, testable requirement 1]
- [ ] [Specific, testable requirement 2]
- [ ] [Specific, testable requirement 3]
 
**Technical Notes** (Optional):
- [API endpoints, components, libraries, etc.]
 
---
 
#### 1.2 [Feature Name] - HIGH
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
**Technical Notes** (Optional):
- [Relevant implementation details]
 
---
 
### Domain 2: [Domain Name]
 
#### 2.1 [Feature Name] - HIGH
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
---
 
#### 2.2 [Feature Name] - MEDIUM
**Description**: [What this feature does]
 
**User Stories**:
- As a [user type], I want [feature] so that [benefit]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]
 
---
 
### Domain 3: [Domain Name]
 
#### 3.1 [Feature Name] - MEDIUM
**Description**: [What this feature does]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
 
---
 
#### 3.2 [Feature Name] - LOW
**Description**: [What this feature does]
 
**Acceptance Criteria**:
- [ ] [Specific requirement 1]
 
---
 
**Note**: Repeat for as many domains and features as needed. Aim for 3-6 domains with 2-5 features each.
 
## Architecture Notes (Optional)
 
### Folder Structure
 
If you have a preferred structure:
 
    src/
    ├── app/              # Next.js app router
    ├── components/       # React components
    ├── lib/              # Utilities
    ├── hooks/            # Custom hooks
    └── styles/           # Global styles
 
Or:
 
    src/
    ├── app/              # Next.js app router
    ├── components/       # React components
    │   ├── ui/          # Reusable UI components
    │   └── features/    # Feature-specific components
    ├── lib/              # Utilities and helpers
    ├── hooks/            # Custom React hooks
    ├── services/         # API services
    └── types/            # TypeScript types
 
### Design Patterns
 
- [Any specific patterns to use]
- [Any patterns to avoid]
 
### Constraints
 
- [Performance requirements]
- [Accessibility requirements]
- [Browser support requirements]
 
## Third-Party Integrations (Optional)
 
- [API 1]: [Purpose and usage notes]
- [API 2]: [Purpose and usage notes]
 
## Out of Scope (for MVP)
 
List what you're explicitly NOT building:
 
- [Feature X] - Will add in v2
- [Feature Y] - Out of scope
- [Feature Z] - Not needed
 
## Success Criteria
 
The product is complete when:
 
1. [All critical features implemented and tested]
2. [All tests passing with 80%+ coverage]
3. [No type errors (adapts to stack)]
4. [No security vulnerabilities]
5. [Deployed to production]
 
## Notes
 
[Any additional context, links, or documentation]

Section by Section Guide

Overview

Purpose: Quick understanding of what you're building.

Length: 2-3 sentences.

Include:

What the product is
Who it's for
Key value proposition

Good Example:

## Overview
A task management application for remote teams. Users can create projects, add tasks with deadlines, assign team members, and track progress with real-time updates.

Bad Example:

## Overview
A task app.  # Too vague - agentful doesn't know what features to include

Goals

Purpose: Define success metrics.

Format: Checkbox list (so you can track progress).

Good Example:

## Goals
 
- [ ] Users can register and login
- [ ] Users can create projects and tasks
- [ ] Users can assign tasks to team members
- [ ] Real-time updates when tasks change
- [ ] Mobile-responsive design

Tip: Keep goals high-level. Features are where you get specific.

Tech Stack

Purpose: Tell agentful what technologies to use.

Critical: Be explicit. Don't make agentful guess.

Frontend

### Frontend
- **Framework**: Next.js 14
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **State Management**: Zustand

Why this matters:

agentful generates specialized agents based on your stack
Different frameworks have different patterns (Next.js app router vs pages)
Testing setup depends on the framework

Backend

### Backend
- **Runtime**: Node.js
- **Framework**: Next.js API Routes
- **Language**: TypeScript

Tip: If using Next.js, backend is often integrated. Specify if using a separate backend server.

Database

### Database
- **Database**: PostgreSQL
- **ORM**: Prisma

Common choices:

PostgreSQL + Prisma - Most common, production-ready
SQLite + Prisma - Good for local development, simple apps
MongoDB + Mongoose - Flexible schema, document-based
None - In-memory state for simple apps

Be specific about the ORM. Prisma != Drizzle != TypeORM.

Authentication

### Authentication
- **Method**: JWT with httpOnly cookies

Options:

JWT - Stateless, scalable, common
Sessions - Simple, built-in to many frameworks
Clerk/Auth0 - Managed services, faster setup
None - If no auth needed for MVP

Testing

### Testing
- **Unit**: Vitest
- **E2E**: Playwright

Common pairs:

Vitest + Playwright - Modern, fast
Jest + Cypress - Traditional, widely-used

Deployment

### Deployment
- **Hosting**: Vercel

agentful uses this to:

Set build configurations
Configure environment variables
Add deployment scripts

Features (The Most Important Section)

This is where most PRODUCT.md files fail. Follow these patterns carefully.

Structure

Every feature needs:

### [Priority Number]. [Feature Name] - [PRIORITY LEVEL]
 
**Description**: [One sentence explaining what this feature does]
 
**Acceptance Criteria**:
- [ ] [Specific, testable requirement]
- [ ] [Specific, testable requirement]
- [ ] [Specific, testable requirement]
 
**User Stories** (optional):
- As a [user type], I want [feature] so that [benefit]
 
**Technical Notes** (optional):
- [Implementation hints or constraints]

Priority Levels

Use these consistently:

CRITICAL - Must have for MVP. agentful works on these first.
HIGH - Important, but can wait slightly.
MEDIUM - Nice to have.
LOW - Future improvements.

Acceptance Criteria (The Secret Sauce)

Good acceptance criteria are:

Specific - Clear what "done" looks like
Testable - Can write a test for it
Complete - Cover all key aspects
Checkable - Can verify with a checkbox

Examples

❌ Vague (Bad):

**Acceptance Criteria**:
- [ ] User can login
- [ ] Authentication works
- [ ] Security is good

Why this fails: agentful doesn't know:

What fields to include (email? username?)
What validation to apply
How to handle errors
What "good security" means

✅ Specific (Good):

**Acceptance Criteria**:
- [ ] Login form with email and password fields
- [ ] Email validation: required, valid format
- [ ] Password validation: required, min 8 characters
- [ ] On success: store JWT token in httpOnly cookie, redirect to /dashboard
- [ ] On failure: show inline error message with specific reason
- [ ] Prevent login for unverified emails (show "check your email" message)
- [ ] Rate limiting: max 5 attempts per 15 minutes per IP

Why this works: agentful knows exactly what to build. No decisions needed.

Writing Great Acceptance Criteria

Pattern 1: User Input

**Acceptance Criteria**:
- [ ] Input field for [field name]
- [ ] Validation: [required, format, min/max length]
- [ ] Placeholder text: "[example]"
- [ ] Error messages for invalid input
- [ ] Submit button that validates before submitting

Pattern 2: API Endpoints

**Acceptance Criteria**:
- [ ] POST /api/auth/login endpoint
- [ ] Request body: { email: string, password: string }
- [ ] Response success: { user: {...}, token: "..." } with 200 status
- [ ] Response error: { error: "specific message" } with 401 status
- [ ] Hash passwords with bcrypt before comparing
- [ ] Return JWT token valid for 7 days

Pattern 3: Data Display

**Acceptance Criteria**:
- [ ] Display list of [items]
- [ ] Show [field 1], [field 2], [field 3] for each item
- [ ] Loading state while fetching data
- [ ] Empty state with message when no items exist
- [ ] Error state with retry button when fetch fails

Pattern 4: User Actions

**Acceptance Criteria**:
- [ ] [Button/Action] triggers [action]
- [ ] Confirmation prompt: "[message]"
- [ ] On confirm: [what happens]
- [ ] On cancel: [what happens]
- [ ] Success notification: "[message]"
- [ ] Error handling with specific message

User Stories (Optional but Helpful)

Format:

**User Stories**:
- As a [user type], I want [feature] so that [benefit]

Example:

**User Stories**:
- As a registered user, I want to login with my email and password so that I can access my projects
- As a security-conscious user, I want rate limiting on login attempts so that my account can't be brute-forced

Why include these: Helps agentful understand context and make better decisions when ambiguity exists.

Technical Notes (When Needed)

Use this section to guide implementation when you have specific requirements:

**Technical Notes**:
- Use React Hook Form for form validation
- Store session in httpOnly cookie for security
- Implement rate limiting using Redis (or in-memory if Redis unavailable)
- Follow existing auth pattern in src/lib/auth.ts

When to include:

You have existing code agentful should follow
You need a specific library or pattern
There are performance constraints
There are security requirements

When to skip:

Let agentful decide the implementation
You don't have a strong preference
The "how" doesn't matter, only the "what"

Architecture Notes (Optional)

Purpose: Guide structural decisions without micromanaging.

Use when:

You have an existing codebase to match
You have strong architectural preferences
You're working with a team that needs consistency

Example:

### Folder Structure

src/ ├── app/ # Next.js app router ├── components/ # React components │ ├── ui/ # Reusable UI components │ └── features/ # Feature-specific components ├── lib/ # Utilities and helpers ├── hooks/ # Custom React hooks ├── services/ # API services └── types/ # TypeScript types

 
### Design Patterns
- Use React Hook Form for all forms
- Use TanStack Query for data fetching
- Use Zod for runtime validation
- Follow atomic design for components
 
### Constraints
- All API routes must return { data, error } format
- All components must be TypeScript strict
- Mobile-first responsive design
- WCAG 2.1 AA accessibility compliance

Out of Scope (for MVP)

Purpose: Explicitly state what you're NOT building.

Why this matters: Prevents agentful from wasting time on features you don't want.

Example:

## Out of Scope (for MVP)
 
- **User profiles** - Will add in v2, focus on core functionality first
- **Email notifications** - Out of scope for now, users check dashboard
- **Real-time collaboration** - Too complex for MVP, will use polling
- **Mobile apps** - Web-only for MVP
- **Payment processing** - Free tier only for launch

Tip: Be explicit. If you don't list it here, agentful might add it if it seems related to your features.

Success Criteria

Purpose: Define when agentful is "done".

Example:

## Success Criteria
 
The product is complete when:
 
1. All CRITICAL and HIGH priority features are implemented and tested
2. All tests passing with 80%+ coverage
3. No type errors (adapts to stack)
4. No security vulnerabilities (npm audit passes)
5. Manual testing confirms all user stories work
6. Deployed to production and accessible

agentful uses this to:

Know when to stop working
Prioritize validation checks
Determine if a feature is truly complete

Real Examples

Example 1: Simple Todo App (Flat Structure)

Structure: Single file (PRODUCT.md)

Best for: Simple projects with few features

# Product Specification
 
## Overview
A simple todo list application for personal task management.
 
## Tech Stack
 
### Frontend
- **Framework**: Next.js 14
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **State Management**: React Context API
 
### Backend
- **Framework**: Next.js API Routes
- **Language**: TypeScript
 
### Database
- **Database**: None (in-memory for MVP)
 
### Testing
- **Unit**: Vitest
 
## Features
 
### 1. Add Todo - CRITICAL
**Description**: Users can add new todo items to their list
 
**Acceptance Criteria**:
- [ ] Input field for todo text
- [ ] Text validation: required, max 200 characters
- [ ] "Add" button that creates todo
- [ ] New todo appears at top of list
- [ ] Input clears after adding
- [ ] Enter key also submits todo
 
### 2. Toggle Todo - HIGH
**Description**: Users can mark todos as complete or incomplete
 
**Acceptance Criteria**:
- [ ] Click todo to toggle completion status
- [ ] Completed todos show strikethrough text
- [ ] Completed todos have gray opacity
- [ ] Toggle persists across page reloads
 
### 3. Delete Todo - MEDIUM
**Description**: Users can delete todos they no longer need
 
**Acceptance Criteria**:
- [ ] Delete button on each todo (trash icon)
- [ ] Confirmation dialog before delete
- [ ] Todo immediately removed on confirm
- [ ] Delete cancels if user clicks outside dialog
 
### 4. Filter Todos - LOW
**Description**: Users can view all, active, or completed todos
 
**Acceptance Criteria**:
- [ ] Filter tabs: All, Active, Completed
- [ ] Active filter shows only incomplete todos
- [ ] Completed filter shows only completed todos
- [ ] All filter shows everything
 
## Success Criteria
 
1. All CRITICAL and HIGH features implemented
2. All tests passing with 80%+ coverage
3. No type errors (adapts to stack)
4. Manual testing confirms all features work

Why this works:

Clear, specific acceptance criteria
Tech stack fully specified
Priorities clearly marked
Success criteria defined

Example 2: E-commerce Platform (Flat Structure)

Structure: Single file (PRODUCT.md) with domain-based sections

Best for: Medium-complexity projects with multiple domains

# Product Specification
 
## Overview
A modern e-commerce platform for selling digital products. Customers can browse products, add to cart, and checkout with Stripe payment.
 
## Tech Stack
 
### Frontend
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS + shadcn/ui
- **State Management**: Zustand
 
### Backend
- **Runtime**: Node.js
- **Framework**: Next.js API Routes
- **Language**: TypeScript
 
### Database
- **Database**: PostgreSQL (Supabase)
- **ORM**: Prisma
 
### Authentication
- **Method**: JWT with httpOnly cookies
 
### Payment
- **Provider**: Stripe
- **Mode**: Checkout Session (redirect-based)
 
### Testing
- **Unit**: Vitest
- **E2E**: Playwright
 
### Deployment
- **Hosting**: Vercel
 
## Features
 
### 1. Product Listing - CRITICAL
**Description**: Customers can browse all available digital products
 
**Acceptance Criteria**:
- [ ] Grid layout showing product cards
- [ ] Each card shows: product image, name, price, description (truncated)
- [ ] Responsive grid: 1 column mobile, 2 tablet, 3 desktop, 4 large screens
- [ ] Loading skeleton while fetching products
- [ ] Empty state with "No products available" message
- [ ] Hover effect on cards (slight elevation)
- [ ] Click card to navigate to product detail page
 
### 2. Product Detail - CRITICAL
**Description**: Customers can view detailed information about a product
 
**Acceptance Criteria**:
- [ ] Large product image (800x600)
- [ ] Product name, price, full description
- [ ] "Add to Cart" button
- [ ] "Back to Products" link
- [ ] Loading state while fetching
- [ ] Error state if product not found (404)
- [ ] Metadata for SEO (title, description, OG tags)
 
### 3. Shopping Cart - CRITICAL
**Description**: Customers can manage items in their cart
 
**Acceptance Criteria**:
- [ ] Cart icon in header showing item count badge
- [ ] Click cart icon to open cart drawer/slide-over
- [ ] Cart shows list of items with:
  - Product thumbnail
  - Product name
  - Price
  - Quantity selector (+/- buttons)
  - Remove button
- [ ] Subtotal calculation
- [ ] "Checkout" button (disabled if cart empty)
- [ ] Cart persists in localStorage
- [ ] Close button on cart drawer
 
### 4. Add to Cart - HIGH
**Description**: Customers can add products to their cart
 
**Acceptance Criteria**:
- [ ] "Add to Cart" button on product detail page
- [ ] Button shows loading state while adding
- [ ] Success toast notification: "Added [Product] to cart"
- [ ] Error toast if add fails
- [ ] Cart count badge updates immediately
- [ ] If item already in cart, increment quantity instead of duplicate
 
### 5. Stripe Checkout - HIGH
**Description**: Customers can pay for their cart items using Stripe
 
**Acceptance Criteria**:
- [ ] Checkout button creates Stripe Checkout Session
- [ ] Request includes: line_items, success_url, cancel_url
- [ ] User redirects to Stripe-hosted checkout page
- [ ] Success URL: /checkout/success?session_id=xxx
- [ ] Cancel URL: /checkout/cancel
- [ ] Environment variable STRIPE_SECRET_KEY for API calls
- [ ] Environment variable NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY for client
- [ ] Webhook endpoint at /api/webhooks/stripe
- [ ] Webhook verifies signature using Stripe SDK
- [ ] Webhook handles checkout.session.completed event
- [ ] On success: clear cart, show order confirmation
- [ ] On cancel: return to cart, show "Payment cancelled" message
 
### 6. Order Confirmation - HIGH
**Description**: Customers see confirmation after successful payment
 
**Acceptance Criteria**:
- [ ] Page at /checkout/success
- [ ] Show order ID from Stripe session
- [ ] Show list of purchased items
- [ ] Show total amount paid
- [ ] "Continue Shopping" button to /products
- [ ] Email notification with order details (optional for MVP)
 
**Technical Notes**:
- Store order in database on webhook receipt
- Order schema: id, stripeSessionId, items, total, createdAt
 
### 7. Product Search - MEDIUM
**Description**: Customers can search products by name or description
 
**Acceptance Criteria**:
- [ ] Search input in header
- [ ] Debounced search (300ms delay)
- [ ] Search filters by product name and description
- [ ] Search results update product listing grid
- [ ] Clear search button (X icon in input)
- [ ] "No results found" message for empty searches
- [ ] URL query param ?search=query for shareable links
 
### 8. Admin Product Management - LOW
**Description**: Admin users can add, edit, and delete products
 
**Acceptance Criteria**:
- [ ] Admin route: /admin/products
- [ ] Protected: only accessible if ADMIN_EMAIL env var matches user email
- [ ] List all products with edit/delete buttons
- [ ] Add product form: name, price, description, image URL
- [ ] Edit product pre-fills form
- [ ] Delete product requires confirmation
- [ ] All changes update database immediately
 
**Out of Scope (for MVP)**:
- User authentication (simple email check for admin)
- Product image upload (use URL for now)
- Order history for customers
- Inventory management
- Product categories
- Product reviews/ratings
- Discount codes
- Shipping (digital products only)
 
## Success Criteria
 
1. All CRITICAL and HIGH features implemented and tested
2. All tests passing with 80%+ coverage
3. No type errors (adapts to stack)
4. Stripe test mode checkout works end-to-end
5. Webhook successfully processes test payments
6. Deployed to Vercel with environment variables configured
7. Manual testing confirms complete purchase flow

Why this works:

Extremely detailed acceptance criteria
Technical notes guide implementation
Out of scope prevents feature creep
Real-world constraints included (webhook, Stripe flow)
Testing considerations mentioned

Example 3: SaaS Platform (Hierarchical Structure)

Structure: Directory tree (.claude/product/domains/*/index.md)

Best for: Large projects with multiple team members

Main file: .claude/product/index.md

# Product Specification
 
## Overview
A project management SaaS platform for software teams. Teams can create projects, manage tasks, track time, and collaborate in real-time.
 
## Goals
- [ ] Users can register and create teams
- [ ] Teams can manage multiple projects
- [ ] Real-time task collaboration
- [ ] Time tracking and reporting
- [ ] Team analytics and insights
 
## Tech Stack
 
### Frontend
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS + shadcn/ui
- **State Management**: Zustand
- **Real-time**: Socket.io client
 
### Backend
- **Runtime**: Node.js
- **Framework**: Express
- **Language**: TypeScript
- **Real-time**: Socket.io
 
### Database
- **Database**: PostgreSQL (Supabase)
- **ORM**: Prisma
 
### Authentication
- **Method**: JWT with httpOnly cookies
 
### Testing
- **Unit**: Vitest
- **E2E**: Playwright
 
### Deployment
- **Hosting**: Vercel (frontend) + Railway (backend)
 
## Domains
 
This product is organized into the following domains:
 
1. **Authentication & Team Management** - User accounts, team creation, invitations
   → See `.claude/product/domains/authentication/index.md`
 
2. **Project & Task Management** - Projects, tasks, subtasks, dependencies
   → See `.claude/product/domains/projects/index.md`
 
3. **Time Tracking** - Time entries, reports, exports
   → See `.claude/product/domains/time-tracking/index.md`
 
4. **Analytics & Reporting** - Team performance, burndown charts
   → See `.claude/product/domains/analytics/index.md`
 
## Out of Scope (for MVP)
 
- File attachments and document management
- Video calls and screen sharing
- Mobile apps (web-only for MVP)
- Custom workflows and automations
- API for third-party integrations
 
## Success Criteria
 
1. All CRITICAL and HIGH features implemented and tested
2. Real-time collaboration works smoothly (WebSocket tests passing)
3. All tests passing with 80%+ coverage
4. No type errors
5. No security vulnerabilities
6. Deployed to production with monitoring setup
 
## Notes
 
- Each domain has a dedicated team member
- Use WebSocket for real-time updates (tasks, comments)
- Implement optimistic UI for better UX
- Focus on core collaboration features first

Domain file: .claude/product/domains/authentication/index.md

# Domain: Authentication & Team Management
 
## Domain Overview
Handles user registration, login, team creation, and team member management.
 
## Dependencies
- Depends on: Database setup
- Required by: All other domains
 
## Features
 
### 1.1 User Registration - CRITICAL
**Acceptance Criteria**:
- [ ] Registration form: name, email, password, company name
- [ ] Email verification required before access
- [ ] On registration: create user, create team (user is owner), send verification email
- [ ] JWT token in httpOnly cookie (7 day expiry)
- [ ] Rate limit: 3 attempts per hour per IP
 
### 1.2 Team Invitations - CRITICAL
**Acceptance Criteria**:
- [ ] Invite form: email address, role (admin/member/viewer)
- [ ] Invitation email with signup link
- [ ] Invitation link expires in 7 days
- [ ] Team owners/admins can send invitations
- [ ] Accepting invite adds user to team
- [ ] Revoke invitation button
 
### 1.3 Team Management - HIGH
**Acceptance Criteria**:
- [ ] Team settings page: name, description, avatar
- [ ] Team members list with roles
- [ ] Change member role (owner/admin only)
- [ ] Remove member from team
- [ ] Delete team (owner only, requires confirmation)
 
## Domain Success Criteria
1. All CRITICAL and HIGH features implemented
2. Email verification flow works end-to-end
3. Team permissions enforced (members can't invite, etc.)
4. Security audit passes

Why this works:

Clear separation of concerns
Multiple team members can work on different domains simultaneously
Each domain file is focused and manageable
Dependencies are explicit
Easy to track progress per domain

Common Product Specification Mistakes

Mistake 1: Vague Requirements

❌ Bad:

### 1. User Authentication - CRITICAL
**Description**: Users can login
 
**Acceptance Criteria**:
- [ ] Login works
- [ ] Security is good

✅ Good:

### 1. User Authentication - CRITICAL
**Description**: Users can login with email and password
 
**Acceptance Criteria**:
- [ ] Login form with email and password fields
- [ ] Email validation: required, valid format
- [ ] Password validation: required, min 8 chars
- [ ] On success: JWT in httpOnly cookie, redirect to /dashboard
- [ ] On failure: inline error with specific reason
- [ ] Rate limiting: max 5 attempts per 15 min per IP

Mistake 2: Missing Tech Stack Details

❌ Bad:

## Tech Stack
- Next.js
- TypeScript
- Database

✅ Good:

## Tech Stack
 
### Frontend
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
 
### Backend
- **Framework**: Next.js API Routes
- **Language**: TypeScript
 
### Database
- **Database**: PostgreSQL
- **ORM**: Prisma

Mistake 3: No Priorities

❌ Bad:

## Features
1. Authentication
2. User profiles
3. Email notifications
4. Dark mode
5. Admin panel

✅ Good:

## Features
 
### 1. Authentication - CRITICAL
...
 
### 2. User profiles - HIGH
...
 
### 3. Email notifications - MEDIUM
...
 
### 4. Dark mode - LOW
...
 
### 5. Admin panel - LOW
...

Why priorities matter: agentful works CRITICAL → HIGH → MEDIUM → LOW. Without priorities, it might work on dark mode before authentication.

Mistake 4: No Acceptance Criteria

❌ Bad:

### 1. Shopping Cart - CRITICAL
Users can add items to cart and checkout.

✅ Good:

### 1. Shopping Cart - CRITICAL
**Description**: Users can add items to cart and checkout
 
**Acceptance Criteria**:
- [ ] Cart icon shows item count badge
- [ ] Add to cart button on product page
- [ ] Cart drawer shows items with quantities
- [ ] Update quantity with +/- buttons
- [ ] Remove items from cart
- [ ] Subtotal calculation
- [ ] Checkout button (disabled if empty)
- [ ] Cart persists in localStorage

Mistake 5: Acceptance Criteria That Aren't Testable

❌ Bad:

**Acceptance Criteria**:
- [ ] UI looks good
- [ ] Code is clean
- [ ] Performance is fast

✅ Good:

**Acceptance Criteria**:
- [ ] Components follow design system spacing (4px grid)
- [ ] All functions have single responsibility
- [ ] Page load time < 2 seconds on 3G

Mistake 6: Too Much Implementation Detail

❌ Bad (over-specifying):

**Acceptance Criteria**:
- [ ] Use React Hook Form with useForm hook
- [ ] Validate with Zod schema on line 15
- [ ] Call API endpoint /api/auth/login exactly
- [ ] Store token in cookie named 'auth_token'
- [ ] Use useEffect to fetch user data on mount
- [ ] Use useState for form state

✅ Good (focus on what, not how):

**Acceptance Criteria**:
- [ ] Login form with email/password fields
- [ ] Client-side validation before submission
- [ ] POST to /api/auth/login with credentials
- [ ] Store auth token securely
- [ ] Fetch and display user data on successful login

Let agentful figure out the "how". You specify the "what".

Product Specification Checklist

Use this checklist before starting agentful:

Structure

Chosen appropriate structure (flat for 3-15 features, hierarchical for 15+)
Flat: Single file with domain sections OR
Hierarchical: Main index + domain directories with index.md files

Content

Quality

No vague requirements ("works well", "good performance")
No missing tech stack details
Acceptance criteria use checkboxes
Features are organized by domain
Features are prioritized
Implementation details only when necessary
User stories included for complex features
Technical notes for specific constraints

Review

Had a teammate review (if working in team)
Tested clarity by asking: "Could I build this without questions?"
Removed ambiguity
Added examples where helpful

Tips for Success

1. Start Simple, Then Expand

First version:

### 1. Todo List - CRITICAL
**Description**: Users can see their todos
 
**Acceptance Criteria**:
- [ ] Display list of todos
- [ ] Each todo shows text

Then expand:

### 1. Todo List - CRITICAL
**Description**: Users can see and manage their todos
 
**Acceptance Criteria**:
- [ ] Display list of todos
- [ ] Each todo shows text and completion status
- [ ] Filter: all / active / completed
- [ ] Sort by date added (newest first)
- [ ] Empty state with illustration
- [ ] Loading state while fetching
- [ ] Error state with retry button

Why: Start with core functionality, then add polish after agentful completes the basics.

2. Use Examples in Acceptance Criteria

**Acceptance Criteria**:
- [ ] Email validation accepts formats like:
  - user@example.com
  - first.last@example.co.uk
  - user+tag@example.com
- [ ] Email validation rejects formats like:
  - user@ (no domain)
  - @example.com (no user)
  - user.example (no @)

Why: Examples make requirements concrete and testable.

3. Be Explicit About Edge Cases

**Acceptance Criteria**:
- [ ] Handle empty input gracefully
- [ ] Handle network errors with retry button
- [ ] Handle duplicate submissions (disable button on submit)
- [ ] Handle malicious input (sanitize user input)
- [ ] Handle expired auth tokens (auto-refresh or re-login)

Why: agentful will handle edge cases if you specify them. Otherwise, it might miss them.

4. Reference Existing Patterns

If you have existing code:

**Technical Notes**:
- Follow existing auth pattern in src/lib/auth.ts
- Match component structure in src/components/ui/
- Use same error handling pattern as src/app/api/products/route.ts

Why: Ensures consistency with your existing codebase.

5. Think About User Experience

**Acceptance Criteria**:
- [ ] Show loading state within 100ms of action (optimistic UI)
- [ ] Display success message for 3 seconds before auto-dismissing
- [ ] Confirm destructive actions with dialog
- [ ] Provide undo for non-destructive actions (like delete)
- [ ] Keyboard shortcuts: Enter to submit, Escape to cancel

Why: Great products are about UX, not just functionality.

6. Consider Performance Early

**Acceptance Criteria**:
- [ ] List items render with virtualization for 100+ items
- [ ] Images lazy load below the fold
- [ ] API responses include pagination (max 50 items per page)
- [ ] Cache GET requests for 5 minutes
- [ ] Debounce search input by 300ms

Why: Performance is easier to build in than retrofit later.

7. Plan for Testing

**Acceptance Criteria**:
- [ ] Unit tests for all business logic functions
- [ ] Integration tests for API endpoints
- [ ] E2E tests for critical user flows (login, checkout)
- [ ] Mock external dependencies (Stripe API, email service)

Why: agentful's tester agent needs to know what to test.

8. Use "Don't" Sections

**What NOT to do**:
- Don't use alerts for errors (use toast notifications)
- Don't hardcode strings (use i18n keys for future localization)
- Don't store sensitive data in localStorage
- Don't use any for types (be specific)

Why: Explicitly preventing bad patterns saves time.

Updating PRODUCT.md Mid-Development

When to Update

Safe to update:

Adding new LOW priority features
Clarifying ambiguous acceptance criteria
Adding technical notes for current work
Updating success criteria

Risky to update:

Changing priorities of in-progress features
Removing features agentful is working on
Completely changing tech stack mid-development
Modifying acceptance criteria of completed features

How to Update Safely

Run /agentful-status to see what's in progress
Only update features not yet started
Check .agentful/state.json for current phase
If changing priorities, explain why in "Notes" section

Example safe update:

## Notes
 
**[2026-01-18]** - Adding feature #8 (Dark mode) as LOW priority.
All CRITICAL and HIGH features complete, so this is safe to add.

Tools for Better PRODUCT.md

PRODUCT.md Validators

# Check for common issues
npx agentful validate-product
 
# Output:
✓ Overview present
✓ Tech stack specified
✓ Features prioritized
⚠ Feature 3 has no acceptance criteria
⚠ Feature 5 is vague: "Make it fast"

PRODUCT.md Templates

# Generate a template for your stack
npx agentful template --stack nextjs,prisma,tailwind
 
# Outputs a ready-to-fill PRODUCT.md with your stack pre-configured

Summary: The Perfect Product Specification

The perfect product specification is:

Specific - No vague requirements
Complete - Covers all critical aspects
Organized - Features grouped by domain
Prioritized - Clear order of work
Testable - Every requirement can be verified
Explicit - Tech stack fully specified
Scoped - Out of scope section prevents creep
Achievable - Success criteria are realistic
Well-Structured - Flat or hierarchical based on project size

Choosing the Right Structure:

Flat (PRODUCT.md or .claude/product/index.md): Start here for most projects
Hierarchical (.claude/product/domains/*/index.md): Migrate when you hit 15+ features or multiple team members

Remember: You can always start flat and migrate to hierarchical later. Feature numbering stays consistent (1.1, 2.1, etc.) regardless of structure.

Invest time in your product specification upfront, and agentful will reward you with autonomous development success.

Next Steps

Now that you have a great PRODUCT.md:

Start agentful - Begin autonomous development
Monitor Progress - Track completion
Handle Decisions - Answer when agentful asks
Validate Quality - Ensure all gates pass

Related Guides:

Team Adoption - Standardize PRODUCT.md across your team
Best Practices - More patterns for great specs
Troubleshooting - Fix PRODUCT.md related issues