prd-authoring（PRD 创作）

PRD Authoring

This skill provides comprehensive guidance for creating high-quality Product Requirement Documents (PRDs) that include:

• Complete technical specifications
• Actionable task lists with priorities
• Relevant code snippets and examples
• Clear implementation phases
• Measurable success criteria

<quality_standards>

What Makes a Good PRD

A good PRD MUST be:

• Actionable: Each requirement can be implemented directly
• Complete: Covers functional, non-functional, and technical requirements
• Specific: Uses precise language, avoiding vague terms like "should" or "might"
• Measurable: Includes success metrics that can be quantified
• Implementable: Contains sufficient detail for engineering to build

Required Elements

Every PRD MUST include:

1. Problem Statement - Clear articulation of what problem we're solving and why
2. Goals - Specific, measurable objectives
3. Requirements - Functional and non-functional requirements
4. Architecture - System design, components, data flow
5. Implementation Plan - Phased approach with milestones
6. Task List - Actionable next steps (see template below)
7. Success Metrics - Quantifiable measures of success
8. Code Snippets - Relevant examples (see guidelines below)

</quality_standards>

<prd_template>

PRD Template

# [Feature Name] - PRD

## Overview
[2-3 sentence summary]

## Problem Statement
[What problem are we solving? Why now? What's the impact of not solving it?]

## Goals
- [ ] [Primary goal 1 - specific and measurable]
- [ ] [Primary goal 2 - specific and measurable]
- [ ] [Secondary goal 3]

## Non-Goals
[What we explicitly will NOT do in this iteration - sets scope boundaries]

## Requirements

### Functional Requirements
- [FR-1] [User stories/use cases as specific requirements]
- [FR-2] [Acceptance criteria for each requirement]

### Non-Functional Requirements
- [NFR-1] **Performance**: [specific metrics, e.g., "API responds in <200ms at p95"]
- [NFR-2] **Security**: [e.g., "All data encrypted at rest and in transit"]
- [NFR-3] **Scalability**: [e.g., "System handles 10k concurrent users"]
- [NFR-4] **Reliability**: [e.g., "99.9% uptime SLA"]

### Technical Requirements
- [TR-1] [Technology stack constraints]
- [TR-2] [Integration requirements]
- [TR-3] [Data retention/compliance requirements]

## Proposed Architecture

### System Design
[High-level architecture - use text diagrams or mermaid]

[Component A] ←→ [Component B] ←→ [Component C] ↓ ↓ ↓ [Database] [Cache Layer] [External API]

### Component Breakdown
- **Component A**: [Responsibility, technology choice, scaling approach]
- **Component B**: [Responsibility, technology choice, scaling approach]
- **Component C**: [Responsibility, technology choice, scaling approach]

### Data Flow
1. [Step-by-step description of how data moves through the system]
2. [Include error handling, retries, fallbacks]
3. [Describe async/sync boundaries]

### API Design (if applicable)
[Include endpoint specifications, request/response schemas]

## Technical Considerations

### Technology Choices
| Technology | Justification | Alternatives Considered |
|------------|---------------|-------------------------|
| [Tech 1]   | [Why this choice] | [Alternative 1, Alternative 2] |
| [Tech 2]   | [Why this choice] | [Alternative 1, Alternative 2] |

### Trade-offs Analyzed
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| [Option A] | ... | ... | ✅/❌ |
| [Option B] | ... | ... | ✅/❌ |

### Risks and Mitigations
| Risk | Impact | Probability | Mitigation Strategy |
|------|--------|-------------|---------------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [How to address] |
| [Risk 2] | High/Med/Low | High/Med/Low | [How to address] |

## Implementation Strategy

### Phase 1: Foundation
- [ ] [Task 1.1]
- [ ] [Task 1.2]
- [ ] [Task 1.3]

**Definition of Done**: [Specific criteria for phase completion]

### Phase 2: Core Features
- [ ] [Task 2.1]
- [ ] [Task 2.2]
- [ ] [Task 2.3]

**Definition of Done**: [Specific criteria for phase completion]

### Phase 3: Polish & Launch
- [ ] [Task 3.1]
- [ ] [Task 3.2]
- [ ] [Task 3.3]

**Definition of Done**: [Specific criteria for phase completion]

## Task Breakdown

<task_list_template>
### High Priority (P0) - Blockers for launch
- [ ] **[TASK-1]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]

### Medium Priority (P1) - Important but not blocking
- [ ] **[TASK-2]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]

### Low Priority (P2) - Nice to have
- [ ] **[TASK-3]**: [Actionable task title]
  - Complexity: [Simple/Medium/Complex]
  - Dependencies: [Task IDs or components that must exist first]
  - Parallelizable: [Yes/No - if Yes, specify which tasks can run simultaneously]
  - Testing: [Required/Recommended/None - specify type: unit, integration, e2e]
  - Acceptance criteria: [Specific, testable criteria]
</task_list_template>

<parallelization_guidance>

### Task Parallelization

Mark tasks as **Parallelizable: Yes** when:
- Task is independent of other in-progress tasks
- Multiple developers/subagents can work on different aspects simultaneously
- Task can be split into independent sub-tasks

**Examples:**

✅ **Parallelizable**
- "Design REST API endpoints" and "Design database schema" - can be done simultaneously with coordination
- "Write frontend user profile component" and "Write frontend settings component" - independent components
- "Set up CI/CD pipeline" and "Set up monitoring infrastructure" - separate infrastructure tasks

❌ **Not Parallelizable**
- "Implement authentication" - blocks on "Design database schema" (dependency)
- "Write API tests" - requires API endpoints to exist first (dependency)

**Format for parallelizable tasks:**

• Parallelizable: Yes - Can run concurrently with [TASK-X], [TASK-Y]

</parallelization_guidance>

<complexity_guidance>

### Task Complexity Levels

**Simple**

- Well-defined scope
- No unknown unknowns
- Follows established patterns
- Single system/component
- Example: "Add email validation to registration form"

**Medium**

- Some research or investigation needed
- Multiple components to integrate
- Requires decision-making
- Some ambiguity to resolve
- Example: "Implement OAuth 2.0 login with Google and GitHub"

**Complex**

- Significant architectural decisions
- Cross-system dependencies
- High ambiguity or research required
- Performance or security concerns
- Requires prototyping or spikes
- Example: "Design and implement real-time notification system with WebSocket scaling"

</complexity_guidance>

<testing_guidance>

### Testing Requirements

Each task MUST specify testing needs:

**Required** - Critical functionality, MUST have tests before merging

- User authentication/authorization
- Payment processing
- Data persistence operations
- External API integrations

**Recommended** - Should have tests but not blocking

- UI components
- Business logic validation
- Edge case handling
- Error scenarios

**None** - Tests not applicable

- Configuration changes
- Documentation updates
- Infrastructure setup
- Design/mockup tasks

**Test Types:**

- `unit` - Individual functions/components in isolation
- `integration` - Multiple components working together
- `e2e` - Full user flows from start to finish
- `performance` - Load testing, benchmarks
- `security` - Penetration testing, vulnerability scans

</testing_guidance>

## Success Metrics

- [Metric 1]: [Current value] → [Target value]
- [Metric 2]: [Current value] → [Target value]
- [Metric 3]: [Current value] → [Target value]

## Open Questions

- [Q1] [Question that needs resolution]
  - Options: [Option A, Option B, Option C]
  - Decision owner: [Who will decide]

## Appendices

### Code Snippets

[Include relevant code examples - see guidelines below]

### Data Schemas

[Include database schemas, type definitions, etc.]

### Mockups

[Links to UI mockups or wireframes]

</prd_template>

<code_snippet_guidelines>

When to Include Code Snippets

PRDs SHOULD include code snippets when they clarify technical details. Use for:

1. API Design

Include when: Defining endpoints, request/response formats

// POST /api/users
interface CreateUserRequest {
  email: string;
  password: string; // Hashed with bcrypt
  name: string;
}

interface CreateUserResponse {
  id: string;
  email: string;
  createdAt: Date;
}

2. Data Schemas

Include when: Defining database models, type definitions

// User schema
interface User {
  id: string; // UUID
  email: string; // Unique, indexed
  passwordHash: string; // bcrypt
  createdAt: Date;
  updatedAt: Date;
}

// Indexes
db.users.createIndex({ email: 1 }, { unique: true });

3. Configuration Examples

Include when: Defining feature flags, environment variables

# Environment variables
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret-key
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=100

4. Algorithm Examples

Include when: Explaining complex logic

// Rate limiting algorithm
function rateLimit(userId: string): boolean {
  const requests = redis.get(`ratelimit:${userId}`) || 0;
  if (requests >= LIMIT) {
    return false; // Rate limited
  }
  redis.incr(`ratelimit:${userId}`);
  redis.expire(`ratelimit:${userId}`, 60);
  return true; // Allowed
}

5. Integration Examples

Include when: Showing how components interact

// Example: Service A calling Service B
const response = await fetch('http://service-b/api/process', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: payload })
});

What NOT to Include

❌ Full implementation code - PRDs are for requirements, not implementation ❌ Business logic details - Save for actual development ❌ Boilerplate code - Unless it's configuration

✅ DO include: Interfaces, schemas, examples of architecture ✅ DO include: Configuration, API contracts, data models

</code_snippet_guidelines>

<task_list_guidelines>

Creating Actionable Task Lists

Tasks in PRDs MUST be:

Specific

❌ "Implement user authentication" ✅ "Implement OAuth 2.0 login with Google and GitHub providers"

Testable

❌ "Make it fast" ✅ "API response time <200ms at p95 under 1000 RPS"

Atomic

❌ "Build the entire checkout flow" ✅ "Build cart summary endpoint" (one of many tasks)

Testable

Each task MUST specify testing requirements (Required/Recommended/None)

Task Template (AI-Agent Optimized)

- [ ] **[TASK-ID]** [Actionable title]
  - **Complexity**: [Simple/Medium/Complex]
  - **Dependencies**: [Task IDs or components that must exist first]
  - **Parallelizable**: [Yes/No - if Yes, specify which tasks]
  - **Testing**: [Required/Recommended/None - specify type: unit, integration, e2e]
  - **Acceptance Criteria**:
    - [ ] [Criterion 1 - must be testable]
    - [ ] [Criterion 2 - must be testable]

</task_list_guidelines>

<anti_patterns>

Common PRD Anti-Patterns

Vague Language

❌ "The system should be scalable" ✅ "System must handle 10,000 concurrent users with <500ms response time"

Missing Acceptance Criteria

❌ "Implement search functionality" ✅ "Implement full-text search with filters, returning results in <100ms, supporting 100+ concurrent searches"

No Success Metrics

❌ "Improve user engagement" ✅ "Increase daily active users from 1,000 to 2,000 within 90 days"

Infinite Scope

❌ "Build the best e-commerce platform" ✅ "Build MVP with product catalog, cart, and checkout (payments via Stripe)"

Missing Technical Details

❌ "Use a database" ✅ "Use PostgreSQL for relational data, Redis for caching, with proper indexing on email and product_id"

No Risk Assessment

❌ [No risk section] ✅ [Include risks table with mitigations]

</anti_patterns>

PRD Authoring Workflow

1. Understand the Problem

- Interview stakeholders if needed - Identify pain points with current solution - Quantify the opportunity

1. Draft Requirements

- Start with user stories - Convert to functional requirements (FR-1, FR-2, etc.) - Add non-functional requirements (NFR-1, NFR-2, etc.)

1. Design Architecture

- Create system diagram - Define components and their responsibilities - Map data flow between components

1. Add Technical Details

- Choose technologies with justification - Document trade-offs - Include relevant code snippets

1. Create Task Breakdown

- Break into phases - Create specific, actionable tasks - Identify dependencies

1. Define Success

- Set measurable metrics - Define baseline and target

1. Review and Refine

- Check against quality standards - Ensure no anti-patterns - Validate with stakeholders

See references/examples.md for complete PRD examples.