有 PRD 但缺少技术设计时，用结构化 SPEC…

当已有 PRD 需要落地为工程师或 AI 可实现的技术规格时使用。

适用场景

解决思路

1. 按总流程执行：定位 PRD → 可选分析上下文 → 提出澄清问题 → 生成 SPEC → 审查迭代 → 保存。
2. 定位 PRD：支持 A. 文件路径（如 tasks/prd-priority-system.md）；B. GitHub Issue URL；C. 直接粘贴 PRD 内容；D. 自动扫描 tasks/ 目录中的近期 PRD。自动检测时列出可用 PRD 让用户选择，例如显示 tasks/prd-priority-system.md (2024-03-15) 和 tasks/prd-user-auth.md (2024-03-10)，再问选择哪个。
3. 可选分析代码库上下文：若已有代码库，扫描现有架构、技术栈、模式（命名约定、文件组织、错误处理方式）、数据库（当前 schema、迁移工具、ORM）、API 风格（REST/GraphQL/gRPC、认证方式、响应格式）、测试（测试框架、覆盖率模式、测试工具），使 SPEC 与现有系统一致；若无代码库（greenfield）则跳过此步。
4. 提出澄清问题：仅在 PRD 留下技术决策歧义时提问，最多 3-5 个；关注架构选择（功能放哪里、新服务还是扩展现有）、数据存储（新表、扩展现有、缓存策略）、API 设计（新端点、扩展现有、破坏性变更）、依赖（新库、版本约束）、性能（预期负载、延迟要求、批大小限制）。
5. 澄清问题使用选项格式，并允许用户选择「根据代码库替我决定」；若用户选择此类选项，基于代码库分析做最佳选择，并在 SPEC 中记录理由。
6. 生成 SPEC 文档标题：`# SPEC: [Feature Name]`，并注明来源 PRD 文件名/链接、生成日期、目标分支、提交短哈希。
7. 写第 1 节 Summary：1.1 本 SPEC 覆盖什么（一段话说明功能与实现范围）；1.2 PRD 引用（源路径或 URL、覆盖的 User Stories、Functional Requirements）；1.3 设计决策摘要表（Decision、Choice、Rationale）。
8. 写第 2 节 Architecture：2.1 系统上下文（功能在整体系统中的位置，图或描述）；2.2 组件设计（新增组件/模块、职责、边界）；2.3 模块交互（新组件与现有组件如何交互，序列或数据流）；2.4 文件结构（新增与修改文件，如 src/services/priority.service.ts [NEW]、src/controllers/task.controller.ts [MODIFY: add priority endpoints]、src/models/priority.model.ts [NEW]、src/migrations/20240315_add_priority.ts [NEW]）。
9. 写第 3 节 Data Model：3.1 Schema 变更（新表、列、索引，用 SQL 或 ORM 表示）；3.2 实体定义（TypeScript interfaces / Go structs / Python dataclasses）；3.3 关系（与现有实体的 FK、嵌入、引用）；3.4 迁移计划（迁移步骤、向后兼容、回滚策略）。
10. 写第 4 节 API Design：4.1 端点表（Method、Path、Description、Auth、Request、Response）；4.2 请求/响应 Schema（字段类型、校验规则、示例）；4.3 错误响应（错误码、消息、HTTP 状态码）；4.4 破坏性变更（向后不兼容变更及消费者迁移路径）。
11. 写第 5 节 Business Logic：5.1 核心算法（关键操作的逐步逻辑，伪代码或结构化描述）；5.2 校验规则（输入校验、业务规则校验、具体约束）；5.3 状态机（若适用：状态、转换、守卫、副作用）；5.4 边缘情况（已知边缘情况及处理方式）。
12. 写第 6 节 Error Handling：6.1 错误分类表（Error Code、HTTP Status、Condition、User Message）；6.2 重试策略（哪些操作可重试、退避策略、最大尝试次数）；6.3 失败模式（依赖失败时如何优雅降级）。
13. 写第 7 节 Security：7.1 认证与授权（谁能访问什么、权限模型、角色检查）；7.2 输入校验（清理规则、注入防护、大小限制）；7.3 数据保护（敏感字段、静态/传输加密、审计日志）。
14. 写第 8 节 Performance：8.1 预期负载（估计 QPS、数据量、增长预测）；8.2 优化策略（缓存、分页、懒加载、批处理）；8.3 数据库考量（索引策略、查询模式、N+1 预防）。
15. 写第 9 节 Testing Strategy：9.1 单元测试（测什么、测试边界、mock 策略）；9.2 集成测试（API 测试、数据库测试、服务交互测试）；9.3 边缘情况测试（基于 5.4 的具体场景）；9.4 验收标准映射表（US/FR、Test、Type、Description）。
16. 写第 10 节 Implementation Plan：10.1 阶段（实现顺序、先建什么、步骤间依赖）；10.2 Issue 映射（将 SPEC 章节映射到 PRD Issues，列 Issue、SPEC Sections、Priority、Depends On）；10.3 增量交付（如 feature flags、dark launches、逐步 rollout）。
17. 写第 11 节 Open Questions & Risks：11.1 未解决问题（需产品/工程输入的问题）；11.2 技术风险表（Risk、Impact、Mitigation）；11.3 假设（SPEC 创建时所做的技术假设，实施前验证）。
18. 按 PRD→SPEC 映射策略转换内容：User Stories → 第 5 节 Business Logic 与第 9.4 节 Acceptance Mapping（故事转算法+测试用例）；Functional Requirements → 第 4 节 API Design 与第 5 节 Business Logic（FR 转端点+逻辑）；Acceptance Criteria → 第 9 节 Testing Strategy（标准转具体测试场景）；Non-Goals → 第 11.1 节 Open Questions（澄清明确排除项）；Technical Considerations → 第 2 节 Architecture 与第 8 节 Performance（约束转设计决策）；Success Metrics → 第 8.1 节 Expected Load 与第 10.3 节 Delivery（指标转监控+发布计划）。
19. 生成后审查与迭代：向用户展示 SPEC，并询问架构选择是否合适、是否缺少边缘情况或错误场景、API 设计是否与现有模式一致、哪些章节需要更多或更少细节；若用户回复 OK 则保存，否则根据反馈迭代。
20. 保存：询问保存位置，选项包括 A. tasks/spec-[feature-name].md（与 PRD 并列，推荐）；B. docs/spec-[feature-name].md；C. 自定义路径，然后写入最终 SPEC。
21. 执行质量检查：确保每条 PRD User Story 都有对应 SPEC 章节；每条 Functional Requirement 都映射到 API 端点或业务逻辑规则；每条 Acceptance Criterion 至少映射到一个测试用例；架构选择有理由说明；API schema 具体到可生成客户端代码；错误处理覆盖所有已识别失败模式；实现顺序尊重依赖；没有「TBD」或「TODO」，需解决或移到 Open Questions。
22. 处理边缘情况与回退：PRD 模糊或不完整时，用最佳判断生成 SPEC，并在 11.3 标记假设；PRD 与现有代码冲突时，明确标记冲突并在 11.1 提出解决方案；功能太大无法一个 SPEC 容纳时，按服务边界拆成多个 SPEC 并互相链接；无现有代码库（greenfield）时跳过第 2 步，根据 PRD 和澄清问题从零提出架构；PRD 没有 User Stories（只有 bullet points）时，推断结构，将 bullet 映射到 SPEC 章节，并在 Summary 中说明；用户不想读代码库时跳过第 2 步，并注明对现有代码的假设未经验证；多个 PRD 需要一个 SPEC 时，合并 PRD 输入，去重需求，并注明每项来源。
23. 避免反模式：不要复述 PRD；不要过度指定无特殊逻辑的 CRUD；不要脱离上下文选技术，先检查项目已在用什么；不要孤立设计，SPEC 必须适配现有系统并使用相同模式、约定、风格；不要让决策隐式存在，若做了选择要说明并给出原因；不要写实现代码，SPEC 描述契约和行为，复杂算法可用伪代码。
24. 明确技能关系：/prd 产出 PRD（本技能输入）；/prd-to-spec 产出 SPEC（本技能）；/goal 依据 SPEC 实现 Issues；/code-to-spec 从现有代码反向生成 SPEC，与本技能互补（正向 vs 反向）。

适用边界 · 注意事项

• 没有 PRD 或需求尚未明确时，不应强行生成 SPEC。
• 任务只是无特殊逻辑的简单 CRUD 或原型验证时，不必套用完整 SPEC 结构，避免过度设计。
• 用户只需要直接写代码或不需要技术设计契约时，不必先做 PRD-to-SPEC 转换。