如何用 goose 的 RPI 配方工作流完成复杂代码库的调研、规划与实现？

如何用 goose 的 RPI 配方工作流完成复杂代码库的调研、规划与实现？

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose

当你需要对一个大型代码库做跨多个文件的改动——重构、迁移、新增功能、大规模升级、事故清理或文档翻新——直接让 AI agent “把代码改了”往往会失控：改动面太大、上下文太长，agent 容易漏改或误伤。goose 的 RPI（Research → Plan → Implement）工作流把这类任务拆成三个纪律分明的阶段，每个阶段在独立的新会话中执行，各自产出可审阅的中间文档：先调研出功能现状的技术地图，再基于调研生成带验证标准的分阶段计划，最后按计划机械地执行并逐步验证。这套流程用速度换清晰度和正确性，适合复杂任务；对简单改动则没有必要。

准备：导入 RPI 配方并配置斜杠命令

RPI 工作流由 4 个主配方（recipe）和 3 个子配方（subrecipe）组成。配方文件存放在项目仓库的 documentation/src/pages/recipes/data/recipes 目录下，官方 RPI 教程 的原始做法是把它们下载到全局配方目录，你在本地仓库 checkout 中也可以直接复制。

把配方复制到全局配方目录

在终端执行（会在家目录的~/.config/goose下创建recipes/和subrecipes/两个目录）：

mkdir -p ~/.config/goose/recipes/subrecipes

然后把仓库中的 4 个主配方复制到~/.config/goose/recipes/，3 个子配方复制到~/.config/goose/recipes/subrecipes/。子配方必须放在subrecipes/子目录中，因为主配方通过相对路径引用它们，例如 rpi-research.yaml 中声明：

sub_recipes: - name: "find_files" path: "./subrecipes/rpi-codebase-locator.yaml" - name: "analyze_code" path: "./subrecipes/rpi-codebase-analyzer.yaml" - name: "find_patterns" path: "./subrecipes/rpi-pattern-finder.yaml"

需要复制的文件：

• 主配方：rpi-research.yaml、rpi-plan.yaml、rpi-implement.yaml、rpi-iterate.yaml
• 子配方：rpi-codebase-locator.yaml、rpi-codebase-analyzer.yaml、rpi-pattern-finder.yaml

4 个主配方都依赖内置的developer扩展（各配方extensions字段中name: developer, bundled: true），无需额外安装。

为每个配方绑定斜杠命令

按 自定义斜杠命令指南，在 goose CLI 中编辑~/.config/goose/config.yaml，按教程给出的对应关系为 4 个配方分别添加命令：

slash_commands: - command: "research_codebase" recipe_path: "~/.config/goose/recipes/rpi-research.yaml" - command: "create_plan" recipe_path: "~/.config/goose/recipes/rpi-plan.yaml" - command: "implement_plan" recipe_path: "~/.config/goose/recipes/rpi-implement.yaml" - command: "iterate_plan" recipe_path: "~/.config/goose/recipes/rpi-iterate.yaml"

如果使用的是 goose Desktop，也可以在界面中操作：点击左上角按钮打开侧边栏，进入Recipes，找到目标配方点击终端图标，在弹窗中输入命令名（不带前导/），点击Save，命令会显示在该配方的条目下。

需要注意的斜杠命令限制（来自指南的 Limitations 一节）：

• 命令只接受一个参数，配方中其余参数必须有默认值；
• 命令名不区分大小写，必须唯一且不含空格；
• 不能与内置 CLI 斜杠命令（如/recipe、/compact、/help）重名；
• 如果配方文件缺失或无效，命令会被当作普通文本发给模型——如果/research_codebase没有触发工作流，先检查recipe_path是否指对了文件。

第一阶段：/research_codebase 调研并记录现状

在你已 clone 的目标代码库中启动一个新的 goose 会话，用自然语言主题调用调研命令。教程中的示例是：

/research_codebase "look through the cloned goose repo and research how the LLM Tool Discovery is implemented"

该命令调用 RPI Research Codebase 配方，其职责被严格限定为：记录现状、不提改进建议、不做批评、不做规划。执行时它会并行派生三个子任务，分别对应上面导入的三个子配方：

• find_files（rpi-codebase-locator）：用 ripgrep 和文件列表定位相关文件的所在位置，返回带简述的文件路径列表；
• analyze_code（rpi-codebase-analyzer）：完整读取这些文件，记录函数签名、数据流和依赖关系；
• find_patterns（rpi-pattern-finder）：在仓库其他地方寻找相似功能或既有惯例作为参照。

三个子任务独立运行并汇报结果，不需要你手动编排。随后配方会收集 git 元数据（日期、git rev-parse HEAD、当前分支、仓库名），最终把调研文档写入thoughts/research/YYYY-MM-DD-HHmm-topic.md（如thoughts/research/2025-12-22-llm-tool-selection-strategy.md），结构包含：Git 元数据、file:line形式的代码引用、流程描述、关键组件说明和未决问题（Open Questions）。

判断这一步是否完成的依据：thoughts/research/下出现了带上述结构的调研文档，且文件与行号引用真实存在。这一步没有任何代码被修改，这是刻意为之——目标只是建立共享理解，所以教程强调：作为 human in the loop，务必人工审阅调研文档，因为它直接决定下一步计划的质量。

如果调研开始后发现主题定得太宽，直接停止并换更精确的主题重跑即可。教程作者在演示中就把“研究 Tool Discovery 全貌”纠正为“研究待移除的 Tool Selection Strategy 功能”，避免计划阶段误删其他功能。教程明确指出这不是失败：调研阶段犯错的成本最低，容易恢复。

第二阶段：/create_plan 生成分阶段实施计划

调研文档审阅通过后，开启一个新会话。教程特别提醒：每个阶段都应在新会话中执行（one goal per session），让模型只聚焦当前任务。调用示例：

/create_plan a removal of the Tool Selection Strategy feature

RPI Create Plan 配方的第一动作是完整读取调研阶段产出的文档，然后做三件事：

1. 提出澄清问题——只问通过代码调研无法回答的问题，例如：完全移除还是弃用（deprecation）？配置清理行为如何？OpenAPI 产物是否要重新生成？相关测试在哪里？
2. 给出设计选项——存在多个合理方案时列出各方案的利弊，由你选择。
3. 产出分阶段实施计划——写入thoughts/plans/YYYY-MM-DD-HHmm-description.md（如thoughts/plans/2025-12-23-remove-tool-selection-strategy.md）。

按计划模板，计划文档包含：明确的分阶段（Phase）结构、精确的文件路径、展示要删除/修改代码的代码片段、分“自动验证（Automated Verification，可脚本化命令）”和“手动验证（Manual Verification，需人工测试）”两类的成功标准，以及用于追踪进度的 checkbox。

这一阶段结束后，计划文档成为 source of truth：理解阶段结束，决策阶段开始，但仍未触碰代码。由于执行会在新的空上下文中进行，计划必须写得足够自足——让不了解前文的另一个人也能照做。

如果审阅计划发现问题，不需要推倒重来：用 RPI Iterate Plan 配方（可选步骤）针对性修订。

/iterate_plan "thoughts/plans/2025-12-23-remove-tool-selection-strategy.md" 计划中 Phase 3 的测试范围不对

它的工作方式是：完整读取现有计划，只针对需要重新思考的部分发起调研（而非整体重查），先向你确认理解的改动再动手，然后做外科手术式的精确编辑——保留仍然有效的内容，只更新受影响的部分和成功标准，最后汇报改动清单。配方提示中给出的一个实用命令是列出最近的计划：

ls -lt thoughts/plans/ | head

第三阶段：/implement_plan 逐阶段执行并验证

再次开一个新会话，把计划文档路径作为参数传入（教程示例）：

/implement_plan thoughts/plans/2025-12-23-remove-tool-selection-strategy.md

RPI Implement Plan 配方按以下纪律执行：

• 完整读取计划，检查已有的勾选标记（- [x]），完整读取计划中提到的所有文件，建立 todo 清单后开始实现；
• 按计划中的文件路径和代码块直接执行，不重新搜索计划已文档化的内容，只在计划含糊或验证改动完整性时才搜索；
• 按阶段顺序执行，每个阶段完成自动检查（计划中的 Automated Verification 命令）后才进入下一阶段，并在计划文件里直接勾选已完成的项。

每完成一个阶段的自动验证，它会暂停并等待你做计划中列出的手动验证，格式大致为“Phase N Complete - Ready for Manual Verification”，并列出已通过和待人工执行的检查项；在用户确认前，手动测试项不会被勾选。如果实际代码与计划不符，它会停下来，以“Expected / Found / Why this matters”的结构说明问题并询问如何继续，而不是自行猜测。

计划文件中的 checkbox 还有一个实际用途：教程作者在演示中上下文窗口中途被填满，goose 压缩上下文后能凭计划里的勾选状态从断点继续。恢复规则写在配方里——如果计划已有勾选项，信任已完成的工作，从第一个未勾选项继续，只在异常时复核。

这一阶段应该感觉“机械”。教程作者的原话：如果执行过程感觉很有创造性，说明上游（调研或计划）有缺失。

教程中的实际演示与适用边界

官方教程用一次真实改动完整走完了这个流程：从大型代码库中移除 Tool Selection Strategy 功能，该功能横跨核心 Rust 代码、TypeScript、配置、测试和文档。文档记录的结果是（以下数字是教程示例数据，不是固定预期）：

• 计划共 10 个阶段、涉及 32 个文件；
• Research 阶段 9 分钟，Plan 阶段 4 分钟，Implement 阶段 39 分钟，总计 52 分钟（含作者回答澄清问题的时间）；
• 最终提交 PR 后构建通过，独立的 Code Review Agent 没有提出任何意见。

按文档说明，RPI 的适用场景包括：重构（Refactors）、迁移（Migrations）、功能新增（Feature additions）、大型升级（Large upgrades）、事故清理（Incident cleanup）、文档翻新（Documentation overhauls）。对基础任务，这套流程可能过重——它本身不是一个快速过程。

全部产物都落在仓库内两个可预测的位置，这也是你核对整个工作流是否走完的最终检查点：

thoughts/ ├── research/ │ └── YYYY-MM-DD-HHmm-topic.md └── plans/ └── YYYY-MM-DD-HHmm-description.md

如果thoughts/research/中的文档引用不准确，回到第一阶段重跑调研；如果thoughts/plans/中的计划有偏差，用/iterate_plan精确修订而不是重写；只有计划审阅通过后才进入/implement_plan。三个阶段各自独立可验证，任何一步出了问题都能在成本最低的位置停下修正。

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose