介绍
# Ralph Loops Skill
> **第一次使用？** 请先阅读 [SETUP.md](./SETUP.md) 以安装依赖项并验证您的设置。
用于迭代开发的自主 AI 代理循环。基于 Geoffrey Huntley 的 Ralph Wiggum 技术，由 Clayton Farr 记录。
**脚本：** `skills/ralph-loops/scripts/ralph-loop.mjs` **仪表板：** `skills/ralph-loops/dashboard/` （使用 `node server.mjs` 运行） **模板：** `skills/ralph-loops/templates/` **归档：** `~/clawd/logs/ralph-archive/`
---
## ⚠️ 已知问题
### Claude Code 版本兼容性
**Claude Code 2.1.29 存在一个严重 Bug**，会生成消耗 99% CPU 的孤立子代理。首次运行时迭代失败并提示“exit code null”。
**修复：** 降级到 2.1.25： ```bash npm install -g @anthropic-ai/[email protected] ```
**验证：** ```bash claude --version # Should show 2.1.25 ```
此问题发现于 2026-02-01。在升级前请检查较新版本是否已修复该问题。
---
## ⚠️ 不要阻塞对话！
运行 Ralph 循环时，**不要同步监控它**。该循环作为一个独立的 Claude CLI 进程运行 —— 您可以继续聊天。
**❌ 错误（阻塞对话）：** ``` Start loop → sleep 60 → poll → sleep 60 → poll → ... (6 minutes of silence) ```
**✅ 正确（保持响应）：** ``` Start loop → "It's running, I'll check periodically" → keep chatting → check on heartbeats ```
**如何在不阻塞的情况下监控：** 1. 使用 `node ralph-loop.mjs ...` 启动循环（在后台运行） 2. 告诉人类：“循环正在运行。我会定期检查进度，或者您也可以询问。” 3. 当被询问或在心跳期间，通过 `process poll <sessionId>` 检查 4. 使用位于 http://localhost:3939 的仪表板进行实时查看
**循环是自主的** —— 这正是其全部意义所在。不要为了盯着它而忽略您的人类用户。
---
## 触发短语
当人类说：
| 短语 | 动作 | |--------|--------| | **"Interview me about system X"** | 开始第一阶段需求面试 | | **"Start planning system X"** | 运行 `./loop.sh plan` （需要先有规格说明） | | **"Start building system X"** | 运行 `./loop.sh build` （需要先有计划） | | **"Ralph loop over X"** | **询问**处于哪个阶段（见下文） |
### 当人类说“Ralph Loop”时 —— 澄清阶段！
不要假设是哪个阶段。请询问：
> "我们要进行哪种类型的 Ralph 循环？ > > 1️⃣ **Interview** — 我会问您问题以构建规格说明（第一阶段） > 2️⃣ **Planning** — 我将迭代改进实现计划（第二阶段） > 3️⃣ **Building** — 我将根据计划进行实施，每次迭代一个任务（第三阶段） > 4️⃣ **Generic** — 对单个主题进行简单的迭代优化"
**然后根据他们的回答进行操作：**
| 选项 | 动作 | |--------|--------| | Interview | 使用 `templates/requirements-interview.md` 协议 | | Planning | 需要规格说明 → 运行使用 `PROMPT_plan.md` 的规划循环 | | Building | 需要计划 → 运行使用 `PROMPT_build.md` 的构建循环 | | Generic | 创建提示词文件，直接运行 `ralph-loop.mjs` |
### 通用 Ralph 循环流程（第四阶段）
用于简单的迭代优化（非完整的系统构建）：
1. **明确任务** —— 具体应该改进/优化什么？ 2. **创建提示词文件** —— 保存到 `/tmp/ralph-prompt-<task>.md` 3. **设置完成标准** —— 什么信号表示“完成”？ 4. **运行循环：** ```bash node skills/ralph-loops/scripts/ralph-loop.mjs \ --prompt "/tmp/ralph-prompt-<task>.md" \ --model opus \ --max 10 \ --done "RALPH_DONE" ``` 5. **或作为子代理生成** 用于长时间运行的任务
---
## 核心理念
> "人类的角色从'告诉代理做什么'转变为'设计让良好结果自然通过迭代涌现的条件'。" > — Clayton Farr
三个原则驱动一切：
1. **上下文稀缺** —— 在 200K 的窗口中仅有约 176K 可用 Token，保持每次迭代精简 2. **计划是可抛弃的** —— 重新生成一个偏离的计划比挽救它更廉价 3. **背压优于指令** —— 设计能自动拒绝错误输出的环境
---
## 三阶段工作流
``` ┌─────────────────────────────────────────────────────────────────────┐ │ Phase 1: REQUIREMENTS │ │ Human + LLM conversation → JTBD → Topics → specs/*.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 2: PLANNING │ │ Gap analysis (specs vs code) → IMPLEMENTATION_PLAN.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 3: BUILDING │ │ One task per iteration → fresh context → backpressure → commit │ └─────────────────────────────────────────────────────────────────────┘ ```
### 第一阶段：需求（与人类交流）
**目标：** 在构建之前理解要构建什么。
这是最重要的阶段。使用结构化对话来：
1. **识别待完成任务 (JTBD)** - 我们正在解决什么用户需求或结果？ - 不是功能 —— 而是结果
2. **将 JTBD 分解为关注主题** - 每个主题 = 一个独特的方面/组件 - 使用“不含'and'的单句测试” - ✓ "颜色提取系统分析图像以识别主色调" - ✗ "用户系统处理身份验证、个人资料和计费" → 3 个主题
3. **为每个主题创建规格说明** - 在 `specs/` 中为每个主题创建一个 Markdown 文件 - 捕获需求、验收标准、边缘情况
**模板：** `templates/requirements-interview.md`
### 第二阶段：规划（差距分析）
**目标：** 创建一个优先任务列表而不实施任何内容。
在循环中使用 `PROMPT_plan.md`： - 研究所有规格说明 - 研究现有代码库 - 比较规格说明与代码（差距分析） - 生成带有优先任务的 `IMPLEMENTATION_PLAN.md` - **不实施** —— 仅规划
通常在 1-2 次迭代内完成。
### 第三阶段：构建（每次迭代一个任务）
**目标：** 使用全新的上下文一次实现一个任务。
在循环中使用 `PROMPT_build.md`： 1. 读取 `IMPLEMENTATION_PLAN.md` 2. 选择最重要的任务 3. 调查代码库（不要假设未实现） 4. 实施 5. 运行验证（背压） 6. 更新计划，提交 7. 退出 → 全新上下文 → 下一次迭代
**核心洞察：** 每次迭代一个任务可保持上下文精简。代理保持在“智能区域”，而不是累积陈旧代码。
**为什么全新上下文很重要：** - **无累积错误** —— 每次迭代都从零开始；之前的错误不会叠加 - **完整的上下文预算** —— 用于此任务的 200K Token，不与已完成的工作共享 - **减少幻觉** —— 较短的上下文 = 更基于事实的响应 - **自然的检查点** —— 每次提交都是一个保存点；易于恢复单次迭代
---
## 文件结构
``` project/ ├── loop.sh # Ralph loop script ├── PROMPT_plan.md # Planning mode instructions ├── PROMPT_build.md # Building mode instructions ├── AGENTS.md # Operational guide (~60 lines max) ├── IMPLEMENTATION_PLAN.md # Prioritized task list (generated) └── specs/ # Requirement specs ├── topic-a.md ├── topic-b.md └── ... ```
### 文件用途
| 文件 | 用途 | 创建者 | |------|---------|-------------| | `specs/*.md` | 需求的单一事实来源 | 人类 + 第一阶段 | | `PROMPT_plan.md` | 规划模式的指令 | 从模板复制 | | `PROMPT_build.md` | 构建模式的指令 | 从模板复制 | | `AGENTS.md` | 构建/测试/Lint 命令 | 人类 + Ralph | | `IMPLEMENTATION_PLAN.md` | 带有优先级的任务列表 | Ralph （第二阶段） |
### 项目组织（系统）
对于 Clawdbot 系统，每个 Ralph 项目位于 `<workspace>/systems/<name>/`：
``` systems/ ├── health-tracker/ # Example system │ ├── specs/ │ │ ├── daily-tracking.md │ │ └── test-scheduling.md │ ├── PROMPT_plan.md │ ├── PROMPT_build.md │ ├── AGENTS.md │ ├── IMPLEMENTATION_PLAN.md # ← exists = past Phase 1 │ └── src/ └── activity-planner/ ├── specs/ # ← empty = still in Phase 1 └── ... ```
### 阶段检测（自动）
通过检查存在哪些文件来检测当前阶段：
| 存在什么 | 当前阶段 | 下一步操作 | |-------------|---------------|-------------| | 无内容 / 空的 `specs/` | 第一阶段：需求 | 运行需求面试 | | `specs/*.md` 但没有 `IMPLEMENTATION_PLAN.md` | 准备好第二阶段 | 运行 `./loop.sh plan` | | `specs/*.md` + `IMPLEMENTATION_PLAN.md` | 第二阶段或第三阶段 | 审查计划，运行 `./loop.sh build` | | 计划显示所有任务完成 | 完成 | 归档或迭代 |
**快速检查：** ```bash # What phase are we in? [ -z "$(ls specs/ 2>/dev/null)" ] && echo "Phase 1: Need specs" && exit [ ! -f IMPLEMENTATION_PLAN.md ] && echo "Phase 2: Need plan" && exit echo "Phase 3: Ready to build (or done)" ```
---
## JTBD 分解
层级结构很重要：
``` JTBD (Job to Be Done) └── Topic of Concern (1 per spec file) └── Tasks (many per topic, in IMPLEMENTATION_PLAN.md) ```
**示例：** - **JTBD：** "帮助设计师创建情绪板" - **主题：** - 图像收集 → `specs/image-collection.md` - 颜色提取 → `specs/color-extraction.md` - 布局系统 → `specs/layout-system.md` - 分享 → `specs/sharing.md` - **任务：** 每个规格说明生成多个实施任务
### 主题范围测试
> 你能否用不含"and"的一句话描述该主题？
如果您需要"and"或"also"，那可能是多个主题。拆分它。
**何时拆分：** - 描述中有多个动词 → 拆分为不同的主题 - 涉及不同的用户角色 → 拆分为不同的主题 - 可能由不同的团队实施 → 拆分为不同的主题 - 有其自己的失败模式 → 可能是它自己的主题
**拆分示例：** ``` ❌ "User management handles registration, authentication, profiles, and permissions"
✅ Split into: - "Registration creates new user accounts from email/password" - "Authentication verifies user identity via login flow" - "Profiles let users view and edit their information" - "Permissions control what actions users can perform" ```
**反例（不要拆分）：** ``` ✅ Keep together: "Color extraction analyzes images and returns dominant color palettes" Why: "analyzes" and "returns" are steps in one operation, not separate concerns. ```
---
## 背压机制
当错误输出被拒绝时，自主循环会收敛。三个层次：
### 1. 下游闸门（硬） 测试、类型检查、Linting、构建验证。确定性的。 ```markdown # In AGENTS.md ## Validation - Tests: `npm test` - Typecheck: `npm run typecheck` - Lint: `npm run lint` ```
### 2. 上游引导（软） 现有的代码模式引导代理。它通过探索发现约定。
### 3. LLM 即法官（主观） 对于主观标准（语气、UX、美学），使用另一个 LLM 调用进行通过/失败二元判断。
> 从硬闸门开始。仅在机械背压有效后，才为主观标准添加 LLM 即法官。
---
## 提示词结构
Geoffrey 的提示词遵循编号模式：
| 章节 | 用途 | |---------|---------| | 0a-0d | **定向：** 研究规格说明、源代码、当前计划 | | 1-4 | **主要指令：** 本次迭代做什么 | | 999+ | **护栏：** 不变量（数字越大 = 越关键） |
### 编号护栏模式
护栏使用递增的数字（99999, 999999, 9999999...）来表示优先级：
```markdown 99999. Important: Capture the why in documentation.
999999. Important: Single sources of truth, no migrations.
9999999. Create git tags after successful builds.
99999999. Add logging if needed to debug.
999999999. Keep IMPLEMENTATION_PLAN.md current. ```
**为什么有效：** 1. **视觉显著性** —— 大数字很突出，更难跳过 2. **隐含优先级** —— 9 越多越关键（类似于反过来的 DEFCON 级别） 3. **无冲突** —— 稀疏编号允许您在不重新编号的情况下插入新规则 4. **助记符** —— Claude 将这些视为不变量，而非建议
**"Important:"前缀**是故意的 —— 它会触发 Claude 的注意力。
### 关键语言模式
使用 Geoffrey 的特定措辞 —— 这很重要：
- "study"（不是 "read" 或 "look at"） - "don't assume not implemented"（关键！） - "using parallel subagents" / "up to N subagents" - "only 1 subagent for build/tests"（背压控制） - "Ultrathink"（深度推理触发器） - "capture the why" - "keep it up to date" - "resolve them or document them"
---
## 快速开始
### 1. 设置项目结构
```bash mkdir -p myproject/specs cd myproject git init # Ralph expects git for commits
# Copy templates cp .//templates/PROMPT_plan.md . cp .//templates/PROMPT_build.md . cp .//templates/AGENTS.md . cp .//templates/loop.sh . chmod +x loop.sh ```
### 2. 自定义模板（必须！）
**PROMPT_plan.md** — 将 `[PROJECT_GOAL]` 替换为您的实际目标： ```markdown # Before: ULTIMATE GOAL: We want to achieve [PROJECT_GOAL].
# After: ULTIMATE GOAL: We want to achieve a fully functional mood board app with image upload and color extraction. ```
**PROMPT_build.md** — 如果未使用 `src/`，请调整源路径： ```markdown # Before: 0c. For reference, the application source code is in `src/*`.
# After: 0c. For reference, the application source code is in `lib/*`. ```
**AGENTS.md** — 更新您技术栈的构建/测试/Lint 命令。
### 3. 第一阶段：需求收集（不要跳过！）
此阶段与人类一起进行。使用面试模板：
```bash cat .//templates/requirements-interview.md ```
**工作流程：** 1. 讨论 JTBD（待完成任务）—— 关注结果，而非功能 2. 拆分为关注点 —— 每个都通过“一句话”测试 3. 为每个主题编写规范文件：`specs/topic-name.md` 4. 人工审查并批准规范
**示例输出：** ``` specs/ ├── image-collection.md ├── color-extraction.md ├── layout-system.md └── sharing.md ```
### 4. 第二阶段：规划
```bash ./loop.sh plan ```
等待 `IMPLEMENTATION_PLAN.md` 生成（通常 1-2 次迭代）。审查它 —— 这是你的任务列表。
### 5. 第三阶段：构建
```bash ./loop.sh build 20 # Max 20 iterations ```
观察其运行。随着模式的出现，增加反压（测试、检查）。检查提交进度。
---
## 循环脚本选项
```bash ./loop.sh # Build mode, unlimited ./loop.sh 20 # Build mode, max 20 iterations ./loop.sh plan # Plan mode, unlimited ./loop.sh plan 5 # Plan mode, max 5 iterations ```
或者使用 Node.js 封装器以获得更多控制：
```bash node skills/ralph-loops/scripts/ralph-loop.mjs \ --prompt "./PROMPT_build.md" \ --model opus \ --max 20 \ --done "RALPH_DONE" ```
---
## 何时重新生成计划
计划会偏移。当出现以下情况时重新生成：
- Ralph 偏离轨道（实施了错误的内容） - 计划感觉陈旧或与当前状态不匹配 - 已完成项目产生的杂乱过多 - 你对规范做了重大更改 - 你对实际完成的内容感到困惑
只需切换回规划模式：
```bash ./loop.sh plan ```
重新生成的成本是一次规划循环。相比于 Ralph 兜圈子，这很便宜。
---
## 安全性
Ralph 需要 `--dangerously-skip-permissions` 才能自主运行。这完全绕过了 Claude 的权限系统。
**理念：** “不是会不会出问题，而是什么时候出问题。以及爆炸半径是多少？”
**防护措施：** - 在隔离环境中运行（Docker、VM） - 仅提供任务所需的 API 密钥 - 除了需求外，无法访问私有数据 - 尽可能限制网络连接 - **逃生舱：** Ctrl+C 停止循环；`git reset --hard` 恢复未提交的更改
---
## 成本预期
| 任务类型 | 模型 | 迭代次数 | 预估成本 | |-----------|-------|------------|-----------| | 生成计划 | Opus | 1-2 | $0.50-1.00 | | 实现简单功能 | Opus | 3-5 | $1.00-2.00 | | 实现复杂功能 | Opus | 10-20 | $3.00-8.00 | | 完整项目构建 | Opus | 50+ | $15-50+ |
**提示：** 对于计划明确的简单任务，请使用 Sonnet。对于规划和复杂推理，请使用 Opus。
---
## 现实世界成果
来自 Geoffrey Huntley： - 在 YC 黑客松上过夜生成了 6 个代码仓库 - 仅花费 $297 的 API 费用就完成了 $50k 的合同 - 在 3 个月内创建了整个编程语言
---
## 高级用法：作为子代理运行
对于长循环，将其作为子代理生成，以便主会话保持响应：
```javascript sessions_spawn({ task: `cd /path/to/project && ./loop.sh build 20 Summarize what was implemented when done.`, label: "ralph-build", model: "opus" }) ```
检查进度： ```javascript sessions_list({ kinds: ["spawn"] }) sessions_history({ label: "ralph-build", limit: 5 }) ```
---
## 故障排除
### Ralph 一直在实施相同的内容 - 计划陈旧 → 使用 `./loop.sh plan` 重新生成 - 缺少反压 → 添加能捕获重复内容的测试
### Ralph 兜圈子 - 在提示词中添加更具体的护栏 - 检查规范是否模棱两可 - 重新生成计划
### 上下文变得臃肿 - 确保每次迭代一个任务（检查提示词） - 保持 AGENTS.md 在 60 行以内 - 将状态/进度移至 IMPLEMENTATION_PLAN.md，而不是 AGENTS.md
### 测试未运行 - 检查 AGENTS.md 是否有正确的验证命令 - 确保提示词中的反压部分引用了 AGENTS.md
---
## 边缘情况
### 没有 Git 的项目
循环脚本需要 git 来进行提交和推送。对于没有版本控制的项目：
**选项 1：无论如何都初始化 git**（推荐） ```bash git init git add -A git commit -m "Initial commit before Ralph" ```
**选项 2：修改提示词** - 从 PROMPT_build.md 中删除与 git 相关的护栏 - 从 loop.sh 中删除 git push 部分 - 改用文件备份：将 `cp -r src/ backups/iteration-$ITERATION/` 添加到 loop.sh
**选项 3：使用 tarball 快照** ```bash # Add to loop.sh before each iteration: tar -czf "snapshots/pre-iteration-$ITERATION.tar.gz" src/ ```
### 非常大的代码库
对于拥有 10 万行以上代码的代码库：
- **减少子代理并行度：** 在提示词中将“最多 500 个并行 Sonnet 子代理”更改为“最多 50 个” - **缩小范围：** 使用针对特定目录的聚焦规范 - **添加路径限制：** 在 AGENTS.md 中，记录哪些目录在范围内 - **考虑拆分工作区：** 将大型模块视为单独的 Ralph 项目
### 当 Claude CLI 不可用时
该方法适用于任何 Claude 接口：
**直接使用 Claude API：** ```bash # Replace loop.sh with API calls using curl or a script curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "content-type: application/json" \ -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 8192, "messages": [...]}' ```
**替代代理：** - **Aider：** `aider --opus --auto-commits` - **Continue.dev：** 与 Claude API 密钥一起使用 - **Cursor：** 使用 Composer 模式，并将 PROMPT 文件作为上下文
无论使用何种工具，关键原则（每次迭代一个任务、全新上下文、反压）都适用。
### 非 Node.js 项目
根据你的技术栈调整 AGENTS.md：
| 技术栈 | 构建 | 测试 | Lint | |-------|-------|------|------| | Python | `pip install -e .` | `pytest` | `ruff .` | | Go | `go build ./...` | `go test ./...` | `golangci-lint run` | | Rust | `cargo build` | `cargo test` | `cargo clippy` | | Ruby | `bundle install` | `rspec` | `rubocop` |
同时更新提示词中的路径引用（`src/*` → 你的源代码目录）。
---
## 了解更多
- Geoffrey Huntley: https://ghuntley.com/ralph/ - Clayton Farr's Playbook: https://github.com/ClaytonFarr/ralph-playbook - Geoffrey's Fork: https://github.com/ghuntley/how-to-ralph-wiggum
---
## 致谢
由 **Johnathan & Q** 构建 —— 一个人类-AI 二元组。
- Twitter: [@spacepixel](https://x.com/spacepixel) - ClawdHub: [clawhub.ai/skills/ralph-loops](https://www.clawhub.ai/skills/ralph-loops)