名称: 研究-计划-实施描述: 强制执行一个三阶段RPI工作流程（研究、计划、实施）用于代码变更。在处理中到大型代码库中的非平凡功能、重构或错误修复时使用，以防止上下文浪费并确保正确性优先于速度。

研究-计划-实施 (RPI)

一种disciplined的三阶段工作流程，以速度换取清晰度、可预测性和正确性。每个阶段都有一个验证门，必须通过才能继续。

核心原则: 绝不让AI在未先研究代码库并产生验证计划的情况下编写代码。一页计划比审查1000行AI代码提供10倍的杠杆作用。

何时使用

非平凡功能、重构或错误修复
不熟悉或大型代码库
错误代码成本高于慢速代码的任务
当之前的直接实施尝试失败时

何时不使用

单行修复、拼写错误或琐碎更改
您已有完整上下文和清晰路径的任务
探索性原型制作（在固化原型时使用RPI）

工作流程

复制此检查清单并跟踪进度：

- [ ] 阶段1: 研究 (FAR验证)
- [ ] 阶段2: 计划 (FACTS验证)
- [ ] 阶段3: 实施 (验证)

阶段1: 研究

目标: 探索代码库，找到正确的文件。进行零修改。

使用子代理（Task工具，类型Explore）进行广泛阅读，而不污染主要上下文。子代理仅返回压缩事实。

研究输出

对于每个发现，记录：

文件路径和行号
什么存在那里（函数签名、数据结构、模式）
为什么它对当前任务重要

FAR验证门

每个发现必须通过所有三个：

检查	问题	失败示例
F实际性	这是来自实际代码，不是假设吗？	“可能有个配置文件在某个地方”
A可操作性	是否包括具体文件路径+行号？	“认证模块处理这个”
R相关性	是否直接与任务相关？	记录无关的实用函数

研究总结模板:

## 研究结果: {任务描述}

### 发现1: {简短标题}
- **文件**: `src/auth/middleware.ts:42-67`
- **什么**: `validateToken()`检查JWT过期和角色声明
- **为什么**: 我们需要扩展这个以支持API密钥认证

### 发现2: {简短标题}
- **文件**: `src/types/auth.ts:15-23`
- **什么**: `AuthContext`接口定义`user`、`token`、`roles`
- **为什么**: 必须在此处添加`apiKey`字段

### FAR检查
- [x] 所有发现引用带路径和行号的实际代码
- [x] 不包括假设或猜测
- [x] 每个发现直接与任务相关

在FAR通过之前不要进入阶段2。

阶段2: 计划

目标: 产生一个逐步计划，其中每个步骤都有代码级特异性。

没有代码片段的计划只是一个“感觉”——它没有执行能力。

计划结构

对于每个步骤：

### 步骤N: {动作动词} + {什么}

**文件**: `路径/到/文件.ts:行范围`
**更改**: {精确描述要添加/修改/删除什么}
**代码草图**:
  ```typescript
  // 之前（当前）:
  function validateToken(token: string): AuthContext { ... }

  // 之后（计划）:
  function validateAuth(credential: string | ApiKey): AuthContext { ... }

验证: {如何确认此步骤成功} 范围: 仅更改validateToken签名和主体。尚未触及调用者。


### FACTS验证门

每个步骤必须通过所有五个：

| 检查 | 问题 | 失败示例 |
|-------|----------|-------------|
| **F**可行性 | 这能在当前环境中完成吗？ | “迁移到新框架”中途任务 |
| **A**原子性 | 它是否只做一件事？ | “更新认证和重构测试” |
| **C**清晰性 | 是否有文件名、行号和代码片段？ | “更新相关文件” |
| **T**可测试性 | 是否有具体验证步骤？ | “确保它工作” |
| **S**范围性 | 是否清楚什么更改和什么不更改？ | 无边界提及 |

**FACTS检查清单**:

```markdown
### FACTS验证
- [ ] F: 每个步骤在当前环境中可实现
- [ ] A: 每个步骤有恰好一个目标
- [ ] C: 每个步骤有文件路径、行号和代码草图
- [ ] T: 每个步骤有具体验证命令或检查
- [ ] S: 每个步骤说明它更改什么AND它留下什么不变

在FACTS通过之前不要进入阶段3。

向用户展示计划

在FACTS验证后，向人类审查展示计划。计划是主要的审查工件——审查计划比审查生成代码更高效。

阶段3: 实施

目标: 以最小上下文压力执行验证计划。

执行规则

逐步遵循计划——不要即兴发挥或“改进”超出范围
一次一步——在下一步之前完成并验证每一步
对独立步骤使用子代理——保持主要上下文精简
每一步后验证——运行计划中定义的验证

每一步后

步骤N: {标题}
- 状态: 完成 / 阻塞 / 修改
- 验证: {验证步骤的结果}
- 偏差: {无，或解释为什么计划被调整}

如果步骤失败

不要盲目重试——诊断为什么失败
用新信息更新计划
重新验证FACTS在更新步骤上
如果连续3+步骤失败，停止——参见升级

意图压缩

当对话变长或开始偏离轨道（大约20+轮后）：

停止所有实施工作
总结关键研究发现和计划状态为压缩格式：

## 压缩上下文: {任务}

### 验证事实
- {带文件路径和行号的事实1}
- {带文件路径和行号的事实2}

### 计划状态
- 完成步骤: {列表}
- 当前步骤: {N} - {状态}
- 剩余: {列表}

### 阻塞
- {任何未解决的问题}

开始新对话用此压缩上下文

更好输入产生更好输出。带压缩事实的新鲜上下文胜过带噪声的臃肿上下文。

子代理策略

子代理是分片工具，不是角色。使用它们来：

任务	代理类型	返回
广泛代码库阅读	`Explore`	压缩文件/函数映射
目标搜索	`Explore`	具体路径和行号
独立实施步骤	`Bash`或`general-purpose`	步骤完成状态
测试执行	`Bash`	通过/失败带输出

规则:

子代理做重读；主代理做推理
子代理返回压缩事实，不是原始文件内容
绝不让主要上下文吸收整个文件当子代理能提取相关行时

升级

当RPI计划反复失败（连续3+步骤失败），这表示任务复杂性超过AI在当前上下文中能处理的范围。

行动: 停止。返回白板。人类必须重新思考方法并不同地分解问题，然后重新使用AI。

不要通过重复失败蛮力推进——那浪费上下文并产生坏代码。

名称: 研究-计划-实施 描述: 强制执行一个三阶段RPI工作流程（研究、计划、实施）用于代码变更。在处理中到大型代码库中的非平凡功能、重构或错误修复时使用，以防止上下文浪费并确保正确性优先于速度。