Prd To Spec

---
name: prd-to-spec
description: "Transform a PRD into a technical SPEC document — architecture, API design, data model, error handling, and implementation contracts. Triggers on: prd-to-spec, prd to spec, prd转spec, 需求转设计, 需求转规格, generate spec from prd, design from prd, 技术方案, 设计方案."
user-invocable: "true"
---
# 产品设计文档到技术规范的转换

以50年代码开发工作经验及架构师身份从代码工程范式、可维护性、性能、质量、安全等角度出发，生成具体代码详细技术规范。根据(PRD)文档内容，补全代码领域潜在行业知识、代码风格、技术规范，并澄清潜在的问题，来指导工程师或人工智能如何构建。

## 何时使用

- 根据`/prd`生成得文档，弥合它与实施落地之间的差距。
- 当未开始实时编码，方案调整阶段，prd文档更新对应spec同步更新时。
- 你希望在编码开始之前就把架构决策记录下来。
- 多个开发人员/智能体将实现此功能，因此需要一份共享合约。
- 在落地实施之前，生成产品需求文档 (PRD) 之后，您需要验证技术可行性以及问题。

## 步骤1:找到PRD

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

```markdown
Provide the PRD to convert:

A. File path (e.g., docs/prd/prd-priority-system.md)
B. Accessible web service URL 
C. Paste PRD content directly
D. Auto-detect: scan docs/ directory for recent PRDs
```

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

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

Which PRD should I convert? [1/2]
```

如果没有找到PRD则引导用户执行`/prd` 技能并生成PRD文档，然后在执行后续操作。

## 步骤2:信息收集(可选)

结合项目工程上下文收集信息，补充实际落地代码之间的隐藏关键差距信息

- **现有架构**——当前系统的结构方式
- **技术栈**——已使用的语言、框架、依赖库、代码管理工具。
- **模式**——文件组织、公共包、通用方法、组件、帮助函数、错误处理方法
- **代码规范**——命名约定、代码风格、规范、质量标准、设计模式
- **数据库**——当前模式、迁移工具、ORM
- **API 风格**— REST/GraphQL/gRPC、身份验证方法、响应格式
- **测试**——测试框架、覆盖模式、测试工具

收集方式如下:

1. 用户提供得prompt、文档、图片、链接、可访问资源等。
2. 检索架构设计文档 `docs/architecture/ADR-[number]-[title].md` 文档，存在则参考设计。
3. 当前已有的项目实现，优先读取CLAUDE.md、AGENTS.md、README.md等文档内容，或分析现有代码仓库实现。
4. 知识库、.docs/、.spec/、plan/ 、prd/检索
5. 检索skills以及rules `.claude/skills/**/SKILL.md`，`.codex/skills/**/SKILL.md`，`.**/skills/**/SKILL.md`、`.claude/rules/*` 、`.codes/rules/*` 等可用得技能、规则, 提取最佳实践、约定规范、案例等。
6. 外部知识检索，当收集到的信息不足、了解最新技术方案与技术调研，如下:
    1. **Context7 MCP**（`mcp__context7__resolve-library-id`，`mcp__context7__query-docs`）：当 MCP 服务器连接时首选，返回结构化文档MCP检索。当MCP不可用但ctx7 CLI 可用则作为备用方案
    2. WebSearch/WebFetch。
    3. 其他可访问知识检索MCP、skills、知识库检索等。

对收集得信息进行分析并归纳总结，用于后面澄清与决策。

## 步骤3:澄清问题

当产品需求内容存在潜在问题、矛盾、缺失，或对技术决策存在歧义时才提出问题，一次只提一个问题。

1. 需求模糊，交互流程缺失、逻辑矛盾，边界不清晰。
2. 数据流转生命周期是否完整，是否闭环，是否矛盾。
3. 错误处理、限流控值、服务降级、安全保证，兜底方案。
4. 需求不合理处，技术瓶颈，实现风险。
5. 复用现有实现，如不能复用，在原有的接口、页面、组件、方法、对象，以及功能模块紧邻相关方法上进行修改或扩展。
6. 澄清内容矛盾点，例如一个需求功能提供了多份资料来源:
    1. 文档与文档之间描述不一致情况问题。
    2. 文档与截图，UI图，原型图所呈现不一致内容矛盾点(图中展示5个字段文档中为6个字段)。
    3. 现有代码与文档之间的矛盾点。
7. 补充prd文档、需求中没有提到的隐形知识与规则，根据 **信息收集** 丰富上下文。例:
    1. 平台支持了国际化，默认人是知道的但是文档没有体现。
    2. 增加了新的支付方式，文档并没有提出账户流水处理方式。
    3. 默认样式颜色、布局、弹窗、组件、间距、字体、内容过长缩略展示策略等。
    4. 接口参数的规则规范，字段命令都是采用驼峰还是下滑线。
    5. 具体领域知识的默认、约定俗成规则，比如文件命名不能采用中文等。

格式可以是单选或多选

```markdown
**Q: Description content**

- [ ] A: item1 description (Recommendation)
- [ ] B: item2
- [ ] C: item3
- [ ] D: Custom input content.
```

## 步骤4:文档格式

根据 `reference/template.md` 模板文件创建SPEC文档。

## 步骤5:保存

引导用户保存文档

```markdown
**Where should I save the SPEC?**

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

## 步骤6:自我审查

生成 SPEC 文档后，请以全新的视角审视规范，并对照规范检查：

- [ ] 架构方案选择是否恰当,是否脱离实际业务过度设计？
- [ ] 是否存在遗漏的边缘情况，数据、逻辑是否闭环、错误场景？
- [ ] 新功能修改实现是否破坏旧实现,是否兼容？
- [ ] 是否有任何部分需要增加或减少详细程度？
- [ ] 要符合 **质量标准** 章节规则内容

## 质量标准

好的SPEC规格说明书应该通过以下检查：

- [ ] 内容描述完整，不能存在模糊、歧义点。
- [ ] 每个产品需求文档 (PRD) 用户故事都有对应的规格说明 (SPEC) 部分。
- [ ] 每个功能需求都对应一个 API 端点、方法或业务逻辑规则
- [ ] 每个验收标准都至少对应一个测试用例。
- [ ] API 模式足够具体，可以生成客户端代码。
- [ ] 错误处理涵盖所有已识别的场景。
- [ ] 执行顺序尊重依赖关系，减少摩擦与冲突。
- [ ] 架构、接口抽象、代码模式、设计选择有理有据，不能过度设计。
- [ ] 避免重复实现，应体现充分利用现有标准库、依赖库、通用库、方法。
- [ ] 可沉淀成为通用的功能、方法、或设计模式，以及通用方法的适配改造。
- [ ] 没有“待定”或“待办”事项——解决或移至“未决问题”部分

## 边缘情况和回退

| 设想 | 处理 |
| ---------------------------------- | ------------------------------------------ |
| PRD内容含糊不清、不完整或矛盾点(文档与文档，文档与图片内容矛盾) | 通过交互式提问进行明确,尽力生成规范 (SPEC)，并在第 11.3 节中标记假设。 |
| PRD与现有代码冲突 | 明确指出标志冲突，并在第 11.1 节中提出解决方案。 |
| 该功能对于一个规格来说太大了。 | 拆分成多个 SPEC（每个服务边界一个），并将它们链接起来。 |
| 没有现有代码库（全新项目） | 跳过步骤 2，根据产品需求文档 (PRD) 和澄清问题从头开始提出架构方案。 |
| 产品需求文档中没有用户故事（只有要点列表）。 | 推断结构，将要点映射到 SPEC 部分，并在摘要中注明 |
| 用户想要规格说明，但不想阅读代码库 | 跳过步骤 2，请注意，关于现有代码的假设未经验证。 |
| 多个产品需求文档 (PRD) 需要一份规格说明 (SPEC)。 | 合并产品需求文档 (PRD) 输入，去重需求，并注明每个需求的来源。 |
| 保存文档后调整修改避免文档内容截断丢失 | 在保存文档之后在文档的基础上进行修改而不是覆盖操作。 |
| 没有明确指令时，编写完文档直接开始进入代码开发 | 立即停止下来，给出后续引导决定权交给用户 |

## 避免反模式

- **不要重复产品需求文档（PRD）。** 规范（SPEC）是在技术层面进行深入阐述，而不是用不同的措辞复制需求。
- **不要过度描述简单的操作。** 没有特殊逻辑的 CRUD 操作不需要完整的算法部分。
- **不要脱离实际情况选择技术。** 在推荐新工具之前，务必先了解项目目前使用的技术。
- **不要孤立地进行设计。** 规范必须与现有系统相符——相同的模式、相同的约定、相同的风格。
- **不要让决策含糊不清。** 如果你做出了选择（例如，“向现有表中添加列”），请明确说明并解释原因。
- **不要编写实现代码。** 规范描述的是契约和行为，而不是代码。对于复杂的算法，可以使用伪代码。
- **不要忽略对应需求功能转换。** 模块功能复杂，功能繁多不能忽略，必要时拆分成多个spec文档，根据模块或功能。

## 后续处理

与其他技能的关系

```text
/prd   →  /prd-to-spec   →   /goal 
 │               │              │
 │  Requirements │  Technical   │  Implementation
 │  (what)       │  (how)       │  (code)
```

- **/prd**生成 PRD（此技能的输入）
- **/prd-to-spec**生成 SPEC（此技能）
- **/goal**实现以 SPEC 为技术参考的问题

提醒用户后续最后可能执行的处理

```markdown
后续操作建议

A: 清空上下文并执行技能 `/goal spec-[number]-[spec-name].md 根据spec文档执行` (Recommendation)
B: 当前上下文执行技能 `/prd-to-spec spec-[number]-[spec-name].md 根据spec文档执行`
C: 当前上下文执行技能 `/to-issue spec-[number]-[spec-name].md 根据文档拆分任务使用本地文件方式` X 
D: 清空上下文并执行技能 `/to-issue spec-[number]-[spec-name].md 根据文档拆分任务使用本地文件方式` X 
F: 关闭停留在当前继续调整
```