pdd

提示词驱动开发

概述

将粗略的想法转化为详细设计和实施计划。这个过程是迭代的：澄清需求、开展研究、进行设计、制定计划，并根据需要在各阶段之间切换。

重要说明

以下规则适用于所有步骤：

• 由用户驱动流程： 未经用户明确确认，绝不进入下一步。每次阶段转换时，都要询问用户接下来想做什么。
• 迭代式： 用户可以随时在需求澄清和研究之间切换。阶段转换时，务必提供此选项。
• 随时记录： 实时将问题、答案和发现追加到项目文件中，不要等到最后才一次性写入。
• Mermaid 图表： 在研究和设计文档中，为架构、数据流和组件关系添加图表。
• 来源： 如果依据外部资料编写研究文档，请注明参考资料和链接。
• 仅限规划： 此 SOP 仅生成规划产物。不得实现代码、运行容器、执行脚本或开始任何实施工作。如果用户想要实施，请引导他们使用 ralph run。

参数

• rough_idea（必需）：待完善的初始概念或想法
• project_dir（可选，默认值：specs/{task_name}/）：所有产物的基础目录。根据想法以 kebab-case 格式生成 {task_name}（例如，“build a rate limiter” → rate-limiter）。与 Ralph 的规范驱动流水线相匹配。

约束：

• 必须在一个提示中一次性询问所有必需参数
• 必须支持多种输入方式：直接输入文本、提供文件路径、提供 URL
• 必须根据粗略想法以 kebab-case 格式生成 task_name
• 不得覆盖现有项目目录；如果目录已有内容，请询问新的路径

步骤

1. 创建项目结构

创建目录和初始文件：

• {project_dir}/rough-idea.md — 用户提供的粗略想法
• {project_dir}/requirements.md — 问答记录（初始为空）
• {project_dir}/research/ — 研究笔记目录

告知用户此结构将用于 Ralph 的规范驱动预设。

关卡： 用户确认项目结构可接受后，才能继续执行步骤 2。

2. 初步流程规划

询问用户偏好的起始点：

• 澄清需求（默认）
• 对特定主题开展初步研究
• 先提供更多背景信息

关卡： 必须等待用户选择后才能继续。未经用户明确指示，不得自动开始澄清需求或开展研究。

3. 澄清需求

通过提问引导用户，将想法完善为详尽的规格说明。

约束：

• 每次只能问一个问题，不要列出多个问题
• 不得预先填写答案，也不得将问答一次性写入 requirements.md
• 每个问题都必须遵循以下流程：
  1. 拟定问题并追加到 requirements.md
  2. 向用户提出问题，等待用户完整回答
  3. 将答案追加到 requirements.md
  4. 继续下一个问题
• 继续之前，必须询问用户是否已完成需求澄清

覆盖边缘情况、用户体验、技术约束和成功标准。如果用户不确定，请提供选项。

关卡： 未经用户明确确认需求澄清已完成，不得继续开展研究或设计。若出现可通过补充信息解答的问题，必须提供开展研究的选项。

4. 研究

研究技术、库或现有代码，为设计提供参考。

约束：

• 你必须向用户提出研究计划，并采纳他们的建议
• 你必须将研究发现记录在 {project_dir}/research/ 中，分别存入各主题文件
• 你必须定期与用户沟通，分享研究发现并确认方向
• 进入下一步前，你必须总结关键发现

**关卡：**在用户确认研究已充分之前，你绝不能进入迭代检查点。如果研究发现了新问题，你必须提出返回需求澄清阶段。

5. 迭代检查点

总结当前的需求和研究情况，然后询问用户：

• 是否进入设计阶段？
• 是否返回需求澄清阶段？
• 是否开展更多研究？

**关卡：**未经用户明确确认，你绝不能进入设计阶段。你必须支持根据需要在需求与研究阶段之间反复迭代。

6. 创建详细设计

创建 {project_dir}/design.md，作为独立文档，包含以下章节：

• 概述
• 详细需求（根据 requirements.md 汇总）
• 架构概述
• 组件与接口
• 数据模型
• 错误处理
• 验收标准（采用便于机器验证的 Given-When-Then 格式）
• 测试策略
• 附录（技术选型、研究发现、替代方案）

约束：

• 你必须将设计编写成独立文档，无需阅读其他文件即可理解
• 你必须整合 requirements.md 中的所有需求
• 你必须在附录中总结研究内容（技术选型、替代方案、局限性）
• 你必须与用户评审设计，并根据反馈进行迭代

**关卡：**未经用户明确批准设计，你绝不能进入实施计划阶段。如果设计评审中发现缺漏，你必须提出返回需求或研究阶段。

7. 制定实施计划

创建 {project_dir}/plan.md，列出一系列循序渐进的实施步骤。

**指导原则：**每个步骤都应建立在前序步骤的基础上，产出可运行、可演示的功能，并遵循 TDD 实践。不得留下孤立代码——每个步骤都必须以集成收尾。应尽早提供核心端到端功能。

约束：

• 你必须在 plan.md 顶部加入清单，用于跟踪每个步骤
• 你必须使用“Step N:”格式，并包含：目标、实施指导、测试要求、集成说明和演示描述
• 你必须确保计划覆盖设计的所有方面，同时避免重复设计细节

**关卡：**未经用户评审并批准实施计划，你绝不能进入总结阶段。

8. 总结并呈现结果

创建 {project_dir}/summary.md，列出所有产出文件，简要概述，并提供建议的后续步骤。在对话中呈现此总结。

9. 提供 Ralph 集成选项

询问：“你希望我创建一份 PROMPT.md，让 Ralph 自主实现吗？”

如果用户同意，请创建一份简洁的 PROMPT.md（不超过 100 行），包含：

• 目标说明
• 关键需求
• 验收标准（Given-When-Then）
• 对 specs/{task_name}/ 的引用

建议使用相应命令：

• 完整流程：ralph run --config presets/pdd-to-code-assist.yml
• 简化流程：ralph run -c ralph.yml -H builtin:code-assist

如果用户拒绝，请确认并结束会话。

**关卡：**你绝不能运行 ralph run 或开始任何实施。本 SOP 到此结束。实施是用户自行启动的独立步骤。

示例

输入：“我想为我们的内部工具构建模板管理功能——创建、编辑和共享模板，并使用自定义字段生成文档。”

**输出：**一个 specs/template-management/ 目录，其中包含 rough-idea.md、requirements.md、research/、design.md、plan.md 和 summary.md——以及可选的、用于自主实施的 PROMPT.md。

故障排查

需求陷入停滞： 建议切换到其他方面，提供示例，或转向调研以推动决策。

调研受限： 记录缺少的信息，依据现有信息建议替代方案，并向用户询问更多背景。不要因此阻碍进展。

设计过于复杂： 拆分为较小的组件，优先实现核心功能，建议分阶段实施，并返回需求重新确定优先级。