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:

PRD (Persistent) → Specification (Temporary) → Implementation → 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

A specification guides implementation RIGHT NOW. Once implemented + tested → spec's job is done:

• Behavior captured in code
• API contract in API schema
• Business context in PRD

Archive after implementation:

git mv specs/task-tags/specification.md specs/_archive/2024-01-task-tags-spec.md

If feature needs modification later:

1. Start from PRD (business requirements still current?)
2. Generate NEW specification (fresh guide)
3. Don't try to "update" old specification

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

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

Only when explicitly directed:

Human: "Read docs/prds/task-tags-v1.0.md to understand 
the original business requirements before we modify this."

Typical workflow (PRD not involved):

1. Human: "Add pagination to task list endpoint"
2. Agent reads: OpenAPI, CLAUDE.md, code (current state)
3. Agent generates specification and implements
4. Agent never browsed PRD folder

Think of PRDs as blueprints: Once the house is built, you tour the house (code), not old blueprints.

PRD says (high-level):

## 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):

## 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:

This distinction is critical for AI-assisted development.

Definition: Agent can verify BEFORE merging code.

## Verification Criteria

**Tests:**
- ✅ User can create tag → test passes
- ✅ Invalid tag rejected → test passes
- ✅ Tag filtering <200ms → benchmark measures 45ms
- ✅ Coverage ≥90% → achieved 94%

Definition: Measured AFTER deployment based on user behavior.

## Success Metrics (Post-Deployment)

Measured after release, inform future iterations:
- Target: 70% of users create 3+ tags within first week
- Measured via: Analytics dashboard
- Review date: 2 weeks after launch

Note: NOT verification criteria. Product analytics goals.

❌ BAD (in Specification - agent can't verify):

- 70% of users adopt tags within first week

✅ GOOD (in Specification):

- Test: Tag creation succeeds with valid name → passes
- Performance: Tag API responds <100ms → measured at 45ms

✅ GOOD (in PRD):

- Target: 70% user adoption within first week (analytics, post-deployment)

Template:

# 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

PRDs change only when fundamental business requirements evolve.

Example:

v1.0: Tasks have priority 1-5 (numeric)
Problem discovered: 68% of users confused by numeric scale

v2.0 PRD:

# PRD: Task Priority (Revised)

**Version:** 2.0  
**Status:** ✅ Implemented  
**Supersedes:** v1.0

## Problem This Update Solves
User research showed numeric priority confused 68% of users.
This update replaces 1-5 scale with self-explanatory enum.

## Requirements
- Priority field: enum low/medium/high
- Migration: 1-2→high, 3→medium, 4-5→low

The Process:

1. Human provides informal requirements (1-2 paragraphs)
2. Claude analyzes codebase (models, API patterns, CLAUDE.md)
3. Claude generates architecture-aware PRD (references actual code)
4. Human reviews for business accuracy (right problem? feasible constraints?)
5. Claude refines based on feedback
6. Approved PRD → input for specification generation

"Architecture-aware" does not mean "implementation-detailed." The PRD notes that a feature integrates with existing systems (e.g., "extends the Task entity," "uses existing auth") - it does NOT define exact schemas, API contracts, migrations, or step-by-step implementation plans. Those belong in the specification or technical plan.

Important: Once approved and implemented, PRD lives in Git as historical record. Agents won't browse it unless human explicitly directs them to.

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

Header and Metadata:

# 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:

## 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:

## 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:

**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):

## 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:

## 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:

## 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.

Key Concepts:

• Specification lifecycle: PRD (persistent) → Spec (temporary) → Implementation → Archive Spec
• PRDs are for humans: Historical records, not agent discovery docs
• What agents read: API Schema, CLAUDE.md, Code, ADRs (PRDs only when human directs)
• PRD structure: Status field, past-tense problems, post-deployment metrics clearly marked
• Verification vs Success: Agent verifies before merge → Verification. Need real users → Success metric
• PRD versioning: Rare - only when business requirements fundamentally change
• Architecture-aware ≠ implementation-detailed: PRDs reference what a feature integrates with (existing entities, patterns, systems) - not exact schemas, API contracts, or migrations. Those live in the specification.

Key Mental Models:

1. PRDs are blueprints: Tour the house (code), not blueprints
2. Specifications are scaffolding: Removed after construction
3. Verification vs Success: Can agent test now? → Verification. Need users? → Success metric

Next: Practice tasks where you'll:

1. Analyze PRD vs Specification differences
2. Generate architecture-aware PRDs
3. Distinguish verification criteria from success metrics
4. Review PRDs for business accuracy

This establishes the persistent documentation layer that feeds specification work!