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

Example: Task Tags PRD (Structured)

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

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

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

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.

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

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

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.

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

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

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