Many teams write detailed specifications, implement features, and then struggle to maintain those specifications forever. This creates specification debt—outdated documentation that drifts from reality.

This lesson introduces a better mental model: specifications are temporary implementation guides, while product requirements documents (PRDs) persist as business context. Understanding this distinction prevents documentation debt and keeps your development process lightweight.

The correct mental model treats different documentation types according to their purpose and lifetime.

PRD (Persistent) → Specification (Temporary) → Implementation → Archive Spec

What persists in your codebase:

• Product requirements document: Business requirements and rationale (lives in docs/prds/)
• CODEX.md: Project constitution
• ADRs: Architecture decisions (immutable records)
• API schema: API contracts
• Code + Tests: Executable implementation

What serves temporarily:

• Specification: Implementation guide (archived after use)
• Technical plan: Implementation approach
• Task list: Execution checklist

This separation prevents the common mistake of treating all documentation as equally permanent.

A specification guides implementation right now. Once you've implemented and tested the feature, the specification has served its purpose. The actual behavior now lives in code, the API contract exists in the API schema, and the business context remains in the PRD.

After implementation completes, archive the specification:

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

When modifying a feature later, don't try to "update" an old specification. Instead, follow this workflow:

1. Start from the PRD—are business requirements still current?
2. Generate a new specification—a fresh implementation guide
3. Implement and archive the new specification

Specifications are like scaffolding: essential during construction, but removed once the building stands.

A PRD defines the WHAT and WHY at the business level. It explains what problem you're solving and why it matters to users or the business.

A PRD contains:

• Problem statement: What problem does this solve?
• Users and personas
• Functional requirements
• Constraints: Technical, business, and performance
• Success metrics: Post-deployment analytics goals
• Out of scope: What you're deliberately not building

The PRD is written for product managers, stakeholders, developers, and future team members. It provides business context that helps people understand why features exist without reverse-engineering intent from code.

A PRD is not: As detailed as a specification, an implementation guide, or runtime reference documentation.

PRDs serve as organizational memory, documenting the business context and requirements that led to implementation decisions. When a new team member asks "why does this feature work this way?", the PRD provides that answer.

However, PRDs are not active development documentation. When working on existing features, developers and AI tools reference the actual implementation—code, tests, and API schemas—rather than historical requirements documents.

Think of PRDs as architectural blueprints. Once the house is built, you tour the actual house (code), not the old blueprints. Blueprints matter when planning major renovations or understanding original design intent, but daily living happens in the actual structure.

Different documents serve different purposes in AI-assisted development. Understanding when to consult each type keeps development efficient.

Think of documentation as three layers:

• Active layer (API schema, CODEX.md, code): What the system does now
• Decision layer (ADRs): Why the architecture evolved this way
• Context layer (PRDs): What business problems features solve

The active layer guides daily development. The context layer provides historical understanding when needed, but isn't consulted during normal feature work.

PRDs provide value when understanding business context becomes necessary, but they're not part of the normal development workflow.

Typical scenarios for consulting PRDs:

• Major feature modifications that might affect original requirements
• Investigating whether current behavior matches intended business goals
• Onboarding new team members who need business context
• Evaluating whether new feature requests align with existing capabilities

Normal development workflow (PRD not consulted):

A developer identifies a task like "Add pagination to task list endpoint." They reference the current state—OpenAPI schema, CODEX.md, and existing code. They generate a specification and implement it. The PRD folder is not consulted because the developer is working from the current implementation.

This workflow keeps development focused on current reality rather than historical documents.

Understanding the difference between PRDs and specifications prevents documentation confusion. They serve completely different purposes.

PRD example (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 example (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:

The PRD explains why you need tags. The specification explains exactly how to build them.

This distinction is critical for AI-assisted development. Mixing these concepts creates confusion about when a feature is "done."

Verification criteria can be verified BEFORE merging the code. These are technical measurements you can make during development.

## Verification Criteria

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

Each criterion has a clear pass/fail condition. You run tests, measure performance, and verify coverage—all before deployment.

Success metrics measure AFTER deployment based on actual user behavior. These require real users over time.

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

You cannot verify these during development. They require deployment, user adoption, and time to measure accurately.

Bad example (in Specification—cannot be verified during development):

- 70% of users adopt tags within the first week

This belongs in the PRD as a post-deployment success metric.

Good example (in Specification):

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

These can be verified before merging.

Good example (in PRD):

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

Clearly marked as an analytics goal that requires real usage data.

A well-structured PRD makes business requirements clear without diving into implementation details.

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]
- 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 for PRD content:

Include in the PRD:

• Business problem in past/neutral tense
• Functional requirements describing what the system must do
• Post-deployment success metrics clearly marked

Include in the specification (not the PRD):

• Exact API contracts
• Validation rules with regex
• Test cases that can be executed
• Performance benchmarks to hit before merge

Don't include (or mark as post-deployment):

• User adoption rates (cannot verify during development)
• Long-term engagement metrics (requires time + real users)
• Business KPIs dependent on user behavior

These boundaries keep each document focused on its purpose.

PRDs change only when fundamental business requirements evolve. This happens rarely compared to code changes.

Example scenario:

v1.0: Tasks have priority 1-5 (numeric). Problem discovered: 68% of users were confused by the 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 new version documents why requirements changed and supersedes the old version without deleting it.

AI tools can help generate architecture-aware PRDs that align with your existing codebase and standards, reducing the burden of documentation work.

The conceptual workflow:

1. A human provides informal requirements (1-2 paragraphs describing the business need)
2. The AI analyzes codebase context (existing models, API patterns, CODEX.md standards)
3. The AI generates an architecture-aware PRD (references actual code structure, follows project patterns)
4. The human reviews for business accuracy (validates it solves the right problem with feasible constraints)
5. Iterative refinement (AI adjusts based on human feedback)
6. The approved PRD becomes input for specification generation

Why this approach works:

AI tools understand your existing architecture, naming conventions, and technical patterns. Generated PRDs naturally reference your actual file structure, follow established patterns, and identify realistic integration points.

The human validates business logic—ensuring the PRD solves the right problem and sets feasible constraints. The AI ensures technical consistency with existing architecture.

Once approved and implemented, PRDs live in Git as historical records documenting why features exist, not how they currently work.

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

The 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 the past/neutral tense ("needed") instead of "currently broken." The PRD documents what problem existed, not the 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 and per-user
4. Users can filter tasks by tags
5. Users can list tags with usage counts

Business requirements at a high level. A specification would detail the exact regex, API endpoints, and error codes.

Constraints:

## Constraints

**Technical:**
- Extends Task model (src/models/task.py)
- Follows repository pattern (CODEX.md)
- JWT auth via get_current_user

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

This references actual codebase structure. Architecture-aware documentation connects business requirements to real implementation touchpoints, helping developers understand where changes need to occur.

Success metrics:

## Success Metrics (Post-Deployment)

Measured after release, these inform v2.0:
- Target: 70% of users create 3+ tags within the 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 that cannot be verified during development. These require 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

This prevents scope creep and documents what you're deliberately not building.

Integration notes:

## Integration

- New tables: `tags`, `task_tags`
- Testing: 90%+ coverage per CODEX.md
- Migration: Alembic following existing patterns

Technical touchpoints that the specification expands into detailed API contracts and test cases.

Documentation usage in practice:

When implementing new features, developers start with the PRD to understand business requirements, then generate detailed specifications for implementation. When modifying existing features, developers work from the current implementation (code, tests, API schemas) since these reflect actual system state. The PRD remains available for understanding original business context when needed.

This lesson established how PRDs fit into the specification lifecycle. PRDs persist as business context while specifications serve temporarily to guide implementation.

Core concepts:

• Specification lifecycle: PRD (persistent) → Specification (temporary) → Implementation → Archive spec
• Documentation hierarchy: API schema, CODEX.md, and code/tests for active development; PRDs for business context
• PRD structure: Status field, past-tense problems, post-deployment metrics clearly marked
• Verification vs success: Can it be tested before deployment? Verification. Does it require real users? Success metric
• PRD versioning: Rare—only when business requirements fundamentally change

Mental models to remember:

1. PRDs are blueprints: Tour the house (code), not the blueprints
2. Specifications are scaffolding: Removed after construction
3. Verification vs success: Can it be tested now? Verification. Do you need users? Success metric
4. Documentation layers: Active (current state) vs context (business rationale)

Next, you'll practice analyzing PRD vs specification differences, generating architecture-aware PRDs, distinguishing verification criteria from success metrics, and reviewing PRDs for business accuracy. This establishes the persistent documentation layer that feeds specification work.