ralph-mode

Ralph 模式

Ralph 是一个自主 AI 编码循环，会反复启动全新的上下文窗口，直到所有任务完成。记忆通过 git 历史和文本文件持久保存，而每次迭代都会从全新状态开始。

名称取自《辛普森一家》中的 Ralph Wiggum——总是困惑、不断犯错，却从不停下。其理念是：迭代胜过完美。

两种执行模式

Ralph 可在两种环境中运行：

模式	环境	工作方式	全新上下文来源
本地	CLI 终端	Bash 循环启动 claude -p	新的 CLI 进程
远程	Web/API/Agent SDK	控制器启动 Task 子 Agent	新的 Task 调用

两种模式都能实现相同目标：每次迭代都使用全新上下文，以避免上下文腐化。

快速开始

初始化 Ralph

bun .claude/skills/ralph-mode/scripts/init-ralph.ts

这会创建包含所有必需文件的 scripts/ralph/。

填写 PRD

编辑 scripts/ralph/prd.json，添加用户故事（参见 prd-guide.md）。

运行 Ralph

本地模式（CLI）：

./scripts/ralph/ralph.sh 20      # AFK: 20 iterations max
./scripts/ralph/ralph-once.sh    # HITL: single iteration

远程模式（Web/API）： 加载 scripts/ralph/ralph-controller.md 并按其中说明操作。控制器会为每个故事启动 Task 子 Agent。

工作原理

本地模式（Bash 循环）

┌─────────────────────────────────────────┐
│  ralph.sh (bash loop)                   │
│  └─▶ claude -p < prompt.md              │
│       └─▶ Implements ONE story          │
│       └─▶ Commits if passing            │
│       └─▶ Updates state files           │
│  └─▶ Loop until done or max iterations  │
└─────────────────────────────────────────┘

远程模式（基于 Task）

┌─────────────────────────────────────────┐
│  Ralph Controller (you or outer agent)  │
│  └─▶ Reads prd.json, progress.txt       │
│  └─▶ Selects next story                 │
│  └─▶ Task(general-purpose) ────────────────┐
│       │                                    │
│       ▼                                    │
│  ┌─────────────────────────────────────┐   │
│  │  Ralph Worker (subagent)            │   │
│  │  - Fresh context window             │   │
│  │  - Implements ONE story             │   │
│  │  - Runs feedback loops              │   │
│  │  - Commits if passing               │   │
│  │  - Updates state files              │   │
│  └─────────────────────────────────────┘   │
│       │                                    │
│       ◀────────────────────────────────────┘
│  └─▶ Verifies result                    │
│  └─▶ Loop until done or max iterations  │
└─────────────────────────────────────────┘

关键点：每次 Task() 调用都会创建一个全新的上下文窗口——这正是 Ralph 所需的。

文件结构

scripts/ralph/
├── ralph.sh            # Local: AFK mode loop
├── ralph-once.sh       # Local: HITL single iteration
├── ralph-controller.md # Remote: Controller instructions
├── ralph-worker.md     # Remote: Worker template
├── prompt.md           # Local: Iteration prompt
├── prd.json            # User stories with completion status
└── progress.txt        # Accumulated learnings

远程模式：强制使用子 Agent

在远程模式下，控制器不得直接实现代码：

❌ Controller writes code     → Context rot, defeats purpose
✅ Controller spawns workers  → Fresh context per story

控制器只负责：

1. 读取状态文件
2. 选择下一个故事
3. 启动 Task 子 Agent
4. 验证结果
5. 循环执行

所有实现工作都由使用全新上下文的子 Agent 完成。

启动工作 Agent

Task({
  subagent_type: "general-purpose",
  description: "Implement US-003: Add email validation",
  prompt: `[contents of ralph-worker.md with story details filled in]`
})

工作 Agent 的职责

每个工作子 Agent 都要：

1. 加载上下文（progress.txt、AGENTS.md）
2. 实现一个故事
3. 运行反馈循环（类型检查、lint、测试）
4. 仅在全部通过时提交
5. 更新 prd.json 和 progress.txt
6. 将结果报告给控制器

记忆持久化

Ralph 会在每次迭代之间忘记所有内容。记忆仅通过以下方式持久保存：

文件	用途
prd.json	任务状态（passes 字段）
progress.txt	经验、模式和注意事项
Git 提交	实现历史
AGENTS.md	永久项目模式

成功的 11 条建议

1. Ralph 是一个循环

任务由 Agent 选择，而不是你。定义最终状态，Ralph 会抵达那里。

2. 先 HITL，再 AFK

• HITL：观察、干预、改进提示词
• AFK：基础稳固后批量处理工作

3. 明确范围

PRD 条目应包含明确的 passes 字段和验收标准。

4. 跟踪进度

progress.txt 就是记忆。将代码库模式放在最上方。

5. 使用反馈循环

只有类型检查、lint 和测试全部通过，才允许提交。

6. 小步前进

每次迭代处理一个故事。上下文腐化确实存在。

7. 优先处理高风险任务

架构 → 集成 → 功能 → 打磨

8. 明确质量预期

告诉 Ralph：目标是原型、生产级产品还是库。

9. 使用沙盒

本地 AFK 使用 Docker。远程模式使用隔离环境。

10. 投入才能获得回报

即使是 HITL Ralph，也胜过手动进行多阶段提示。

11. 按需改造

Ralph 只是一个循环。可根据覆盖率、lint、重构等需求进行调整。

使用示例

本地 HITL（学习）

./scripts/ralph/ralph-once.sh
# Watch output, intervene if needed
# Run again when ready

本地 AFK（通宵运行）

./scripts/ralph/ralph.sh 50  # Let it run

远程 HITL（Web 会话）

1. 阅读 ralph-controller.md
2. 阅读 prd.json 和 progress.txt
3. 选择一个故事
4. 使用工作 Agent 提示词启动一个 Task 子 Agent
5. 验证结果
6. 手动重复以上步骤

远程 AFK（Agent 间协作）

外部 Agent 或 Agent SDK 程序运行控制器循环，并不断启动子 Agent，直到所有故事都通过。

监控进度

# Story status
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

# Learnings
cat scripts/ralph/progress.txt

# Recent commits
git log --oneline -10

安全

• 本地 AFK 使用 --dangerously-skip-permissions
• 尽可能使用 Docker 沙箱
• 始终限制迭代次数
• 按 Ctrl+C 可立即停止本地循环
• git reset --hard 会还原未提交的更改

不适用场景

• 没有明确结果的探索性工作
• 没有明确标准的重大重构
• 需要人工审查的安全关键代码
• 早期架构决策（使用 HITL）

参考资料

• prd-guide.md - 编写有效的用户故事
• patterns.md - 常见模式和注意事项
• ralph-controller.md - 远程控制器说明
• ralph-worker.md - Worker 子 Agent 模板