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.

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:

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

Specification example (precise):

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.

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.

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

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

Good example (in Specification):

These can be verified before merging.

Good example (in PRD):

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:

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:

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:

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

Problem statement:

Notice the past/neutral tense ("needed") instead of "currently broken." The PRD documents what problem existed, not the current system state.

Functional requirements:

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

Constraints:

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:

Clearly marked as analytics goals that cannot be verified during development. These require real users over time.

Scope boundaries:

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

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.