ralph-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Loop Creator

Ralph Loop 创建器

Create autonomous iterative loops that process a backlog of tasks with clear acceptance criteria. Named after the Ralph Wiggum pattern for spec-driven autonomous development.

创建可处理带有明确验收标准的任务积压的自主迭代循环。该模式得名于用于规范驱动自主开发的Ralph Wiggum模式。

Overview

概述

A Ralph loop consists of:

Task System - Native Claude Code task management with dependency tracking
Prompt (
```
prompt.md
```
) - Instructions for each iteration
Runner (
```
ralph.sh
```
) - Bash script that loops until completion
Progress (
```
progress.txt
```
) - Execution log
Knowledge (
```
knowledge.md
```
) - Accumulated learnings

Ralph Loop包含以下组件：

任务系统 - 具备依赖跟踪功能的原生Claude Code任务管理系统
提示文件 (
```
prompt.md
```
) - 每次迭代的执行指令
运行脚本 (
```
ralph.sh
```
) - 循环执行直至完成的Bash脚本
进度日志 (
```
progress.txt
```
) - 执行记录文件
知识库 (
```
knowledge.md
```
) - 积累的学习记录

Quick Start

快速开始

To create a new Ralph loop, gather requirements then run the init script:

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py <output-dir>

要创建新的Ralph Loop，请先收集需求，然后运行初始化脚本：

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py <output-dir>

Workflow

工作流

Step 1: Gather Requirements

步骤1：收集需求

Before creating a loop, clarify these parameters with the user using AskUserQuestion:

Loop Goal:

What is the global objective of this loop?
What domain/codebase does it operate on?

Task Structure:

What kind of tasks/items will be tracked?
What dependencies exist between tasks?
What metadata should each task have?

Iteration Process:

What steps should each iteration perform?
What tools/commands are needed?
What files should be read/written?

Acceptance Criteria:

How to validate a task is completed?
What checks should pass before marking done?
Should there be automated validation (tests, builds, typechecks)?

Exit Conditions:

When should the loop terminate? (all tasks done, specific marker, max iterations)
What completion marker to use? Default:
```
<promise>COMPLETE</promise>
```

创建循环前，请使用AskUserQuestion工具向用户确认以下参数：

循环目标：

此循环的全局目标是什么？
它将在哪个领域/代码库中运行？

任务结构：

将跟踪哪些类型的任务/事项？
任务之间存在哪些依赖关系？
每个任务应包含哪些元数据？

迭代流程：

每次迭代应执行哪些步骤？
需要使用哪些工具/命令？
需要读写哪些文件？

验收标准：

如何验证任务已完成？
标记任务完成前需要通过哪些检查？
是否需要自动化验证（测试、构建、类型检查）？

退出条件：

循环应在何时终止？（所有任务完成、特定标记、最大迭代次数）
使用什么完成标记？默认值：
```
<promise>COMPLETE</promise>
```

Step 2: Select or Create Template

步骤2：选择或创建模板

Available templates in

~/.claude/skills/ralph-loop/templates/

Template	Use Case
`migration.md`	Migrating components, APIs, dependencies
`exploration.md`	Codebase analysis, documentation generation
`testing.md`	Test generation, coverage improvement
`refactoring.md`	Code cleanup, pattern enforcement
`custom.md`	Blank template for unique workflows

~/.claude/skills/ralph-loop/templates/

目录下提供了以下可用模板：

模板	使用场景
`migration.md`	组件、API、依赖项迁移
`exploration.md`	代码库分析、文档生成
`testing.md`	测试生成、覆盖率提升
`refactoring.md`	代码清理、模式强制执行
`custom.md`	适用于独特工作流的空白模板

Step 3: Generate Loop Files

步骤3：生成循环文件

After gathering requirements, generate the loop structure:

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py \
  --template migration \
  --output ./my-loop \
  --goal "Migrate React components from styled-components to Tailwind"

Or interactively:

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py ./my-loop

收集完需求后，生成循环结构：

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py \
  --template migration \
  --output ./my-loop \
  --goal "Migrate React components from styled-components to Tailwind"

或交互式生成：

bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py ./my-loop

Step 4: Create Tasks Using Task System

步骤4：使用任务系统创建任务

After generating the loop, create tasks using the native Task tools:

TaskCreate:
  subject: "Migrate Button component"
  description: "Convert Button from styled-components to Tailwind CSS classes"
  activeForm: "Migrating Button component"

Set up dependencies between tasks:

TaskUpdate:
  taskId: "2"
  addBlockedBy: ["1"]  # Task 2 waits for Task 1

生成循环后，使用原生Task工具创建任务：

TaskCreate:
  subject: "Migrate Button component"
  description: "Convert Button from styled-components to Tailwind CSS classes"
  activeForm: "Migrating Button component"

设置任务之间的依赖关系：

TaskUpdate:
  taskId: "2"
  addBlockedBy: ["1"]  # Task 2 waits for Task 1

Step 5: Run the Loop

步骤5：运行循环

bash

cd <output-dir>
./ralph.sh [max-iterations]

Default max iterations: 50

bash

cd <output-dir>
./ralph.sh [max-iterations]

默认最大迭代次数：50

File Structure

文件结构

<output-dir>/
├── ralph.sh          # Executable bash loop
├── prompt.md         # Iteration instructions (uses Task tools)
├── progress.txt      # Execution log
├── knowledge.md      # Accumulated learnings
└── logs/             # Per-run log files

<output-dir>/
├── ralph.sh          # Executable bash loop
├── prompt.md         # Iteration instructions (uses Task tools)
├── progress.txt      # Execution log
├── knowledge.md      # Accumulated learnings
└── logs/             # Per-run log files

Task System Integration

任务系统集成

The Ralph loop uses Claude Code's native Task management system:

Tools:

```
TaskCreate
```
- Create new tasks with subject, description, activeForm
```
TaskList
```
- View all tasks with status/owner/blockers
```
TaskGet
```
- Fetch full task details by ID
```
TaskUpdate
```
- Change status, set dependencies, mark complete

Status values:

pending

in_progress

completed

Dependencies:

```
blocks
```
- Tasks that cannot start until this one completes
```
blockedBy
```
- Tasks that must complete before this one can start

Benefits over JSON backlog:

Native dependency tracking
Status validation (can't mark complete if tests fail)
Parallel agent coordination via owner field
Progress spinner shows activeForm text

Ralph Loop使用Claude Code的原生任务管理系统：

工具：

```
TaskCreate
```
- 创建包含主题、描述、activeForm的新任务
```
TaskList
```
- 查看所有任务的状态/负责人/阻塞项
```
TaskGet
```
- 通过ID获取完整任务详情
```
TaskUpdate
```
- 修改状态、设置依赖关系、标记任务完成

状态值：

pending

in_progress

completed

依赖关系：

```
blocks
```
- 此任务完成前无法启动的任务
```
blockedBy
```
- 必须先完成才能启动此任务的任务

相比JSON任务积压的优势：

原生依赖跟踪
状态验证（测试失败时无法标记为完成）
通过负责人字段实现多Agent并行协作
进度加载动画显示activeForm文本

Prompt Template Structure

提示模板结构

markdown

undefined

markdown

undefined

Ralph Agent: {Goal}

Configuration

List paths, files, tools

List paths, files, tools

Your Task (One Iteration)

Step 1: Load Context

Use TaskList to get all tasks, read knowledge.md

Step 2: Determine State

Check if all tasks are completed → output <promise>COMPLETE</promise>

Step 3: Select Target

Use TaskList to find first task with:

status: "pending"
blockedBy: empty (no unresolved dependencies) Use TaskUpdate to set status: "in_progress"

Use TaskList to find first task with:

status: "pending"
blockedBy: empty (no unresolved dependencies) Use TaskUpdate to set status: "in_progress"

Step 4-N: Execute

Task-specific steps using TaskGet for full details

Final Step: Update

Use TaskUpdate to set status: "completed" Update progress.txt and knowledge.md

Completion

When all tasks completed: <promise>COMPLETE</promise>

undefined

When all tasks completed: <promise>COMPLETE</promise>

undefined

Creating Initial Tasks

创建初始任务

After generating the loop, create tasks for the backlog. Example for a migration loop:

undefined

生成循环后，为任务积压创建任务。以下是迁移循环的示例：

undefined

Create first task

TaskCreate: subject: "Migrate Button component" description: "Convert Button.tsx from styled-components to Tailwind. Update imports, replace styled() calls with className props using Tailwind utilities." activeForm: "Migrating Button component"

Create dependent task

TaskCreate: subject: "Migrate Modal component" description: "Convert Modal.tsx. Depends on Button migration since Modal uses Button internally." activeForm: "Migrating Modal component"

Set dependency

TaskUpdate: taskId: "2" addBlockedBy: ["1"]


**Tip:** Use TaskUpdate with `addBlockedBy` to ensure tasks run in correct order.

TaskUpdate: taskId: "2" addBlockedBy: ["1"]


**提示：** 使用`TaskUpdate`的`addBlockedBy`参数确保任务按正确顺序执行。

Best Practices

最佳实践

One task per iteration - Keep iterations focused
Clear acceptance criteria - Define what "done" means
Use dependencies - Set blockedBy for ordered tasks
Incremental commits - Commit after each successful task
Knowledge accumulation - Document learnings for future iterations
Fail fast - Stop on errors, don't silently continue
Idempotent operations - Safe to re-run if interrupted

每次迭代处理一个任务 - 保持迭代聚焦
明确的验收标准 - 定义“完成”的含义
使用依赖关系 - 为有序执行的任务设置blockedBy
增量提交 - 每次任务成功完成后提交代码
积累知识 - 为未来迭代记录学习内容
快速失败 - 遇到错误时停止，不要静默继续
幂等操作 - 中断后可安全重新运行

Troubleshooting

故障排除

Issue	Solution
Loop never completes	Check completion marker in prompt.md matches ralph.sh
Tasks skipped	Verify status field updates in prompt.md
Context overflow	Reduce prompt.md size, move details to knowledge.md
Permission errors	Ensure ralph.sh has execute permissions

问题	解决方案
循环始终无法完成	检查prompt.md中的完成标记是否与ralph.sh中的一致
任务被跳过	验证prompt.md中的状态字段是否正确更新
上下文溢出	减小prompt.md的大小，将细节移至knowledge.md
权限错误	确保ralph.sh具有执行权限

References

参考资料

templates/ - Pre-built loop templates
references/patterns.md - Common iteration patterns

templates/ - 预构建的循环模板
references/patterns.md - 常见迭代模式