外观
RPI：研究→计划→实现
将功能开发分为三个锁定阶段：首先研究可行性，其次规划实现方案，最后编写代码。每个阶段产出具体的工件，每个关卡都需要明确的 GO 指令才能进入下一阶段。
目录
- TL;DR
- 何时使用 RPI
- 关卡如何运作
- 阶段一：研究
- 阶段二：计划
- 阶段三：实现
- 斜杠命令模板
- 实战示例
- 与其他工作流的对比
- 技巧与故障排查
- 参见
TL;DR
Plain
阶段一 — 研究：
Claude 探索可行性，揭示风险，提出决策问题
产出：RESEARCH.md
关卡：你决定 GO / NO-GO
阶段二 — 计划：
Claude 撰写架构决策、用户故事、测试计划
产出：PLAN.md
关卡：你在编写任何代码前批准计划
阶段三 — 实现：
Claude 逐步实现，每步完成测试关卡后才进入下一步
产出：可运行的代码 + 通过的测试
关卡：每个实现步骤验证通过后才开始下一步最适合：可行性不明确的功能、超过一天工作量的功能、未知技术领域，或因错误假设而造成的代价较高的情况。
何时使用 RPI
适合使用 RPI 的情况
- 可行性未知：你有想法，但不确定技术上是否可行
- 规模较大：实现工作量超过一天
- 需求模糊：你知道想要的结果，但不知道如何达到
- 方向错误的风险较高：安全、支付、数据迁移、与外部系统集成
- 之前曾被意外惊到：某个功能看起来简单，结果涉及 6 个其他系统
跳过 RPI 的情况
| 场景 | 更好的方式 |
|---|---|
| 修复很明显（错别字、颜色错误） | 直接编辑 |
| 功能理解清晰，需求明确 | 「规范先行」 或 「双实例」 |
| 探索模式 — 你还不知道想要什么 | 探索工作流 |
| 微小改动，仅涉及单文件 | 直接做 |
决策启发式规则
问问自己："如果研究阶段发现了严重问题，我是否庆幸没有先花 2 天时间实现？"
如果答案是肯定的，就运行 RPI。研究阶段通常需要 30-60 分钟，却能节省数小时工作量。
关卡如何运作
RPI 有两个人工关卡和每个实现步骤一个自动关卡。
Plain
[想法]
|
v
[阶段一：研究]
|
+- NO-GO -> 停止。记录原因。归档 RESEARCH.md。
|
+- GO -------------------------------------------------------->
|
[阶段二：计划]
|
+- 需要修改 -> 与 Claude 迭代
|
+- 已批准 -------------------------------->
|
[阶段三：实现]
步骤 1 -> 测试关卡
步骤 2 -> 测试关卡
步骤 3 -> 测试关卡
|
[完成]关卡 1（研究后）：你阅读 RESEARCH.md 并做出 GO/NO-GO 决定。这是最重要的关卡——它能防止完全构建错误的东西。
关卡 2（计划后）：你在编写任何代码前审查 PLAN.md。轻微修改在此处以零成本完成。
步骤关卡（实现期间）：每个实现步骤必须通过测试，Claude 才会进入下一步。自动化执行，除非步骤失败，否则无需人工干预。
阶段一：研究
研究内容
研究阶段回答五个问题：
- 现有什么？ 代码库中的相关代码、库、之前的尝试
- 需要构建什么？ 范围边界，要创建还是要修改的组件
- 有哪些风险？ 技术、安全、集成、性能方面的风险
- 有哪些决策点？ 影响整体计划的架构选择
- 工作量估算是多少？ 在承诺计划前进行粗略评估
Claude 探索代码库，阅读相关文件，检查依赖项，并揭示任何可能改变计划的约束条件。结果保存为 RESEARCH.md。
启动研究
创建功能文件夹并启动研究：
Bash
mkdir -p .claude/features/[feature-name]然后在 Claude 中：
Plain
/rpi:research [功能描述]或不使用斜杠命令：
Plain
为以下功能运行 RPI 阶段一（研究）：[功能描述]
将输出保存到 .claude/features/[feature-name]/RESEARCH.md
使用计划模式探索，不要修改任何代码。RESEARCH.md 模板
Markdown
# 研究：[功能名称]
**日期**：[YYYY-MM-DD]
**需求**：[一句话描述该功能]
**状态**：待决策
---
## 当前现状
### 相关代码
- [文件路径]：[功能说明及重要性]
- [文件路径]：[功能说明及重要性]
### 相关库
- [库名]：[当前使用中 / 可用 / 需要新增]
### 之前的尝试或相关工作
- [现有的部分实现、相关 PR、代码库中的说明]
---
## 需要构建的内容
### 新文件
- [文件路径]：[用途]
- [文件路径]：[用途]
### 需要修改的文件
- [文件路径]：[改动内容及原因]
### 外部依赖
- [依赖项]：[需要的原因，如有版本约束请注明]
---
## 风险
| 风险 | 可能性 | 影响 | 备注 |
|------|-----------|--------|-------|
| [风险描述] | 低/中/高 | 低/中/高 | [缓解措施或阻断因素] |
---
## 架构决策点
开始计划前需要做出决策的问题：
1. **[决策]**：选项 A（优点：X，缺点：Y）vs 选项 B（优点：X，缺点：Y）
2. **[决策]**：[选项及权衡]
---
## 工作量估算
- 研究到计划：[时间]
- 实现：[时间范围]
- 测试：[时间]
- **总估算**：[范围]
**估算置信度**：低 / 中 / 高
**原因**：[置信度级别的理由]
---
## 建议
[GO / NO-GO / 需要澄清]
[1-3 句话说明建议理由]
---
**决策**：[ ] GO [ ] NO-GO [ ] 需要澄清
**备注**：[人工填写]NO-GO 的样子
并非每次研究都以 GO 结束。常见的 NO-GO 原因：
- 技术阻断：外部 API 不支持所需操作
- 发现范围蔓延："简单功能"原来需要重写认证层
- 存在更好的替代方案：研究发现现有的库或配置变更能更简单地解决问题
- 当前时机风险过高：功能本身有效，但时机不对
归档 NO-GO 研究文档——它们是关于已做决策及原因的宝贵记录。
阶段二：计划
计划内容
只有在你将 RESEARCH.md 标记为 GO 后，阶段二才会开始。Claude 阅读研究文档并生成精确的实现计划。
一份好的计划应足够具体，使另一位工程师（或新会话中的 Claude）无需提问就能执行。
Plain
/rpi:plan .claude/features/[feature-name]/RESEARCH.md或不使用斜杠命令：
Plain
使用以下内容运行 RPI 阶段二（计划）：
- 研究文档：.claude/features/[feature-name]/RESEARCH.md
将输出保存到 .claude/features/[feature-name]/PLAN.md
暂时不要编写任何代码，仅输出计划。PLAN.md 模板
Markdown
# 计划：[功能名称]
**日期**：[YYYY-MM-DD]
**研究文档**：[RESEARCH.md 链接]
**估算工作量**：[来自研究阶段]
**风险级别**：低 / 中 / 高
---
## 摘要
[2-4 句话：实现内容、主要设计决策、不包含的内容]
---
## 架构决策
[记录研究决策点中做出的决定]
1. **[决策]**：选择了 [选项]，原因是 [理由]
2. **[决策]**：选择了 [选项]，原因是 [理由]
---
## 实现步骤
步骤必须是顺序的，且可独立测试。
### 步骤 1：[名称]
**文件**：[要创建或修改的文件列表]
**构建内容**：[精确描述]
**测试关卡**：[在步骤 2 开始前必须通过的具体测试或检查]
### 步骤 2：[名称]
**文件**：[要创建或修改的文件列表]
**构建内容**：[精确描述]
**测试关卡**：[在步骤 3 开始前必须通过的具体测试或检查]
[...所有步骤以此类推]
---
## 成功标准
- [ ] [可测试的标准——描述可观测行为，而非实现细节]
- [ ] [可测试的标准]
- [ ] 所有步骤测试关卡通过
---
## 超出范围
明确列出本计划不涵盖的内容：
- [排除的内容]
- [排除的内容]
---
## 已接受的风险
[来自 RESEARCH.md 的风险，列出已接受的风险及其缓解方式]
---
## 回滚计划
若实现中途失败：
- [需要撤销的内容]
- [如何恢复到之前的状态]
---
**计划是否批准？** [ ] 是 — 继续实现
**修改备注**：[如需修改，人工填写]审查计划
批准前请仔细阅读 PLAN.md。目标是现在发现设计问题，而不是在实现过程中。需要重点检查：
- 实现步骤顺序是否正确，是否存在隐藏的依赖关系
- 测试关卡是否具体且可执行（而不是"看起来没问题"这类描述）
- 超出范围的内容是否明确（防止 Claude 过度构建）
- 涉及数据或共享状态的操作是否有回滚计划
如果计划需要修改，请在批准前让 Claude 修订。这是免费的——批准后再修订会消耗实现时间。
阶段三：实现
步骤关卡模式
实现逐步进行，每步都有测试关卡。Claude 在当前关卡通过前不会开始下一步。
Plain
/rpi:implement .claude/features/[feature-name]/PLAN.md或不使用斜杠命令：
Plain
使用以下内容运行 RPI 阶段三（实现）：
- 计划文档：.claude/features/[feature-name]/PLAN.md
规则：
- 每次只实现一个步骤
- 每步结束后，运行计划中指定的测试关卡
- 在测试关卡通过前不得开始下一步
- 如果测试关卡失败，停止并报告失败——不要自行修复
- 每步通过后提交实现过程中会发生什么
Claude 按顺序执行计划中的步骤。对于每个步骤：
- 实现指定的文件和变更
- 运行测试关卡（单元测试、集成检查或人工验证）
- 若关卡通过：以引用该步骤的提交信息提交，宣布准备好进入下一步
- 若关卡失败：报告失败、具体的测试输出和可能的原因。在你确认前不尝试修复。
步骤提交模式为你提供了与计划对应的清晰 git 历史。如果步骤 4 出了问题，你可以干净地回滚到步骤 3 的提交。
步骤关卡失败协议
当测试关卡失败时，Claude 报告：
Plain
步骤 [N] 关卡失败。
关卡：[本应通过的内容]
输出：
[实际测试输出]
可能原因：[Claude 的诊断]
选项：
1. 修复：[可能解决问题的具体变更]
2. 修订计划：[如果计划步骤本身有缺陷]
3. 停止并调查：[如果失败揭示了意外情况]
我应该怎么做？由你决定。Claude 不会自行修复后继续——那样会导致实现偏离计划。
斜杠命令模板
将这些保存到 .claude/commands/ 以直接调用每个阶段。
/rpi:research
保存到 .claude/commands/rpi-research.md：
Markdown
# RPI 阶段一：研究
为所请求的功能进行可行性研究。
## 指令
1. 进入计划模式（研究期间不修改文件）
2. 探索代码库以回答以下问题：
- 现有哪些相关内容？
- 哪些文件需要修改或创建？
- 技术风险是什么？
- 在计划之前需要做哪些决策？
- 粗略工作量估算是多少？
3. 使用以下模板将输出保存到 `.claude/features/$ARGUMENTS/RESEARCH.md`
4. 以明确的建议结束：GO、NO-GO 或需要澄清
5. 在继续之前询问用户的 GO/NO-GO 决定
## 约束
- 不得编写任何代码
- 不得修改任何文件
- 不得开始规划实现步骤
- 如果对范围不确定，请将其作为决策点提出/rpi:plan
保存到 .claude/commands/rpi-plan.md：
Markdown
# RPI 阶段二：计划
基于已批准的研究创建实现计划。
## 前置检查
开始前：
1. 阅读 $ARGUMENTS 中指定的 RESEARCH.md 文件
2. 验证其中标记了 GO 决策
3. 如果未找到 GO 决策，停止并请用户先做决定
## 指令
1. 仔细阅读 RESEARCH.md
2. 在同一功能文件夹中创建 PLAN.md
3. 架构决策：解决研究中所有的决策点
4. 实现步骤：每步必须有具体的测试关卡
5. 成功标准：可观测、可测试，不依赖内部实现细节
6. 超出范围：明确列出本计划不涵盖的内容
7. 不得编写任何实现代码
8. 写完计划后，请用户审查并批准
## 约束
- 不得编写实现代码
- 步骤必须是顺序的且可独立测试
- 测试关卡必须是可运行的命令或精确的人工检查，不能是模糊描述
- 每步应在单个专注的会话中可完成/rpi:implement
保存到 .claude/commands/rpi-implement.md：
Markdown
# RPI 阶段三：实现
按照已批准的计划逐步实现功能。
## 前置检查
开始前：
1. 阅读 $ARGUMENTS 中指定的 PLAN.md 文件
2. 验证其中标记了批准
3. 如果未找到批准，停止并请用户先批准
## 指令
对计划中的每个步骤：
1. 仔细阅读步骤描述
2. 仅实现步骤中指定的内容——不多也不少
3. 严格按照计划中写明的方式运行测试关卡
4. 若关卡通过：
- 以这样的提交信息提交："feat([feature]): 步骤 [N] — [步骤名称]"
- 宣布步骤完成及准备好进入下一步
5. 若关卡失败：
- 报告确切的失败输出
- 诊断可能的原因
- 提供选项（修复、修订计划、停止）
- 等待人工决定后再继续
## 约束
- 绝不跳过测试关卡
- 在当前关卡通过前绝不开始下一步
- 绝不修改当前步骤范围之外的文件
- 如果遇到改变计划的意外情况，停止并报告
- 每步通过后提交——不要等到最后实战示例
需求："为公开 API 端点添加速率限制。"
阶段一：研究输出（简略版）
Markdown
# 研究：API 速率限制
**日期**：2026-03-12
**状态**：待决策
## 当前现状
- `src/middleware/` — 有认证中间件，无速率限制
- `package.json` — 未安装 express-rate-limit，Redis 可用
- `src/routes/api.ts` — 14 个公开端点，未认证路由与已认证路由混合
## 需要构建的内容
- 公开端点的速率限制中间件
- 已认证 vs 未认证用户的不同限制
- 用于分布式速率限制的 Redis 存储（应用运行 3 个实例）
## 风险
| 风险 | 可能性 | 影响 | 备注 |
|------|-----------|--------|-------|
| Redis 连接失败导致所有 API 访问禁用 | 低 | 高 | 需要在 Redis 不可用时回退到内存存储 |
| 速率限制过于激进——破坏现有集成 | 中 | 高 | 需要先调查当前使用模式 |
## 架构决策点
1. **库**：express-rate-limit（维护中，经过实战验证）vs 自定义中间件
2. **受信 IP 的绕过**：是否允许内部服务绕过速率限制？
## 工作量估算
- 实现：2-4 小时
- 测试：2 小时
- **总计**：4-6 小时
**建议**：GO — 标准问题，有好的库选项，主要风险是 Redis 回退，可解决。人工决定：GO。使用 express-rate-limit。暂时不设 IP 绕过。
阶段二：计划（简略版）
Markdown
# 计划：API 速率限制
**风险级别**：中（共享 Redis 状态，有潜力阻断合法流量）
## 架构决策
1. 库：express-rate-limit with rate-limit-redis store
2. 暂时不设 IP 绕过——如果内部服务出问题再重新考虑
3. 未认证：100 次请求/15 分钟。已认证：1000 次请求/15 分钟。
4. Redis 失败回退：内存存储（接受单实例不一致）
## 实现步骤
### 步骤 1：安装依赖并配置 Redis 存储
**文件**：`package.json`、`src/config/rate-limit.ts`
**测试关卡**：`npm install` 完成，`src/config/rate-limit.ts` 无报错地导出配置
### 步骤 2：实现速率限制中间件
**文件**：`src/middleware/rate-limit.ts`
**测试关卡**：单元测试——限制器在 15 分钟内阻断来自同一 IP 的第 101 个请求
### 步骤 3：应用到路由
**文件**：`src/routes/api.ts`
**测试关卡**：集成测试——未认证路由在 100 次请求后返回 429；已认证路由不受影响
### 步骤 4：添加 Redis 回退
**文件**：`src/config/rate-limit.ts`
**测试关卡**：在 Redis 不可用时测试——API 仍正常响应（200，而非 500），内存限制生效人工审查：已批准。
阶段三：实现
Claude 实现步骤 1，运行关卡（npm install + 导入检查），提交 feat(rate-limit): step 1 — dependencies and config。然后按顺序执行步骤 2、3、4。每次提交都是干净的，每个关卡必须通过才能继续。
与其他工作流的对比
| 工作流 | 阶段结构 | 人工关卡 | 最适合 |
|---|---|---|---|
| RPI | 研究 + 计划 + 实现 | GO/NO-GO + 计划批准 | 可行性未知、超过 1 天、方向错误风险高 |
| 双实例 | 计划 + 实现（独立 Claude 实例） | 计划批准 | 已知功能需精细执行、规范密集型工作 |
| 规范先行 | 规范 + 实现 | 无（规范是隐式关卡） | 以设计为导向、API 契约、团队对齐 |
| TDD | 测试先行 + 实现 | 无（测试是关卡） | 测试覆盖率驱动、重构、增量行为 |
| 直接编码 | 无 | 无 | 简单变更、范围明确、不超过 2 小时 |
RPI vs 双实例
双实例将计划和实现分为两个 Claude 实例，严格执行角色分工。当你已经知道要构建什么并想要高质量计划时效果很好。RPI 在计划前增加了可行性阶段，更适合模糊的需求。如果你已有明确的规范，跳过研究阶段，使用双实例或规范先行即可。
RPI vs 规范先行
规范先行以设计为导向：你定义系统应该做什么，然后 Claude 实现它。RPI 以实现为导向，带有验证关卡：你描述目标，Claude 研究如何实现，然后你们在接触代码前就计划达成共识。设计清晰时用规范先行，技术路径不明时用 RPI。
RPI vs 直接编码
对于所有范围清晰、不超过 2 小时的任务，直接让 Claude 去做就好。RPI 增加的开销对小任务并不合算。仅研究阶段就需要 30-60 分钟。这个开销在多天功能开发中才值得，因为晚期发现错误假设的代价要昂贵得多。
技巧与故障排查
Claude 在研究阶段跳到了实现
问题：Claude 在研究阶段开始编写代码。
解决方案：明确为研究阶段启用计划模式（按两次 Shift+Tab）。在研究命令中包含这行：
Plain
你处于计划模式。不要修改文件。不要编写实现代码。
仅进行研究。输出写入 RESEARCH.md。或添加到你的 CLAUDE.md：
Markdown
## RPI 规则
- /rpi:research 仅在计划模式下运行——不修改文件
- /rpi:plan 仅生成 PLAN.md——不编写实现代码
- /rpi:implement 每次只实现一步，等待测试关卡通过后才进入下一步研究阶段时间过长
问题：Claude 探索了整个代码库，而不是专注于相关内容。
解决方案：明确限定研究范围：
Plain
/rpi:research payment-processing
关注范围：src/payments/、src/routes/checkout.ts
不要探索：前端、认证、无关的后端模块
时间预算：在一个会话中完成研究计划步骤过多
问题：PLAN.md 有 12 个步骤，导致实现难以管理。
解决方案：超过 6-8 个步骤的计划通常需要缩减范围，而不是更细粒度的实现。让 Claude：
Plain
计划的步骤太多了。能交付核心价值的最小可行范围是什么？
修改计划，只实现那部分内容，并在"未来工作"章节中列出其余内容。测试关卡描述模糊
问题：某步骤的测试关卡写的是"验证它可以工作"，而不是具体命令。
解决方案：在批准计划前拒绝模糊的关卡。这样反驳：
Plain
步骤 3 的测试关卡是"验证速率限制有效"。请具体说明：
我运行什么命令，通过时我预期看到什么输出？好的测试关卡：
Plain
测试关卡：`npm test src/middleware/rate-limit.test.ts` — 全部 4 个测试通过坏的测试关卡：
Plain
测试关卡：速率限制正常工作某步骤关卡反复失败
问题：步骤 2 的关卡在尝试修复后仍一直失败。
解决方案：两次失败意味着要调查计划，而不是继续迭代修复。
Plain
停止实现。步骤 2 的关卡已失败两次。
回顾计划——考虑到步骤 1 的输出，该测试关卡是否可以实现？
在继续之前我们是否需要修订计划？文件结构摘要
Plain
.claude/
└── features/
└── [feature-name]/
├── RESEARCH.md # 阶段一输出（人工标注 GO/NO-GO）
└── PLAN.md # 阶段二输出（人工标注批准）
.claude/commands/
├── rpi-research.md # /rpi:research 斜杠命令
├── rpi-plan.md # /rpi:plan 斜杠命令
└── rpi-implement.md # /rpi:implement 斜杠命令归档已完成的功能：
Bash
mkdir -p .claude/features/_archive
mv .claude/features/payment-processing .claude/features/_archive/归档是一份学习资源：已完成的 RESEARCH.md 和 PLAN.md 展示了之前如何思考各个功能。
参见
- 双实例计划工作流 — 规范密集型实现的双实例模式
- 规范优先开发 — 使用 CLAUDE.md 作为契约的设计优先工作流
- 使用 Claude Code 进行 TDD — 与 TDD 结合实现测试关卡驱动
- 任务管理工作流 — 跨会话管理多阶段任务
- 模块 07：高级模式 — 多实例与计划模式概述
来源：飞书 · AI Spark 知识库 ｜ 原文（最新版）：https://lcnniolukk80.feishu.cn/wiki/ArcuwI6akiAumLkNG1zctPnincd ｜ 归档：2026-06-04