PRD as Persistent Documentation

The Specification Lifecycle Problem

Many teams write detailed specifications, implement features, then try to "maintain" those specifications forever. This creates specification debt - outdated docs that drift from reality. The correct mental model: text PRD (Persistent) \to Specification (Temporary) \to Implementation \to Archive Spec What persists: 📋 PRD - Business requirements and rationale (lives in docs/prds/) 🏗️ CLAUDE.md - Project constitution 📐 ADRs - Architecture decisions (immutable records) 📖 API Schema - API contracts 💻 Code + Tests - Executable implementation What's temporary: 📝 Specification - Implementation guide (archived after use) 🔧 Technical Plan - Implementation approach ✅ Task List - Execution checklist

Why Specifications Are Temporary

A specification guides implementation RIGHT NOW . Once implemented + tested \to spec's job is done: Behavior captured in code API contract in API schema Business context in PRD Archive after implementation: Shell git mv specs/task-tags/specification.md specs/_archive/2024-01-task-tags-spec.md If feature needs modification later: Start from PRD (business requirements still current?) Generate NEW specification (fresh guide) Don't try to "update" old specification

What Is a PRD?

A Product Requirements Document defines WHAT and WHY at the business level. PRD contains: Problem statement (what problem does this solve?) Users and personas Functional requirements Constraints (technical, business, performance) Success metrics (post-deployment) Out of scope PRD is written for: Product managers, stakeholders, developers, future team members PRD is NOT: As detailed as specification, implementation guide, or runtime documentation for agents

PRDs Are For Humans, Not Agent Discovery

Critical distinction: PRDs are historical records for human reference, NOT documentation that agents browse during development.

What Agents Read to Understand the System

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

PRD vs Specification

Document	When Agent Reads
API Schema	Every API change
CLAUDE.md	Start of every session
Code + Tests	When modifying features
ADRs	When working on related code
PRDs	Only when human explicitly references it

PRD says (high-level):

Markdown

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Requirements
- Users can add/remove tags from tasks
- Maximum 10 tags per task
- Tags are alphanumeric strings with hyphens (1-30 chars)
- Users can filter tasks by tags

## Success Metrics (Post-Deployment)
- Target: 70% of active users create 3+ tags within first week
- Review date: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Requirements
- Users can add/remove tags from tasks
- Maximum 10 tags per task
- Tags are alphanumeric strings with hyphens (1-30 chars)
- Users can filter tasks by tags

## Success Metrics (Post-Deployment)
- Target: 70% of active users create 3+ tags within first week
- Review date: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

Specification says (precise):

Markdown

## API Contract

POST /api/tasks/{task_id}/tags
Request: { "name": "string" }  // Regex: ^[a-zA-Z0-9-]{1,30}$
Response (201): { "id": "uuid", "name": "string", ... }
Response (400): { "detail": "Tag name must be 1-30 alphanumeric..." }

## Verification Criteria (Must Pass Before Merge)

**Functional Tests:**
- ✅ User can add tag with valid name
- ✅ System rejects 11th tag (max 10 enforced)
- ✅ System rejects invalid characters
- ✅ Tag filter returns correct tasks

**Performance Tests:**
- ✅ Tag filtering <200ms for 1000 tasks
- ✅ Tag list query <50ms

**Coverage:**
- ✅ Test coverage ≥90%

## API Contract

POST /api/tasks/{task_id}/tags
Request: { "name": "string" }  // Regex: ^[a-zA-Z0-9-]{1,30}$
Response (201): { "id": "uuid", "name": "string", ... }
Response (400): { "detail": "Tag name must be 1-30 alphanumeric..." }

## Verification Criteria (Must Pass Before Merge)

**Functional Tests:**
- ✅ User can add tag with valid name
- ✅ System rejects 11th tag (max 10 enforced)
- ✅ System rejects invalid characters
- ✅ Tag filter returns correct tasks

**Performance Tests:**
- ✅ Tag filtering <200ms for 1000 tasks
- ✅ Tag list query <50ms

**Coverage:**
- ✅ Test coverage ≥90%

Key differences:

Aspect	PRD	Specification
Purpose	Business requirements	Implementation guide
Detail	High-level (WHAT/WHY)	Precise (HOW)
Lifetime	Persistent	Temporary
Metrics	Post-deployment analytics	Pre-merge verification
Agent Access	Only when human directs	Read during implementation

PRD Structure Best Practices

Template:

Markdown

# PRD: [Feature Name]

**Version:** [X.Y]  
**Status:** [📝 Draft | ✅ Implemented | 🔄 Superseded]  
**Created:** [Date]

## Problem This Feature Solves
[Past/neutral tense - "This feature adds..." not "Currently broken..."]

## Requirements
[Numbered functional requirements]

## Constraints
- Technical: [Integration points, patterns to follow - conceptual, not file paths]
- Business: [Rules, policies]
- Performance: [Specific targets]

## Success Metrics (Post-Deployment)
[Clearly marked as analytics goals, not verification criteria]
Review date: [When to assess]

## Out of Scope
[What we're NOT building in this version]

# PRD: [Feature Name]

**Version:** [X.Y]  
**Status:** [📝 Draft | ✅ Implemented | 🔄 Superseded]  
**Created:** [Date]

## Problem This Feature Solves
[Past/neutral tense - "This feature adds..." not "Currently broken..."]

## Requirements
[Numbered functional requirements]

## Constraints
- Technical: [Integration points, patterns to follow - conceptual, not file paths]
- Business: [Rules, policies]
- Performance: [Specific targets]

## Success Metrics (Post-Deployment)
[Clearly marked as analytics goals, not verification criteria]
Review date: [When to assess]

## Out of Scope
[What we're NOT building in this version]

Key Principles:

✅ DO include in PRD:

Business problem (past/neutral tense)
Functional requirements (what system must do)
High-level integration constraints (e.g., "extends existing Task entity," "uses existing auth system") - naming what it connects to, not how
Post-deployment success metrics (clearly marked)

✅ DO include in Specification (not PRD):

Exact API contracts and endpoints
Database schema, table names, and migrations
Validation rules with regex
Test cases agent can run
Performance benchmarks to hit before merge

❌ DON'T include (or mark as post-deployment):

User adoption rates (can't verify during dev)
Long-term engagement metrics (need time + real users)
Business KPIs dependent on user behavior

Example: Task Tags PRD (Structured)

Let's examine a real PRD section by section to understand how each part serves its purpose.

Header and Metadata:

Markdown

# PRD: Task Tags

**Version:** 1.0  
**Status:** ✅ Implemented (2024-01-28)  
**Created:** 2024-01-15

# PRD: Task Tags

**Version:** 1.0  
**Status:** ✅ Implemented (2024-01-28)  
**Created:** 2024-01-15

Status field immediately shows this PRD's lifecycle state. "Implemented" means we can reference it for historical context.

Problem Statement:

Markdown

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

Notice: Past/neutral tense ("needed"), not "currently broken." The PRD documents what problem existed, not current system state.

Functional Requirements:

Markdown

## Requirements

1. Users can add/remove tags (alphanumeric + hyphens, 1-30 chars)
2. Maximum 10 tags per task
3. Tags are case-insensitive, per-user
4. Users can filter tasks by tags
5. Users can list tags with usage counts

## Requirements

1. Users can add/remove tags (alphanumeric + hyphens, 1-30 chars)
2. Maximum 10 tags per task
3. Tags are case-insensitive, per-user
4. Users can filter tasks by tags
5. Users can list tags with usage counts

Business requirements at high level. Specification would detail exact regex, API endpoints, error codes.

Constraints:

Markdown

**Technical:**
- Extends the existing Task entity
- Follows established repository pattern (see CLAUDE.md)
- Uses existing authentication system

**Performance:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

**Technical:**
- Extends the existing Task entity
- Follows established repository pattern (see CLAUDE.md)
- Uses existing authentication system

**Performance:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

References existing architecture at a conceptual level - that this integrates with the Task entity, repository pattern, and auth system. It does NOT name exact files, classes, or functions - those specifics belong in the specification.

Success Metrics (Post-Deployment):

Markdown

## Success Metrics (Post-Deployment)

Measured after release, inform v2.0:
- Target: 70% of users create 3+ tags within first week
- Target: Tag filtering used in 50%+ of task views
- Review: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

## Success Metrics (Post-Deployment)

Measured after release, inform v2.0:
- Target: 70% of users create 3+ tags within first week
- Target: Tag filtering used in 50%+ of task views
- Review: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

Clearly marked as analytics goals. Agent can't verify these during development - needs real users over time.

Scope Boundaries:

Markdown

## Out of Scope

v1.0 does NOT include:
- Tag sharing between users (team tags in v2.0)
- Tag colors or visual customization
- Tag hierarchies

## Out of Scope

v1.0 does NOT include:
- Tag sharing between users (team tags in v2.0)
- Tag colors or visual customization
- Tag hierarchies

Prevents scope creep. Documents what we're deliberately NOT building.

Integration Notes:

Markdown

## Integration

- Requires new persistent storage for tags and their task associations
- Testing: 90%+ coverage per CLAUDE.md

## Integration

- Requires new persistent storage for tags and their task associations
- Testing: 90%+ coverage per CLAUDE.md

Technical touchpoints at a conceptual level only - that new storage is needed. Exact table names, schema design, and migration approach belong in the specification, not the PRD.

When implementing:

Human: "Read docs/prds/task-tags-v1.0.md and generate specification"
Agent generates specification (temporary)
Agent implements and tests
Specification archived
PRD persists (historical context)

When working on other features:

Agent reads OpenAPI (discovers tags API)
Agent reads code (understands implementation)
Agent does NOT browse PRD folder

Note: Complete PRD would exist as single file (docs/prds/task-tags-v1.0.md). Sections shown separately here for learning purposes.

The Specification Lifecycle Problem

Why Specifications Are Temporary

What Is a PRD?

PRDs Are For Humans, Not Agent Discovery

What Agents Read to Understand the System

Join the 1M+ learners on CodeSignal

When Agents DO Read PRDs

PRD vs Specification

Verification Criteria vs Success Metrics

Verification Criteria (Specification)

Success Metrics (PRD)

Examples

PRD Structure Best Practices

PRD Versioning (Rare)

AI-Assisted PRD Generation

Example: Task Tags PRD (Structured)

Summary