super-ralph-wiggum

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Super Ralph Wiggum

Autonomous iteration loops for Claude Code. Run the same prompt repeatedly until task completion, with context persisting through files and git history.

为Claude Code打造的自主迭代循环工具。重复运行相同提示直至任务完成，上下文通过文件和Git历史记录持久化。

The Ralph Philosophy

Ralph 核心理念

The agent chooses the task, not you.

You define the end state. Ralph figures out how to get there.

With multi-phase plans, a human writes a new prompt at the start of each phase. With Ralph, the agent picks what to work on next from your PRD. You describe the destination. Ralph navigates.

由Agent选择任务，而非你。

你定义最终状态，Ralph规划实现路径。

在多阶段计划中，人类需要在每个阶段开始时编写新提示。而使用Ralph，Agent会从你的PRD中自主选择下一个要处理的任务。你只需描述目标，Ralph会负责导航前行。

The 11 Tips (Quick Reference)

11条实用技巧（快速参考）

Based on AI Hero's definitive guide:

#	Tip	Key Insight
1	Ralph Is A Loop	Same prompt, multiple iterations
2	Start HITL, Then AFK	Learn → Trust → Let go
3	Define The Scope	Explicit stop conditions prevent infinite loops
4	Track Progress	progress.txt bridges context windows
5	Use Feedback Loops	Types, tests, linting as guardrails
6	Take Small Steps	One logical change per commit
7	Prioritize Risky Tasks	Architecture first, quick wins last
8	Define Software Quality	Tell Ralph what kind of repo this is
9	Use Docker Sandboxes	Essential for AFK safety
10	Pay To Play	HITL still valuable without AFK
11	Make It Your Own	Alternative loop types, task sources

See

@references/tips-and-tricks.md

for detailed guidance on each tip.

基于AI Hero的权威指南：

序号	技巧	核心要点
1	Ralph是一个循环	相同提示，多次迭代
2	从人机协作（HITL）开始，再转为无人值守（AFK）	学习 → 信任 → 放手
3	明确定义范围	清晰的停止条件可防止无限循环
4	跟踪进度	progress.txt 可突破上下文窗口限制
5	使用反馈循环	类型检查、测试、代码规范作为防护机制
6	小步迭代	每次提交仅包含一个逻辑变更
7	优先处理高风险任务	先做架构设计，最后处理快速实现的小功能
8	定义软件质量标准	告诉Ralph当前代码库的定位
9	使用Docker沙箱	对无人值守（AFK）模式至关重要
10	按需选择模式	即使不使用AFK，人机协作（HITL）依然有价值
11	自定义适配	支持自定义循环类型和任务来源

如需每条技巧的详细说明，请查看

@references/tips-and-tricks.md

。

Quick Start

快速开始

To start a Ralph loop with a template:

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

To start with a PRD file:

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

使用模板启动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

Available Templates

可用模板

Template	Use Case	Default Iterations
`test-coverage`	Improve test coverage to target %	30
`feature-prd`	Implement features from PRD file	20
`lint-fix`	Fix all lint errors incrementally	30
`docs-generation`	Generate documentation for modules	25
`dataset-generation`	Generate training data samples	50
`migration`	Migrate to new framework/version	40
`entropy-loop`	Reverse software entropy (dead code, smells)	30
`duplication-loop`	Eliminate duplicate code	25

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

Invocation Patterns

调用模式

Template Mode (Recommended)

模板模式（推荐）

Use a pre-built template for common tasks:

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

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

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

PRD Mode

PRD模式

For structured feature development with task tracking:

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

The PRD file tracks features with

passes: true/false

. Loop completes when all features pass.

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

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

PRD文件通过

passes: true/false

跟踪功能状态。当所有功能标记为通过时，循环结束。

HITL Mode (Single Iteration)

人机协作（HITL）模式（单次迭代）

For interactive learning and pair programming:

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

Runs ONE iteration without looping. Great for learning how Ralph works.

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

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

仅运行一次迭代，不进入循环。非常适合学习Ralph的工作机制。

Custom Prompt

自定义提示

For tasks not covered by templates:

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

用于模板未覆盖的任务：

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

The Two Modes: HITL vs AFK

两种模式：HITL vs AFK

Mode	How It Works	Best For
HITL (human-in-the-loop)	Run once, watch, intervene	Learning, prompt refinement, risky tasks
AFK (away from keyboard)	Run in a loop with max iterations	Bulk work, low-risk tasks, overnight runs

The progression is simple:

Start with HITL to learn and refine
Go AFK once you trust your prompt
Review the commits when you return

For AFK, always cap iterations:

Small tasks: 5-10 iterations
Medium tasks: 15-30 iterations
Large features: 30-50 iterations

模式	工作原理	最佳适用场景
HITL（人机协作）	运行一次，人工监控并干预	学习、提示优化、高风险任务
AFK（无人值守）	循环运行直至达到最大迭代次数	批量任务、低风险任务、夜间运行

进阶路径很简单：

从HITL模式开始，学习并优化提示
当你信任提示的效果后，切换为AFK模式
回来后查看提交记录即可

对于AFK模式，务必设置迭代上限：

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

Explicitly Define Software Quality

明确定义软件质量标准

Ralph doesn't know if this is a throwaway prototype or production code. Tell it.

Repo Type	What To Say	Expected Behavior
Prototype	"Speed over perfection. Skip edge cases."	Takes shortcuts
Production	"Must be maintainable. Follow best practices."	Adds tests, docs
Library	"Public API. Backward compatibility matters."	Careful about breaking changes

Ralph无法判断当前代码库是一次性原型还是生产代码。请明确告知它。

代码库类型	该如何描述	预期行为
原型	"速度优先，跳过边缘案例。"	采用快捷方式实现
生产环境	"必须具备可维护性，遵循最佳实践。"	添加测试和文档
类库	"公开API，向后兼容性至关重要。"	谨慎处理破坏性变更

Code Quality Prompt

代码质量提示

If the loop should maintain high code quality, specify it factually:

Maintain existing code conventions and quality standards. Each change should leave test coverage equal to or better than before. Prefer incremental improvements over large rewrites.

Avoid motivational framing ("fight entropy", "be thorough")—Claude 4.6 already tends toward thoroughness and these amplify it into over-planning. Factual quality criteria are more effective.

如果循环需要保持高代码质量，请客观明确地指定：

遵循现有代码规范和质量标准。每次变更后的测试覆盖率应不低于变更前。优先选择增量改进而非大规模重写。

避免使用激励性表述（如"对抗熵"、"务必彻底"）——Claude 4.6本身就倾向于详尽处理，这类表述会导致过度规划。客观的质量标准会更有效。

The Repo Wins

代码库优先级高于指令

Your instructions compete with your codebase. When Ralph explores your repo, it sees two sources of truth: what you told it to do and what you actually did.

If you write "never use

any

types" but Ralph sees

any

throughout your existing code, it will follow the codebase, not your instructions.

Claude learns patterns from the existing codebase. If the codebase uses

any

types throughout, the loop will follow that pattern regardless of instructions. Clean up the specific patterns you care about before running the loop.

你的指令与代码库实际情况可能存在冲突。当Ralph扫描代码库时，它会看到两个事实来源：你要求它做的，以及代码库实际的实现方式。

如果你要求"永远不要使用

any

类型"，但Ralph发现代码库中大量使用

any

，它会遵循代码库的模式，而非你的指令。

Claude会从现有代码库中学习模式。如果代码库中普遍使用

any

类型，无论你如何指令，循环都会遵循该模式。在运行循环前，请先清理你关注的特定代码模式。

Task Prioritization Order

任务优先级顺序

When choosing the next task, Ralph should prioritize:

Architectural decisions and core abstractions
Integration points between modules
Unknown unknowns and spike work
Standard features and implementation
Polish, cleanup, and quick wins

Fail fast on risky work. Save easy wins for later.

Use HITL Ralph for early architectural decisions—the code from these tasks stays forever. Save AFK Ralph for when the foundation is solid.

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

架构决策和核心抽象
模块间集成点
未知风险和探索性工作
标准功能和实现
优化、清理和快速实现的小功能

在高风险工作上快速试错。把简单的小功能留到最后。

在早期架构决策阶段使用HITL模式的Ralph——这些任务产生的代码会长期存在。当基础架构稳固后，再使用AFK模式的Ralph。

Execution Modes

执行模式

1. In-Session Mode (Default)

1. 会话内模式（默认）

Loop runs inside your current Claude Code session using stop hooks:

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

Stop hook intercepts exit attempts
Same prompt fed back each iteration
Context persists through files and git
Best for interactive/monitored work

循环在当前Claude Code会话内运行，使用停止钩子：

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

停止钩子拦截退出尝试
每次迭代使用相同提示
上下文通过文件和Git持久化
最适合交互式/受监控的工作

2. Dockerized Mode (External)

2. Docker化模式（外部）

Loop runs externally via bash script with Docker sandbox:

bash

undefined

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

bash

undefined

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 &


- Each iteration is a fresh Claude Code instance
- Docker isolation for safety
- Best for overnight/AFK runs
- Memory persists only via files

**Essential for AFK safety**: Docker sandboxes let Ralph edit project files and commit—but can't touch your home directory, SSH keys, or system files.

./run-ralph.sh 20 &


- 每次迭代都是全新的Claude Code实例
- Docker隔离保障安全
- 最适合夜间/AFK运行
- 仅通过文件持久化内存

**AFK安全的关键**：Docker沙箱允许Ralph编辑项目文件并提交，但无法访问你的主目录、SSH密钥或系统文件。

How It Works

工作原理

Setup: Creates state file at
```
.claude/ralph-loop.local.md
```
Progress: Auto-creates
```
progress.txt
```
in project root
Loop: Stop hook intercepts exit, feeds same prompt back
Completion: Detects
```
<promise>COMPLETE</promise>
```
or PRD all-pass
Learning: Patterns accumulate in progress.txt across iterations

设置：在
```
.claude/ralph-loop.local.md
```
创建状态文件
进度跟踪：在项目根目录自动创建
```
progress.txt
```
循环：停止钩子拦截退出操作，每次迭代重新传入相同提示
完成检测：检测到
```
<promise>COMPLETE</promise>
```
或所有PRD功能通过
学习积累：迭代中的经验会累积到progress.txt中

Key Options

关键选项

Option	Description	Default
`--template <name>`	Use pre-built template	(required or custom prompt)
`--prd <file>`	PRD file for task tracking	none
`--max-iterations <n>`	Iteration limit	varies by template
`--completion-promise <text>`	Custom completion phrase	COMPLETE
`--progress <file>`	Progress file location	./progress.txt
`--browser`	Enable browser testing prompts	false
`--once`	Single iteration (HITL mode)	false

选项	描述	默认值
`--template <name>`	使用预构建模板	（必填，或使用自定义提示）
`--prd <file>`	用于任务跟踪的PRD文件	无
`--max-iterations <n>`	迭代次数上限	随模板不同而变化
`--completion-promise <text>`	自定义完成标识	COMPLETE
`--progress <file>`	进度文件位置	./progress.txt
`--browser`	启用浏览器测试提示	false
`--once`	单次迭代（HITL模式）	false

Best Practices

最佳实践

1. Small Stories

1. 拆分任务为小故事

Tasks must fit in one context window. Break large features into atomic stories.

任务必须能放入一个上下文窗口。将大型功能拆分为原子化的小故事。

2. Verification First

2. 先验证再提交

Always run typecheck + tests before committing. Templates enforce this.

提交前务必运行类型检查和测试。模板已强制要求这一点。

3. Cap Iterations

3. 设置迭代上限

For AFK (unattended) Ralph, always set

--max-iterations

. Infinite loops are dangerous with stochastic systems.

对于AFK（无人值守）模式的Ralph，务必设置

--max-iterations

。随机系统存在无限循环的风险。

4. Clear Completion Criteria

4. 明确完成标准

Vague tasks risk infinite loops. Be explicit about when to stop.

模糊的任务可能导致无限循环。请明确说明停止条件。

5. Use Progress File

5. 使用进度文件

Previous iteration learnings persist in

progress.txt

. Templates auto-inject this.

上一次迭代的经验会保存在

progress.txt

中。模板会自动注入该文件内容。

6. One Change Per Commit

6. 每次提交一个变更

Keep changes small and focused. Prefer multiple small commits over one large commit.

保持变更小而聚焦。优先选择多次小型提交而非一次大型提交。

7. Structure State Appropriately

7. 合理结构化状态

Use JSON for structured progress data (coverage percentages, feature pass/fail, migration counts). Use freeform text in progress.txt for observations and session learnings. Use git commits as checkpoints between iterations so each new context window can discover state from the filesystem.

使用JSON存储结构化进度数据（覆盖率百分比、功能通过状态、迁移计数）。在progress.txt中使用自由文本记录观察结果和会话经验。使用Git提交作为迭代间的检查点，以便新的上下文窗口可以从文件系统中获取状态。

References

参考资料

For detailed guidance, read the reference files:

```
@references/tips-and-tricks.md
```
- The 11 Tips expanded with AI Hero insights
```
@references/prompt-patterns.md
```
- 10 patterns for convergent prompts
```
@references/prd-schema.md
```
- PRD file structure and usage
```
@references/cost-estimation.md
```
- API cost guidelines
```
@references/browser-testing.md
```
- Dev-browser integration

如需详细指导，请查看以下参考文件：

```
@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
```
- 开发浏览器集成

Template Details

模板详情

test-coverage

Improves test coverage by:

Running coverage to find gaps
Identifying most important untested user-facing behavior
Writing ONE meaningful test per iteration
Using
```
/* v8 ignore */
```
for non-essential code
Committing after each successful test

Read full template:

@templates/test-coverage.md

通过以下方式提升测试覆盖率：

运行覆盖率检测找出缺口
识别最重要的未测试用户行为
每次迭代编写一个有意义的测试
对非必要代码使用
```
/* v8 ignore */
```
每次测试成功后提交

查看完整模板：

@templates/test-coverage.md

feature-prd

Implements features from a PRD file by:

Reading
```
prd.json
```
for highest-priority incomplete feature
Checking dependencies are satisfied
Implementing ONE feature per iteration
Running verification (typecheck + tests)
Updating AGENTS.md with patterns discovered
Marking feature as
```
passes: true
```

Read full template:

@templates/feature-prd.md

通过以下方式基于PRD文件实现功能：

读取
```
prd.json
```
获取优先级最高的未完成功能
检查依赖是否满足
每次迭代实现一个功能
运行验证（类型检查+测试）
在AGENTS.md中记录发现的模式
将功能标记为
```
passes: true
```

查看完整模板：

@templates/feature-prd.md

lint-fix

Fixes lint errors by:

Running linter to get error list
Picking file with most errors
Fixing ALL errors in that file
Verifying fixes don't break tests
Committing and moving to next file

Read full template:

@templates/lint-fix.md

通过以下方式修复代码规范错误：

运行代码规范检查获取错误列表
选择错误最多的文件
修复该文件中的所有错误
验证修复不会破坏测试
提交后处理下一个文件

查看完整模板：

@templates/lint-fix.md

entropy-loop

Reverses software entropy by:

Scanning for code smells (unused exports, dead code, TODOs)
Fixing ONE issue per iteration
Running verification
Documenting changes in progress.txt

Read full template:

@templates/entropy-loop.md

通过以下方式逆转软件熵：

扫描代码异味（未使用的导出、死代码、TODO注释）
每次迭代修复一个问题
运行验证
在progress.txt中记录变更

查看完整模板：

@templates/entropy-loop.md

duplication-loop

Eliminates duplicate code by:

Running jscpd to find duplicates
Identifying ONE duplication group
Extracting shared code into utility/helper
Updating all call sites
Verifying with tests

Read full template:

@templates/duplication-loop.md

通过以下方式消除重复代码：

运行jscpd检测重复代码
识别一组重复代码
将共享代码提取为工具/辅助函数
更新所有调用位置
通过测试验证

查看完整模板：

@templates/duplication-loop.md

docs-generation

Generates documentation by:

Identifying undocumented public functions
Writing ONE doc per iteration
Verifying examples compile/run
Including JSDoc and README updates

Read full template:

@templates/docs-generation.md

通过以下方式生成文档：

识别未文档化的公开函数
每次迭代编写一个文档
验证示例可编译/运行
包含JSDoc和README更新

查看完整模板：

@templates/docs-generation.md

dataset-generation

Generates training data by:

Creating samples meeting quality criteria
Validating quality per iteration
Tracking count in progress.txt
Stopping at target count

Read full template:

@templates/dataset-generation.md

通过以下方式生成训练数据：

创建符合质量标准的样本
每次迭代验证质量
在progress.txt中跟踪数量
达到目标数量时停止

查看完整模板：

@templates/dataset-generation.md

migration

Migrates codebase by:

Reading migration plan from file
Migrating ONE module per iteration
Ensuring tests pass after each
Tracking migrated vs remaining

Read full template:

@templates/migration.md

通过以下方式迁移代码库：

从文件中读取迁移计划
每次迭代迁移一个模块
确保每次迁移后测试通过
跟踪已迁移和剩余模块数量

查看完整模板：

@templates/migration.md

Canceling a Loop

取消循环

To stop an active Ralph loop, delete the state file:

bash

rm .claude/ralph-loop.local.md

Or wait for max iterations to be reached.

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

bash

rm .claude/ralph-loop.local.md

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

Attribution

致谢

Based on the Ralph Wiggum technique by Geoffrey Huntley. Enhanced with learnings from Ryan Carson, Matt Pocock, and AI Hero.

基于Geoffrey Huntley提出的Ralph Wiggum技术（链接）。结合了Ryan Carson、Matt Pocock和AI Hero（链接）的经验进行增强。