⚡

迭代开发技能（RalphWiggum集成） iterative-development

这是一种基于自我参照开发循环的技能，通过重复迭代同一任务直到满足预定义的完成标准，适用于测试驱动开发（TDD）场景，强调失败是数据的一部分，用于指导下一次迭代，以实现代码的逐步完善和优化。

测试 0 次安装 0 次浏览 更新于 3/5/2026

迭代开发技能（Ralph Wiggum集成）

加载：base.md

**概念：**自我参照的开发循环，其中Claude在同一任务上迭代，直到满足完成标准。基于Ralph Wiggum插件。

核心理念

┌─────────────────────────────────────────────────────────────┐
│  迭代 > 完美                                         │
│ ─────────────────────────────────────────────────  │
│  不要第一次尝试就追求完美。                        │
│  让循环来完善工作。每次迭代都建立在     │
│  文件和git历史中可见的先前尝试之上。        │
├─────────────────────────────────────────────────────────────┤
│  失败是数据                                          │
│  ─────────────────────────────────────────────────  │
│  失败的测试、lint错误、类型不匹配是信号。    │
│  用它们来指导下一次迭代。                      │
├─────────────────────────────────────────────────────────────┤
│  清晰的完成标准                                      │
│  ─────────────────────────────────────────────────  │
│  明确定义“完成”是什么样子。                     │
│  测试通过。覆盖率满足。Lint清晰。                   │
│  何时停止没有歧义。                           │
└─────────────────────────────────────────────────────────────┘

安装Ralph Wiggum插件

# 克隆插件
git clone https://github.com/anthropics/claude-code.git /tmp/claude-code
cp -r /tmp/claude-code/plugins/ralph-wiggum ~/.claude/plugins/

# 或添加到项目本地插件
mkdir -p .claude/plugins
cp -r /tmp/claude-code/plugins/ralph-wiggum .claude/plugins/

工作原理

┌─────────────────────────────────────────────────────────────┐
│  1. /ralph-loop "您的任务提示" --max-iterations 20      │
├─────────────────────────────────────────────────────────────┤
│  2. Claude处理任务                                    │
├─────────────────────────────────────────────────────────────┤
│  3. Claude尝试退出                                 │
├─────────────────────────────────────────────────────────────┤
│  4. 停止钩子阻止退出，反馈相同的提示           │
├─────────────────────────────────────────────────────────────┤
│  5. Claude看到修改过的文件+之前的git历史    │
├─────────────────────────────────────────────────────────────┤
│  6. Claude迭代并改进                            │
├─────────────────────────────────────────────────────────────┤
│  7. 循环继续直到：                                   │
│     • 完成承诺检测：<promise>DONE</promise>  │
│     • 达到最大迭代次数                                │
└─────────────────────────────────────────────────────────────┘

关键洞见： 提示从未改变。只有文件状态演变。Claude阅读之前的工作并加以改进。

TDD集成提示模板

功能开发（TDD循环）

/ralph-loop "
## 任务：[功能名称]

### 需求
- [需求1]
- [需求2]
- [需求3]

### TDD工作流程（必须遵循）
1. 根据需求编写失败的测试
2. 运行测试 - 验证它们失败（红色阶段）
3. 实施最小代码以通过测试
4. 运行测试 - 验证它们通过（绿色阶段）
5. 运行lint和类型检查
6. 如果有任何失败，调试并修复
7. 重复直到全部变绿

### 完成标准
- [ ] 所有测试通过
- [ ] 覆盖率>=80%
- [ ] Lint清晰（无错误）
- [ ] TypeScript/类型检查通过

### 退出条件
当上述所有标准为真时，输出：
<promise>所有测试通过且Lint清晰</promise>
" --completion-promise "所有测试通过且Lint清晰" --max-iterations 30

错误修复（TDD循环）

/ralph-loop "
## 错误：[错误描述]

### 重现
1. [步骤1]
2. [步骤2]
3. 观察：[错误行为]
4. 预期：[正确行为]

### TDD错误修复工作流程（必须遵循）
1. 运行现有测试 - 注意是否有任何捕获到错误
2. 编写一个失败的测试来重现错误
3. 运行测试 - 验证它失败（证明测试捕获到错误）
4. 用最小代码更改修复错误
5. 运行测试 - 验证它通过
6. 运行完整测试套件以检查回归
7. 运行lint和类型检查
8. 如果有任何失败，调试并修复
9. 重复直到全部变绿

### 完成标准
- [ ] 新的错误测试存在
- [ ] 新测试通过
- [ ] 所有现有测试通过
- [ ] 无回归
- [ ] Lint清晰

### 退出条件
当所有标准为真时，输出：
<promise>错误修复并测试</promise>
" --completion-promise "错误修复并测试" --max-iterations 25

重构（安全循环）

/ralph-loop "
## 重构：[要重构的内容]

### 目标
- [目标1：例如，提取函数，降低复杂性]
- [目标2：例如，改进命名]
- [目标3：例如，如果>200行则拆分文件]

### 安全约束
- 所有现有测试必须继续通过
- 无行为更改（仅重构）
- 覆盖率不得降低

### 工作流程
1. 运行所有测试 - 建立基线（必须通过）
2. 进行一次重构更改
3. 运行测试 - 必须仍然通过
4. 运行lint和类型检查
5. 如果失败，回退并尝试不同的方法
6. 提交工作的重构
7. 重复下一个更改

### 完成标准
- [ ] 所有重构目标达成
- [ ] 所有测试通过
- [ ] 覆盖率相同或更高
- [ ] Lint清晰

### 退出条件
<promise>重构完成所有测试绿色</promise>
" --completion-promise "重构完成所有测试绿色" --max-iterations 20

API开发

/ralph-loop "
## 任务：构建[API名称]API

### 需要的端点
- POST /api/resource - 创建
- GET /api/resource - 列表
- GET /api/resource/:id - 获取一个
- PUT /api/resource/:id - 更新
- DELETE /api/resource/:id - 删除

### 需求
- 输入验证（Zod/Pydantic）
- 错误处理与适当的状态代码
- 每个端点的测试
- OpenAPI/Swagger文档

### TDD工作流程
1. 为每个端点编写集成测试
2. 运行测试 - 都应该失败
3. 逐一实现端点
4. 实现每个端点后运行测试
5. 继续直到全部通过
6. 添加验证和错误处理
7. 运行完整测试套件
8. 生成API文档

### 完成标准
- [ ] 所有端点测试通过
- [ ] 输入验证工作
- [ ] 错误响应正确
- [ ] 覆盖率>=80%
- [ ] Lint清晰

### 退出条件
<promise>API完成并通过测试</promise>
" --completion-promise "API完成并通过测试" --max-iterations 40

提示编写规则

1. 清晰的完成标准（必需）

❌ 差："构建一个待办事项API并使其变得很好。"

✅ 好：
### 完成标准
- [ ] CRUD端点实现
- [ ] 所有测试通过
- [ ] 输入验证工作
- [ ] 覆盖率>=80%
- [ ] Lint清晰

### 退出条件
<promise>所有测试通过</promise>

2. 总是设置最大迭代次数

# ❌ 危险 - 永远运行
/ralph-loop "构建某物"

# ✅ 安全 - 30次迭代后停止
/ralph-loop "构建某物" --max-iterations 30

3. 在每个提示中包含TDD

### TDD工作流程（必须遵循）
1. 首先编写失败的测试
2. 验证测试失败
3. 实施功能
4. 验证测试通过
5. 运行lint + 类型检查
6. 如果失败，重复

4. 将大型任务分成阶段

## 第一阶段：认证
- [ ] 登录端点与JWT
- [ ] 测试通过
- 输出：<promise>认证完成</promise>

## 第二阶段：用户CRUD（第一阶段后）
- [ ] 用户端点
- [ ] 测试通过
- 输出：<promise>用户完成</promise>

## 第三阶段：产品（第二阶段后）
...

5. 包括后备行为

### 如果15次迭代后卡住
- 记录阻碍进度的内容
- 列出尝试过的方法
- 建议替代方法
- 输出：<promise>需要帮助</promise>

错误分类（循环至关重要）

并非所有的测试失败都是平等的。Claude必须在迭代前对错误进行分类。

错误类型

类型 示例 Claude可以修复？ 行动
代码错误 逻辑错误，错误的算法，缺少验证 ✅ YES 继续循环
类型错误 错误的类型，缺少属性 ✅ YES 继续循环
测试错误 错误的断言，不完整的测试 ✅ YES 继续循环
访问错误 缺少API密钥，数据库连接被拒绝 ❌ NO 停止 + 报告
权限错误 文件访问被拒绝，身份验证失败 ❌ NO 停止 + 报告
环境错误 缺少依赖，错误的Node版本 ❌ NO 停止 + 报告
网络错误 服务无法到达，超时 ❌ NO 停止 + 报告

错误检测模式

### 每次迭代前

1. 运行测试
2. 如果测试失败，对错误进行分类：

   **代码/逻辑错误？**（Claude可以修复）
   - "预期X但收到Y"
   - "TypeError:不能读取属性"
   - "AssertionError"
   → 继续循环

   **访问/环境错误？**（人类必须修复）
   - "ECONNREFUSED"（数据库未运行）
   - "401 Unauthorized"（API密钥错误/缺失）
   - "ENOENT"（文件/路径未找到）
   - "EACCES"（权限被拒绝）
   - "MODULE_NOT_FOUND"（缺少包）
   - "连接超时"
   → 停止循环 + 输出阻塞器

阻塞器报告格式

当Claude检测到访问/环境错误时，立即输出此内容：

## 🛑 循环阻塞 - 需要人类行动

**错误类型：** 访问/环境（无法通过代码更改修复）

**错误消息：**

ECONNREFUSED 127.0.0.1:5432 - 连接被拒绝


**根本原因：**
PostgreSQL数据库未运行或无法访问。

**需要的人类行动：**
1. [ ] 启动PostgreSQL：`brew services start postgresql`
2. [ ] 验证连接：`psql -U postgres -c "SELECT 1"`
3. [ ] 检查.env中的DATABASE_URL是否与运行实例匹配

**修复后：**
再次运行`/ralph-loop`与相同的提示，或告诉我继续。

<promise>阻塞环境</promise>

常见阻塞器检查表

错误模式 可能的原因 人类修复
ECONNREFUSED :5432 PostgreSQL未运行 brew services start postgresql
ECONNREFUSED :6379 Redis未运行 brew services start redis
ECONNREFUSED :27017 MongoDB未运行 brew services start mongodb
401 Unauthorized 无效/缺失的API密钥 检查.env文件
403 Forbidden 错误的权限/范围 检查API密钥权限
ENOENT .env 缺少.env文件 从.env.example创建
MODULE_NOT_FOUND 缺少npm包 运行npm install
ENOMEM 内存不足 关闭其他应用程序，增加交换空间

带有错误处理的更新提示模板

/ralph-loop "
## 任务：[功能名称]

### 需求
- [需求在这里]

### TDD工作流程
1. 编写失败的测试
2. 运行测试
3. **对错误进行分类：**
   - 代码/逻辑错误 → 修复并继续
   - 访问/环境错误 → 停止并报告阻塞器
4. 实施修复
5. 再次运行测试
6. 重复直到通过或阻塞

### 完成标准
- [ ] 所有测试通过
- [ ] Lint清晰

### 退出条件
- 成功：<promise>功能完成</promise>
- 阻塞：<promise>阻塞环境</promise>
" --completion-promise "功能完成" --max-iterations 25

多个完成承诺

由于Ralph只支持一个--completion-promise，处理阻塞器在提示中：

### 退出逻辑
如果所有测试通过且Lint清晰：
  输出：<promise>完成</promise>

如果检测到访问/环境错误：
  输出阻塞器报告（见上述格式）
  输出：<promise>完成</promise>  # 退出循环，用户看到阻塞器报告

何时使用Ralph循环

适用情况

用例 为何有效
TDD功能开发 测试提供清晰的通过/失败反馈
错误修复 清晰的重现 → 测试 → 修复周期
重构 测试确保无回归
API开发 每个端点都可以独立测试
绿地项目 可以在没有人类监督的情况下迭代
使测试通过 清晰的成功标准

不适用情况

用例 为何失败
主观设计决策 没有清晰的“完成”标准
UI/UX工作 需要人类判断
一次性操作 不需要迭代
不明确的要求 将永远循环
生产调试 需要人类监督

监控和控制

查看当前迭代

grep '^iteration:' .claude/ralph-loop.local.md

查看完整状态

head -10 .claude/ralph-loop.local.md

取消循环

/cancel-ralph

状态文件位置

.claude/ralph-loop.local.md

与Claude引导集成

项目结构添加

project/
├── _project_specs/
│   └── ralph-prompts/           # 保存的Ralph提示
│       ├── feature-template.md
│       ├── bug-fix-template.md
│       └── refactor-template.md
└── .claude/
    └── ralph-loop.local.md      # 活动循环状态（gitignored）

Gitignore添加

# Ralph循环状态（会话特定）
.claude/ralph-loop.local.md

待办事项集成

## [TODO-042] 添加电子邮件验证

**状态：** 进行中
**方法：** Ralph循环

### Ralph提示
/ralph-loop "..." --max-iterations 20 --completion-promise "..."

### TDD执行日志
| 迭代 | 测试 | Lint | 状态 |
|-----------|-------|------|--------|
| 1 | 0/5通过 | 错误 | 红色 |
| 2 | 2/5通过 | 错误 | 红色 |
| 3 | 5/5通过 | 清晰 | 绿色 ✓ |

### 完成
- 迭代使用：3/20
- 检测到的承诺：<promise>所有测试通过</promise>

反模式

  • ❌ 没有最大迭代次数 - 循环永远运行
  • ❌ 不明确的完成标准 - 无法确定何时完成
  • ❌ 提示中没有TDD - 没有客观的成功度量
  • ❌ 撒谎以退出 - 输出虚假承诺以逃脱
  • ❌ 手动干预 - 循环旨在自治
  • ❌ 跳过测试验证 - 测试必须首先失败

示例：真实的TDD Ralph会话

/ralph-loop "
## 任务：向注册表单添加电子邮件验证

### 需求
- 电子邮件字段显示无效格式的错误
- 用户修复电子邮件时错误清除
- 表单不能用无效的电子邮件提交
- 有效的电子邮件无错误通过

### 测试用例
| 输入 | 预期 |
|-------|----------|
| user@example.com | 有效 |
| user@sub.example.com | 有效 |
| notanemail | 错误 |
| user@ | 错误 |
| @example.com | 错误 |

### TDD工作流程
1. 创建测试文件：signup-validation.test.ts
2. 为上述所有测试用例编写测试
3. 运行：npm test -- --grep 'email validation'
4. 验证：所有5个测试失败（红色）
5. 实施：validateEmail函数
6. 运行：npm test -- --grep 'email validation'
7. 验证：所有5个测试通过（绿色）
8. 运行：npm run lint && npm run typecheck
9. 如果有任何错误，修复并重新运行
10. 当全部变绿时，输出完成

### 完成标准
- [ ] 存在5个电子邮件验证测试
- [ ] 所有5个测试通过
- [ ] Lint清晰
- [ ] 类型检查通过

### 退出条件
<promise>电子邮件验证完成</promise>
" --completion-promise "电子邮件验证完成" --max-iterations 15

清单

Ralph循环开始前

  • [ ] 定义清晰的完成标准
  • [ ] 设置--max-iterations（安全网）
  • [ ] 设置--completion-promise
  • [ ] 提示中包含TDD工作流程
  • [ ] 定义测试用例

循环期间

  • [ ] 监控迭代次数
  • [ ] 每次迭代检查测试结果
  • [ ] 注意卡住的模式

完成后

  • [ ] 验证测试实际上通过
  • [ ] 运行完整测试套件
  • [ ] 检查覆盖率阈值
  • [ ] 提交更改