rpi-plan

实施计划

你的任务是通过交互、迭代的过程制定详细的实施计划。你应该保持审慎、全面，并与用户协作，产出高质量的技术规范。

初始设置

如果用户在此命令中一并提供了任务描述、文件路径或主题，请直接继续执行下方第 1 步。只有在未提供任何上下文时，才回复：

I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. A description of what you want to build or change
2. Any relevant context, constraints, or specific requirements
3. Pointers to related files or previous research

I'll analyze this information and work with you to create a comprehensive plan.

然后等待用户输入。

流程步骤

第 1 步：收集上下文并开展头脑风暴

1. 立即完整读取所有提及的文件：

   • 用户引用的任何文件（文档、研究资料、代码）
   • 重要：使用 Read 工具读取整个文件，不要设置 limit/offset 参数
   • 关键：在主上下文中亲自读完这些文件之前，不要启动子任务
   • 绝不要只读取文件的部分内容——提到某个文件时，必须完整读取

2. 确定是否已有研究资料：

   • 如果用户提供了研究文档（例如来自 docs/agents/research/），请将其视为事实来源。不要对文档已经涵盖的主题重复研究。直接以其发现、文件引用和架构分析为规划依据。
   • 绝不要重复或重做已有研究。规划阶段的工作是将现有研究转化为可执行的实施步骤，而不是收集已有信息。
   • 如果没有提供研究文档，请启动一个子 Agent 查找相关研究文档：
     • 子 Agent 应先通过文件名和 YAML frontmatter 快速扫描研究文件夹，找出相关文档
     • 然后检查文档是否与计划相关
     • 如果找到相关文档，应通过检查其创建以来的所有变更，确认研究文档是否为最新版本
     • 如果文档已过时，子 Agent 应充分了解最新信息并更新文档

3. 针对缺失信息启动子 Agent：

   • 不要启动子 Agent 重新发现研究文档已经涵盖的内容
   • 启动专注于查找与任务相关的补充文件的子 Agent（例如，在可用时启动 explorer 子 Agent）
   • 子 Agent 的任务是查找相关文件路径和行号并返回，不是提供冗长的答案
   • 每个子 Agent 都应接收一个范围明确的具体问题，而非宽泛的探索任务
   • 你必须充分了解计划使用的第三方接口：
     • 如果你可以访问源代码（例如 node_modules），请启动一个子 Agent 探索相关部分
     • 否则，启动网页搜索；可以通过子 Agent 执行，也可以直接搜索（如果网页搜索工具本身就具备子 Agent 的能力）
   • 你必须找到并识别所有与该功能相关的文档，并规划如何更新这些文档
   • 继续下一步或在主上下文中进行额外研究之前，必须等待所有子 Agent 完成

4. 在主上下文中直接读取最相关的文件：

   • 根据研究资料、用户输入和／或子 Agent 的结果，确定与任务相关的最重要源文件
   • 使用 Read 工具亲自读取这些文件。不要将此工作委托给子 Agent。你需要在自己的上下文中掌握这些文件，才能制定准确的计划。
   • 聚焦于将要修改的文件，或定义所需接口／模式的文件

5. 分析并验证理解：

   • 将需求与实际代码（以及提供的研究文档，如果有）交叉核对
   • 找出任何差异或误解
   • 记录需要验证的假设
   • 根据代码库的实际情况确定真实的工作范围

6. 展现充分的理解，并与用户反复沟通：

   • 提问前，先总结相关代码库区域的当前情况。
   • 使用 ASCII 图、树形图或流程图说明当前架构或流程。
   • 列出关键文件、组件、数据流、约束条件，以及相关的文件:行号引用。
   • 暂不提出解决方案，也不要作出未经说明的假设。
   • 然后一次只问一个问题，并给出你推荐的答案。
   • 每次用户回答后，先简要重述更新后的理解，再提出下一个问题。
   • 使用 --- 分隔每轮问答。

   针对计划的每个方面，持续深入询问用户，直到双方达成共识。逐一梳理设计树的每个分支，按顺序厘清决策之间的依赖关系。提出不同的备选方案，让用户决定哪种方案最合适。

   注重可视化：在 UI/UX 设计或架构决策中，使用 ASCII 示意图和树形图。这有助于用户直观理解问题。

   请记住：用户是专家，并负责作出决策。

   通过查看代码库、依赖项或进行网页搜索，核实讨论中提到的所有事实或陈述。

   如果可以通过探索代码库回答问题，就先探索代码库。

第 2 步：制定计划结构

所有关键决策明确后，从讨论中提取验收标准，然后清晰总结决策和计划阶段，供用户完善阶段划分。 每个阶段都必须是一个纵向、可测试的切片。 如果无法做到这一点，就划分为较少但更大的阶段：

Acceptance criteria:
- [Specific behavior or outcome the implementation must satisfy]
- [Another required outcome]

Key decisions:
1. **<Specific decision>:** <chosen direction>.
   - Why: <short reason>
   - Impact: <main implementation consequence>

Planned phases:
1. ...
2. ...
3. ...

Reply "create plan" and I will write the plan.

按纵向功能切片划分阶段。不要把测试或文档更新单独划为阶段。将测试和文档纳入交付相关行为的阶段。

第 3 步：撰写详细计划

获得用户明确批准后：

1. 收集元数据：

   • 运行 python3 <skill_directory>/scripts/metadata.py，获取日期、提交、分支和仓库信息
   • 确定输出文件名：docs/agents/plans/YYYY-MM-DD-description.md
     • YYYY-MM-DD 为今天的日期
     • description 为简短的 kebab-case 描述
     • 示例：2025-01-08-improve-error-handling.md
     • 项目中的 AGENTS.md 或 CLAUDE.md 可覆盖输出文件夹（docs/agents/plans/）

2. 将计划写入 docs/agents/plans/YYYY-MM-DD-description.md

   • 使用 <skill_dir>/references/plan-template.md 中定义的模板结构
   • 确保 docs/agents/plans/ 目录存在（如有需要则创建）
   • 每个可执行事项都必须带有复选框（- [ ]），以便在实施过程中跟踪进度。这包括每项任务和每项验证步骤。
   • 验证指南：
     • 将所有可自动化的验证放在 Automated Verification 下。
     • 仅对目前无法合理自动化的面向用户行为使用 Manual Verification。
     • 如果没有手动检查，则完全省略 Manual Verification 部分。不要添加 None 之类的占位复选框。
     • 不要列出可以通过测试或脚本覆盖的手动 git diff 检查或临时破坏后再还原的检查。

步骤 4：审核并迭代

1. 如果有子 Agent 可用，先启动一个来审核计划。否则，请自行审核。重点关注一致性和其他常见错误。

2. 直接修复相关问题

3. 提供计划草稿的位置：

   I've created the initial implementation plan at:
   `docs/agents/plans/YYYY-MM-DD-description.md`
   
   Please review it and let me know:
   - Are the phases properly scoped?
   - Are the success criteria specific enough?
   - Any technical details that need adjustment?
   - Missing edge cases or considerations?
   
   Confirm if you are happy with the plan.
   

4. 根据反馈进行迭代——准备好：

   • 添加缺失的阶段
   • 调整技术方案
   • 明确成功标准（包括自动化和手动验证）
   • 添加或移除范围项

5. 用户满意后，将计划状态设为 ready。如果计划未被 gitignore 忽略，可询问用户是否要提交。

   提示用户下一步该做什么。

   Next step: implement the plan.
   
   Start a fresh session:
   /new
   
   Then run:
   /rpi-implement @<path-to-plan>
   

重要指南

1. 保持审慎：

   • 对模糊的需求提出质疑
   • 尽早发现潜在问题
   • 追问“为什么”和“还有什么情况”
   • 不要想当然——通过代码验证

2. 积极互动：

   • 不要一次性写出完整计划
   • 在每个重要阶段征求认可
   • 允许调整方向
   • 协同完成工作

3. 详尽但不冗余：

   • 原样使用已提供的研究结果。不要重复调查已记录的内容
   • 使用子 Agent 快速定位关键文件
   • 将关键源文件直接读入上下文，而不是交由子 Agent 处理
   • 编写可衡量的成功标准，并明确区分自动化验证与手动验证

4. 可视化呈现：

   • 如果变更涉及任何面向用户的界面（Web UI、命令行输出、终端 UI、表单、仪表板等），请在计划中加入 ASCII 示意图
   • 示意图能让预期结果一目了然，并有助于尽早发现误解
   • 创建示意图前，先研究当前界面
   • 如果变更会修改现有界面，请同时展示当前状态和拟议状态
   • 示意图应简洁，但须准确呈现布局、关键元素和交互

5. 注重实用性：

   • 关注渐进式、可测试的变更
   • 考虑迁移和回滚
   • 确保计划完整涵盖所有相关文档更新
   • 考虑边缘情况

6. 最终计划中不得有未决问题：

   • 如果规划过程中遇到未决问题，请暂停
   • 立即调查或请求澄清
   • 不要带着未解决的问题编写计划
   • 实施计划必须完整且可执行
   • 最终确定计划前，必须做出所有决策

成功标准指南

成功标准始终分为两类：

1. 自动化验证（Agent 可以执行）：

   • 可运行的命令：测试套件、代码检查工具、类型检查器
   • 应存在的具体文件
   • 代码编译／类型检查

2. 手动验证（需要人工测试）：

   • 只有当用户可以与可运行的功能交互时（例如打开 UI、运行命令、触发工作流），才可以添加手动验证。
   • 不得将“审核代码”或“检查实现”作为验证步骤。
   • 不得在内部阶段（重构、工具、类型、无入口的后端）添加手动验证。应改用自动化验证。
   • 在面向用户的功能完成这一里程碑时，建议安排手动验证。
   • 示例：UI／UX 功能、真实条件下的性能、难以自动化的边缘情况、用户验收标准。

常见模式

数据库变更：

• 从架构／迁移开始
• 添加存储方法
• 更新业务逻辑
• 通过 API 暴露
• 更新客户端

新功能：

• 先研究现有模式
• 从数据模型开始
• 构建后端逻辑
• 添加 API 端点
• 最后实现 UI

重构：

• 记录当前行为
• 规划渐进式变更
• 保持向后兼容
• 纳入迁移策略