super-ralph-wiggum

Super Ralph Wiggum

Claude Code 的自主迭代循环。重复运行相同的提示词，直到任务完成；上下文通过文件和 git 历史记录持续保留。

Ralph 理念

由 Agent 选择任务，而不是由你选择。

你定义最终状态。Ralph 会想办法实现它。

在多阶段计划中，人在每个阶段开始时都会编写新的提示词。使用 Ralph 时，Agent 会根据你的 PRD 选择接下来要处理的内容。你描述目的地，Ralph 负责导航。

11 条建议（快速参考）

基于 AI Hero 的权威指南：

#	建议	核心要点
1	Ralph 是一个循环	使用相同提示词进行多次迭代
2	先采用 HITL，再转为 AFK	学习 → 信任 → 放手
3	明确范围	明确的停止条件可防止无限循环
4	跟踪进度	progress.txt 用于衔接不同的上下文窗口
5	使用反馈循环	将类型检查、测试和 lint 作为护栏
6	小步推进	每次提交只做一项逻辑上的更改
7	优先处理高风险任务	先处理架构，最后处理快速见效的任务
8	定义软件质量	告诉 Ralph 这是哪种类型的代码仓库
9	使用 Docker 沙箱	AFK 安全的关键
10	愿意付费	即使不采用 AFK，HITL 仍然有价值
11	按需调整	使用其他循环类型和任务来源

请参阅 @references/tips-and-tricks.md，了解每条建议的详细指南。

快速开始

使用模板启动 Ralph 循环：

Run the super-ralph-wiggum skill with the test-coverage template, max 20 iterations

使用 PRD 文件启动：

Run super-ralph-wiggum with feature-prd template using ./prd.json

可用模板

模板	用途	默认迭代次数
test-coverage	将测试覆盖率提升至目标百分比	30
feature-prd	根据 PRD 文件实现功能	20
lint-fix	逐步修复所有 lint 错误	30
docs-generation	为模块生成文档	25
dataset-generation	生成训练数据样本	50
migration	迁移到新的框架/版本	40
entropy-loop	消除软件熵（死代码、代码异味）	30
duplication-loop	消除重复代码	25

调用方式

模板模式（推荐）

使用预构建模板处理常见任务：

Use super-ralph-wiggum with [template-name] template
Options: --max-iterations N, --browser (for UI verification)

PRD 模式

用于带任务跟踪的结构化功能开发：

Use super-ralph-wiggum with feature-prd template
PRD file: ./prd.json

PRD 文件会通过 passes: true/false 跟踪功能状态。所有功能都通过后，循环即完成。

HITL 模式（单次迭代）

用于交互式学习和结对编程：

Use super-ralph-wiggum with --once flag to [task description]

只运行一次迭代，不会循环。非常适合了解 Ralph 的工作方式。

自定义提示词

用于模板未涵盖的任务：

Use super-ralph-wiggum with custom prompt:
[Your detailed task description with completion criteria]
Completion: Output <promise>COMPLETE</promise> when done
Max iterations: 15

两种模式：HITL 与 AFK

模式	工作方式	适用场景
HITL（人在循环中）	运行一次、观察并进行干预	学习、优化提示词、高风险任务
AFK（离开键盘）	在设定的最大迭代次数内循环运行	批量工作、低风险任务、过夜运行

推进步骤很简单：

1. 先使用 HITL 进行学习和优化
2. 信任提示词后再转为 AFK
3. 返回时检查提交记录

使用 AFK 时，务必设置迭代次数上限：

• 小型任务：5-10 次迭代
• 中型任务：15-30 次迭代
• 大型功能：30-50 次迭代

明确规定软件质量

Ralph 不知道这是一次性原型还是生产代码。告诉它。

代码仓库类型	应说明的要求	预期行为
原型	“速度优先于完美。跳过边缘情况。”	采用捷径
生产代码	“必须易于维护。遵循最佳实践。”	添加测试和文档
库	“这是公共 API。向后兼容很重要。”	谨慎对待破坏性更改

代码质量提示词

如果循环应该保持较高的代码质量，请用客观的标准说明：

遵循现有的代码规范和质量标准。 每次更改都应确保测试覆盖率不低于之前的水平。 优先进行渐进式改进，而非大规模重写。

避免使用激励式表述（“对抗熵增”“务必周全”）——Claude 4.6 本就倾向于面面俱到，这类表述会让它过度规划。明确的质量标准更有效。

以代码仓库为准

你的指令会与代码库相互竞争。当 Ralph 探索代码仓库时，它会看到两个事实来源：你告诉它该怎么做，以及你实际上做了什么。

如果你写了“绝不使用 any 类型”，但 Ralph 发现现有代码中到处都是 any，它会遵循代码库，而不是你的指令。

Claude 会从现有代码库中学习模式。如果代码库到处都使用 any 类型，循环就会照着这种模式执行，不受指令影响。运行循环之前，先清理你在意的特定模式。

任务优先级顺序

选择下一个任务时，Ralph 应按以下优先级排序：

1. 架构决策和核心抽象
2. 模块之间的集成点
3. 未知的未知问题和探索性工作
4. 标准功能和实现
5. 打磨、清理和快速见效的改进

高风险工作应尽早验证。简单易行的改进留到后面。

早期架构决策应使用 HITL Ralph——这些任务产出的代码会一直保留。基础稳固后，再使用 AFK Ralph。

执行模式

1. 会话内模式（默认）

循环通过停止钩子在你当前的 Claude Code 会话内运行：

Use super-ralph-wiggum with test-coverage template, max 20 iterations

• 停止钩子会拦截退出尝试
• 每轮都会重新输入相同的提示词
• 上下文通过文件和 git 持续保留
• 最适合交互式／受监控的工作

2. Docker 化模式（外部）

循环通过 bash 脚本在 Docker 沙箱中外部运行：

# Generate external script
./scripts/setup-ralph-loop.sh --template test-coverage --docker > run-ralph.sh
chmod +x run-ralph.sh

# Run in background
./run-ralph.sh 20 &

• 每轮都会启动一个全新的 Claude Code 实例
• 通过 Docker 隔离来保障安全
• 最适合隔夜／无人值守运行
• 记忆仅通过文件保留

无人值守安全性的关键保障：Docker 沙箱允许 Ralph 编辑项目文件并提交更改，但无法访问你的主目录、SSH 密钥或系统文件。

工作原理

1. 设置：在 .claude/ralph-loop.local.md 创建状态文件
2. 进度：自动在项目根目录创建 progress.txt
3. 循环：停止钩子拦截退出，并重新输入相同的提示词
4. 完成：检测到 <promise>COMPLETE</promise> 或 PRD 中的所有任务均已通过
5. 学习：各轮中积累的模式会保存在 progress.txt 中

关键选项

选项	说明	默认值
--template <name>	使用预置模板	（必填，或使用自定义提示词）
--prd <file>	用于任务跟踪的 PRD 文件	无
--max-iterations <n>	迭代次数上限	因模板而异
--completion-promise <text>	自定义完成短语	COMPLETE
--progress <file>	进度文件位置	./progress.txt
--browser	启用浏览器测试提示词	false
--once	单次迭代（HITL 模式）	false

最佳实践

1. 小型故事

任务必须能在一个上下文窗口内完成。将大型功能拆分为原子化故事。

2. 优先验证

提交前务必运行类型检查和测试。模板会强制执行此要求。

3. 限制迭代次数

对于 AFK（无人值守）Ralph，务必设置 --max-iterations。在随机性系统中，无限循环很危险。

4. 明确完成标准

任务描述含糊可能导致无限循环。应明确说明何时停止。

5. 使用进度文件

上一轮的经验会保留在 progress.txt 中。模板会自动注入这些内容。

6. 每次提交只做一项更改

保持更改小而专注。与其一次提交大量更改，不如分多次提交小改动。

7. 妥善组织状态

使用 JSON 保存结构化进度数据（覆盖率百分比、功能通过/失败状态、迁移数量）。使用 progress.txt 中的自由文本记录观察结果和会话经验。每轮迭代之间使用 git 提交作为检查点，这样每个新的上下文窗口都能从文件系统中获取状态。

参考资料

如需详细指导，请阅读参考文件：

• @references/tips-and-tricks.md - 扩展了 11 条技巧，并融入 AI Hero 的见解
• @references/prompt-patterns.md - 10 种用于收敛提示词的模式
• @references/prd-schema.md - PRD 文件结构与用法
• @references/cost-estimation.md - API 成本指南
• @references/browser-testing.md - Dev-browser 集成

模板详情

test-coverage

通过以下步骤提高测试覆盖率：

1. 运行覆盖率工具以查找遗漏
2. 找出最重要但未经测试的面向用户行为
3. 每轮迭代编写一个有意义的测试
4. 对非必要代码使用 /* v8 ignore */
5. 每次测试成功后提交

阅读完整模板：@templates/test-coverage.md

feature-prd

通过以下步骤根据 PRD 文件实现功能：

1. 读取 prd.json，找到优先级最高的未完成功能
2. 检查依赖项是否已满足
3. 每轮迭代实现一个功能
4. 运行验证（类型检查 + 测试）
5. 将发现的模式更新到 AGENTS.md
6. 将功能标记为 passes: true

阅读完整模板：@templates/feature-prd.md

lint-fix

通过以下步骤修复 lint 错误：

1. 运行 linter 获取错误列表
2. 选择错误最多的文件
3. 修复该文件中的所有错误
4. 验证修复不会导致测试失败
5. 提交后处理下一个文件

阅读完整模板：@templates/lint-fix.md

entropy-loop

通过以下步骤消除软件熵：

1. 扫描代码异味（未使用的导出、死代码、TODO）
2. 每轮迭代修复一个问题
3. 运行验证
4. 在 progress.txt 中记录更改

阅读完整模板：@templates/entropy-loop.md

duplication-loop

通过以下步骤消除重复代码：

1. 运行 jscpd 查找重复代码
2. 找出一组重复代码
3. 将共享代码提取到工具函数/辅助函数中
4. 更新所有调用位置
5. 使用测试进行验证

阅读完整模板：@templates/duplication-loop.md

docs-generation

通过以下步骤生成文档：

1. 找出缺少文档说明的公共函数
2. 每轮迭代编写一份文档
3. 验证示例可以编译/运行
4. 添加 JSDoc 并更新 README

阅读完整模板：@templates/docs-generation.md

dataset-generation

通过以下步骤生成训练数据：

1. 创建符合质量标准的样本
2. 在每轮迭代中验证质量
3. 在 progress.txt 中跟踪数量
4. 达到目标数量后停止

阅读完整模板：@templates/dataset-generation.md

migration

通过以下步骤迁移代码库：

1. 从文件中读取迁移计划
2. 每轮迭代迁移一个模块
3. 确保每次迁移后测试均通过
4. 跟踪已迁移与待迁移的部分

阅读完整模板：@templates/migration.md

取消循环

要停止正在运行的 Ralph 循环，请删除状态文件：

rm .claude/ralph-loop.local.md

或等待达到最大迭代次数。

致谢

基于 Geoffrey Huntley 的 Ralph Wiggum 技术。 结合了 Ryan Carson、Matt Pocock 和 AI Hero 的经验。