prd-to-spec

prd-to-spec — 将 PRD 转换为技术规格说明

将产品需求文档（PRD）转换为详细的技术规格说明（SPEC），供工程师或 AI Agent 据此实现。PRD 说明要构建什么；SPEC 说明如何构建。

---

适用场景

• 已生成 /prd，需要衔接后续实现
• 希望在开始编码前记录架构决策
• 多名开发者/Agent 将共同实现该功能，需要共享的约定
• 需要在确定 PRD 前验证技术可行性
• 希望尽早发现设计问题——在编写代码之前

---

工作内容

1. 定位 PRD — 查找或接收 PRD 文档
2. 分析上下文（可选） — 如果存在代码库，则扫描代码库以了解当前架构、模式和限制
3. 提出澄清问题 — 解决技术上的模糊之处（最多 3-5 个问题）
4. 生成 SPEC — 生成结构化的技术规格说明
5. 审查 — 提交给用户反馈并迭代
6. 保存 — 将最终 SPEC 写入约定的位置

---

第 1 步：定位 PRD

通过以下方式之一查找输入 PRD：

Provide the PRD to convert:

A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste PRD content directly
D. Auto-detect: scan tasks/ directory for recent PRDs

如果自动检测，则列出可用的 PRD 并让用户选择：

Found PRDs in tasks/:
  1. tasks/prd-priority-system.md (2024-03-15)
  2. tasks/prd-user-auth.md (2024-03-10)

Which PRD should I convert? [1/2]

---

第 2 步：分析上下文（可选）

如果尚不存在代码库（全新项目），则跳过此步骤。 在这种情况下，SPEC 将根据 PRD 要求和澄清问题，从头提出架构方案。

如果存在代码库，则扫描代码库以了解：

• 现有架构 — 当前系统的组织结构
• 技术栈 — 已在使用的语言、框架和库
• 模式 — 命名约定、文件组织方式、错误处理方法
• 数据库 — 当前架构、迁移工具、ORM
• API 风格 — REST/GraphQL/gRPC、身份验证方式、响应格式
• 测试 — 测试框架、覆盖率模式、测试工具

这样可以确保 SPEC 与现有系统保持一致，而不是提出不兼容的方案。

---

第 3 步：澄清问题

仅当 PRD 中的技术决策存在模糊之处时才提问。重点关注：

• 架构选择 — 此功能应该放在哪里？新建服务还是扩展现有服务？
• 数据存储 — 新建表？扩展现有表？缓存策略？
• API 设计 — 新建端点？扩展现有端点？是否有破坏性变更？
• 依赖项 — 是否需要新的库？版本限制是什么？
• 性能 — 预期负载是多少？延迟要求是什么？批次大小限制是什么？

格式：

Technical questions before I generate the SPEC:

1. Where should the priority logic live?
   A. Extend existing TaskService
   B. New PriorityService
   C. Inline in controller
   D. Let me decide based on the codebase

2. Database migration approach?
   A. Add column to existing tasks table
   B. New priority table with FK
   C. JSON field on tasks
   D. Let me decide based on current schema

3. API versioning concern?
   A. Add to existing v1 endpoints
   B. New v2 endpoints
   C. No versioning needed

如果用户选择“由我决定”选项，则根据代码库分析做出最佳选择，并在 SPEC 中记录理由。

---

第 4 步：SPEC 文档结构

# SPEC: [Feature Name]

> Technical specification derived from: [PRD filename/link]
> Generated: [date] | Target branch: [branch] | Commit: [short-hash]

## 1. Summary

### 1.1 What This SPEC Covers
[One paragraph: what feature this specifies and the scope of implementation]

### 1.2 PRD Reference
- Source: [path or URL to PRD]
- User Stories covered: [US-001, US-002, ...]
- Functional Requirements covered: [FR-1, FR-2, ...]

### 1.3 Design Decisions Summary
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |

---

## 2. Architecture

### 2.1 System Context
[Where this feature fits in the overall system — diagram or description]

### 2.2 Component Design
[New components/modules introduced, their responsibilities, and boundaries]

### 2.3 Module Interactions
[How new components interact with existing ones — sequence or data flow]

### 2.4 File Structure
[New files to create and existing files to modify]

src/ ├── services/ │ └── priority.service.ts [NEW] ├── controllers/ │ └── task.controller.ts [MODIFY: add priority endpoints] ├── models/ │ └── priority.model.ts [NEW] └── migrations/ └── 20240315_add_priority.ts [NEW]

---

## 3. Data Model

### 3.1 Schema Changes
[New tables, columns, indexes — with SQL or ORM notation]

### 3.2 Entity Definitions
[TypeScript interfaces / Go structs / Python dataclasses for new entities]

### 3.3 Relationships
[How new entities relate to existing ones — FK, embedded, reference]

### 3.4 Migration Plan
[Migration steps, backward compatibility, rollback strategy]

---

## 4. API Design

### 4.1 Endpoints

| Method | Path | Description | Auth | Request | Response |
|--------|------|-------------|------|---------|----------|
| ... | ... | ... | ... | ... | ... |

### 4.2 Request/Response Schemas
[Detailed shapes with field types, validation rules, and examples]

### 4.3 Error Responses
[Error codes, messages, and HTTP status codes for each failure mode]

### 4.4 Breaking Changes
[Any backward-incompatible changes and migration path for consumers]

---

## 5. Business Logic

### 5.1 Core Algorithms
[Step-by-step logic for key operations — pseudocode or structured description]

### 5.2 Validation Rules
[Input validation, business rule validation, with specific constraints]

### 5.3 State Machine
[If applicable: states, transitions, guards, and side effects]

### 5.4 Edge Cases
[Known edge cases and how they should be handled]

---

## 6. Error Handling

### 6.1 Error Taxonomy
| Error Code | HTTP Status | Condition | User Message |
|------------|-------------|-----------|--------------|
| ... | ... | ... | ... |

### 6.2 Retry Strategy
[Which operations are retryable, backoff policy, max attempts]

### 6.3 Failure Modes
[What happens when dependencies fail — graceful degradation plan]

---

## 7. Security

### 7.1 Authentication & Authorization
[Who can access what, permission model, role checks]

### 7.2 Input Validation
[Sanitization rules, injection prevention, size limits]

### 7.3 Data Protection
[Sensitive fields, encryption at rest/transit, audit logging]

---

## 8. Performance

### 8.1 Expected Load
[Estimated QPS, data volume, growth projection]

### 8.2 Optimization Strategy
[Caching, pagination, lazy loading, batch processing]

### 8.3 Database Considerations
[Index strategy, query patterns, N+1 prevention]

---

## 9. Testing Strategy

### 9.1 Unit Tests
[What to test, test boundaries, mock strategy]

### 9.2 Integration Tests
[API tests, database tests, service interaction tests]

### 9.3 Edge Case Tests
[Specific scenarios to cover based on Section 5.4]

### 9.4 Acceptance Criteria Mapping
| US/FR | Test | Type | Description |
|-------|------|------|-------------|
| US-001 | ... | unit | ... |
| FR-2 | ... | integration | ... |

---

## 10. Implementation Plan

### 10.1 Phases
[Order of implementation — what to build first, dependencies between steps]

### 10.2 Issue Mapping
[Map SPEC sections to PRD Issues for implementation tracking]

| Issue | SPEC Sections | Priority | Depends On |
|-------|--------------|----------|------------|
| #1 | 3.1, 3.4 | high | — |
| #2 | 4.1, 4.2, 5.1 | high | #1 |
| ... | ... | ... | ... |

### 10.3 Incremental Delivery
[How to ship incrementally — feature flags, dark launches, gradual rollout]

---

## 11. Open Questions & Risks

### 11.1 Unresolved Questions
- [Questions that need product/engineering input before implementation]

### 11.2 Technical Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
| ... | ... | ... |

### 11.3 Assumptions
- [Technical assumptions made during SPEC creation — validate before implementing]

---

第 5 步：审查与迭代

生成 SPEC 后，展示给用户并询问：

SPEC generated from PRD. Please review:

- Are the architecture choices appropriate?
- Are there missing edge cases or error scenarios?
- Is the API design consistent with existing patterns?
- Should any section have more/less detail?

Reply OK to save, or provide feedback for iteration.

---

第 6 步：保存

询问用户保存位置：

Where should I save the SPEC?

A. tasks/spec-[feature-name].md (alongside PRD, recommended)
B. docs/spec-[feature-name].md
C. Custom path: [specify]

---

映射策略：PRD → SPEC

PRD 中的内容如何转换为 SPEC 章节：

PRD 章节	SPEC 章节	转换方式
用户故事	5. 业务逻辑、9.4 验收映射	将故事转换为算法和测试用例
功能需求	4. API 设计、5. 业务逻辑	将功能需求转换为端点和逻辑
验收标准	9. 测试策略	将标准转换为具体测试场景
非目标	11.1 未解决问题	明确哪些内容明确排除在外
技术考量	2. 架构、8. 性能	将限制转换为设计决策
成功指标	8.1 预期负载、10.3 交付	将指标转换为监控和发布计划

---

质量标准

优秀的 SPEC 应通过以下检查：

• 每个 PRD 用户故事都有对应的 SPEC 章节
• 每项功能需求都映射到一个 API 端点或业务逻辑规则
• 每项验收标准都映射到至少一个测试用例
• 架构选择都有理由支持
• API 架构足够具体，可以生成客户端代码
• 错误处理涵盖所有已识别的故障模式
• 实施顺序符合依赖关系
• 没有“TBD”或“TODO”事项——解决它们或将其移至待解决问题

---

边缘情况与回退方案

场景	处理方式
PRD 含糊不清或不完整	尽最大努力生成 SPEC，并在第 11.3 节中标明假设
PRD 与现有代码冲突	明确指出冲突，并在第 11.1 节中提出解决方案
功能过于庞大，无法用一份 SPEC 描述	拆分为多份 SPEC（每个服务边界一份），并相互链接
不存在现有代码库（从零开始）	跳过步骤 2，根据 PRD 和澄清问题从头提出架构方案
PRD 没有用户故事（只有项目符号）	推断其结构，将项目符号映射到 SPEC 章节，并在摘要中注明
用户希望不阅读代码库就编写 SPEC	跳过步骤 2，并注明关于现有代码的假设尚未验证
多份 PRD 需要合并成一份 SPEC	合并 PRD 输入，去重需求，并注明每项需求的来源

---

应避免的反模式

• 不要复述 PRD。 SPEC 应补充技术细节，而不是换种说法复制需求。
• 不要过度详细地描述简单操作。 不含特殊逻辑的 CRUD 无需完整的算法章节。
• 不要脱离上下文选择技术。 提出新工具前，务必先检查项目当前使用的技术。
• 不要孤立地设计。 SPEC 必须适配现有系统——使用相同的模式、约定和风格。
• 不要让决策不言自明。 如果你做出了选择（例如“向现有表添加列”），应说明选择内容及原因。
• 不要编写实现代码。 SPEC 描述的是契约和行为，而非代码。对于复杂算法，可以使用伪代码。

---

与其他技能的关系

/prd  →  /prd-to-spec  →  /goal  →  /review-it  →  /ship-it
 │              │              │
 │  Requirements │  Technical   │  Implementation
 │  (what)       │  (how)       │  (code)

• /prd 生成 PRD（此技能的输入）
• /prd-to-spec 生成 SPEC（此技能）
• /goal 以 SPEC 为技术参考，实现 Issues
• /code-to-spec 根据现有代码逆向工程生成 SPEC（互为补充——正向与逆向）