Ralph Loops 技能

第一次使用？ 请先阅读 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 存在一个严重错误，会生成占用 99% CPU 的孤立子代理。首次运行时迭代会因 "exit code null" 而失败。

修复方法： 降级到 2.1.25：

npm install -g @anthropic-ai/claude-code@2.1.25

验证：

claude --version  # 应显示 2.1.25

此问题于 2026-02-01 发现。在升级前请检查新版本是否已修复该问题。

⚠️ 不要阻塞对话！

运行 Ralph 循环时，不要同步监控它。循环作为独立的 Claude CLI 进程运行——你可以继续聊天。

❌ 错误做法（阻塞对话）：

启动循环 → 休眠 60 秒 → 轮询 → 休眠 60 秒 → 轮询 → ...（6 分钟沉默）

✅ 正确做法（保持响应）：

启动循环 → "循环正在运行，我会定期检查" → 继续聊天 → 检查心跳

如何在不阻塞的情况下监控：
1. 使用 node ralph-loop.mjs ... 启动循环（在后台运行）
2. 告诉人类："循环正在运行。我会定期检查进度，或者你可以随时询问。"
3. 在被询问时或心跳期间通过 process poll <sessionId> 检查
4. 使用 http://localhost:3939 上的仪表板进行实时查看

循环是自主运行的——这正是其核心所在。不要为了监控它而忽略与你对话的人类。

触发短语

当人类说：

当人类说 "Ralph 循环" 时——请明确阶段！

不要假设阶段。请询问：

"我们正在进行哪种类型的 Ralph 循环？

1️⃣ 访谈 — 我将通过提问来构建规格说明（第 1 阶段）
2️⃣ 规划 — 我将迭代制定实施计划（第 2 阶段）
3️⃣ 构建 — 我将根据计划实施，每次迭代一个任务（第 3 阶段）
4️⃣ 通用 — 对单一主题进行简单的迭代优化"

然后根据他们的回答进行：

通用 Ralph 循环流程（第 4 阶段）

用于简单的迭代优化（非完整系统构建）：

1. 明确任务 — 具体需要改进/优化什么？
2. 创建提示文件 — 保存到 /tmp/ralph-prompt-<任务>.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. 反向压力优于直接指导 — 设计能自动拒绝错误输出的环境

三阶段工作流

┌─────────────────────────────────────────────────────────────────────┐
│  第 1 阶段：需求                                                    │
│  人类 + LLM 对话 → JTBD → 主题 → specs/*.md                         │
├─────────────────────────────────────────────────────────────────────┤
│  第 2 阶段：规划                                                    │
│  差距分析（规格说明 vs 代码） → IMPLEMENTATION_PLAN.md              │
├─────────────────────────────────────────────────────────────────────┤
│  第 3 阶段：构建                                                    │
│  每次迭代一个任务 → 全新上下文 → 反向压力 → 提交                    │
└─────────────────────────────────────────────────────────────────────┘

第 1 阶段：需求（与人类对话）

目标： 在构建之前理解要构建什么。

这是最重要的阶段。使用结构化对话来：

1. 识别待完成工作

   • 我们要解决的用户需求或结果是什么？
   • 不是功能——是结果

2. 将 JTBD 分解为关注主题

   • 每个主题 = 一个不同的方面/组件
   • 使用"一句话且不含'和'"测试
   • ✓ "颜色提取系统分析图像以识别主色调"
   • ✗ "用户系统处理身份验证、配置文件和计费" → 3 个主题

3. 为每个主题创建规格说明

   • 在 specs/ 中每个主题一个 markdown 文件
   • 捕获需求、验收标准、边界情况

模板： templates/requirements-interview.md

第 2 阶段：规划（差距分析）

目标： 创建优先任务列表，但不实施任何内容。

在循环中使用 PROMPT_plan.md：
- 研究所有规格说明
- 研究现有代码库
- 比较规格说明与代码（差距分析）
- 生成带有优先级的 IMPLEMENTATION_PLAN.md 任务列表
- 不进行实施——仅规划

通常 1-2 次迭代即可完成。

第 3 阶段：构建（每次迭代一个任务）

目标： 在全新上下文中逐个实施任务。

在循环中使用 PROMPT_build.md：
1. 读取 IMPLEMENTATION_PLAN.md
2. 选择最重要的任务
3. 调查代码库（不要假设未实现）
4. 实施
5. 运行验证（反向压力）
6. 更新计划，提交
7. 退出 → 全新上下文 → 下一次迭代

关键见解： 每次迭代一个任务可以保持上下文简洁。代理保持在"智能区域"，而不是积累冗余。

为什么全新上下文很重要：
- 没有累积的错误 — 每次迭代都从干净状态开始；之前的错误不会叠加
- 完整的上下文预算 — 200K token 用于此任务，不与已完成的工作共享
- 减少幻觉 — 更短的上下文 = 更可靠的响应
- 自然的检查点 — 每次提交都是一个保存点；易于回滚单个迭代

文件结构

project/
├── loop.sh                    # Ralph 循环脚本
├── PROMPT_plan.md             # 规划模式指令
├── PROMPT_build.md            # 构建模式指令
├── AGENTS.md                  # 操作指南（最多约 60 行）
├── IMPLEMENTATION_PLAN.md     # 优先级任务列表（生成）
└── specs/                     # 需求规格说明
    ├── topic-a.md
    ├── topic-b.md
    └── ...

文件用途

项目组织（系统）

对于 Clawdbot 系统，每个 Ralph 项目位于 <workspace>/systems/<name>/：

systems/
├── health-tracker/           # 示例系统
│   ├── specs/
│   │   ├── daily-tracking.md
│   │   └── test-scheduling.md
│   ├── PROMPT_plan.md
│   ├── PROMPT_build.md
│   ├── AGENTS.md
│   ├── IMPLEMENTATION_PLAN.md  # ← 存在 = 已过第 1 阶段
│   └── src/
└── activity-planner/
    ├── specs/                  # ← 空 = 仍在第 1 阶段
    └── ...

阶段检测（自动）

通过检查存在的文件来检测当前阶段：

快速检查：

# 我们处于哪个阶段？
[ -z "$(ls specs/ 2>/dev/null)" ] && echo "第 1 阶段：需要规格说明" && exit
[ ! -f IMPLEMENTATION_PLAN.md ] && echo "第 2 阶段：需要计划" && exit
echo "第 3 阶段：准备构建（或已完成）"

JTBD 分解

层次结构很重要：

JTBD
└── 关注主题（每个规格说明文件一个）
    └── 任务（每个主题多个，在 IMPLEMENTATION_PLAN.md 中）

示例：
- JTBD： "帮助设计师创建情绪板"
- 主题：
- 图像收集 → specs/image-collection.md
- 颜色提取 → specs/color-extraction.md
- 布局系统 → specs/layout-system.md
- 分享 → specs/sharing.md
- 任务： 每个规格说明生成多个实施任务

主题范围测试

你能用一句话描述这个主题，且不含"和"吗？

如果需要"和"或"也"，那可能是多个主题。拆分它。

何时拆分：
- 描述中有多个动词 → 拆分为单独的主题
- 涉及不同的用户角色 → 拆分为单独的主题
- 可以由不同的团队实施 → 拆分为单独的主题
- 有自己的故障模式 → 可能是一个独立的主题

拆分示例：

❌ "用户管理处理注册、身份验证、配置文件和权限"

✅ 拆分为：
   - "注册通过邮箱/密码创建新用户账户"
   - "身份验证通过登录流程验证用户身份"
   - "配置文件让用户查看和编辑其信息"
   - "权限控制用户可以执行的操作"

反例（不要拆分）：

✅ 保持在一起：
   "颜色提取分析图像并返回主色调调色板"

   为什么："分析"和"返回"是一个操作中的步骤，不是独立的关注点。

反向压力机制

当错误输出被拒绝时，自主循环会收敛。三个层次：

1. 下游关卡（硬性）

测试、类型检查、代码检查、构建验证。确定性的。

# 在 AGENTS.md 中
## 验证
- 测试：`npm test`
- 类型检查：`npm run typecheck`
- 代码检查：`npm run lint`

2. 上游引导（软性）

现有代码模式引导代理。它通过探索发现约定。

3. LLM 作为评判者（主观性）

对于主观标准（语气、用户体验、美学），使用另一个 LLM 调用进行二元通过/失败判断。

从硬性关卡开始。只有在机械反向压力有效后，才为主观标准添加 LLM 作为评判者。

提示结构

Geoffrey 的提示遵循编号模式：

编号防护栏模式

防护栏使用递增的数字（99999, 999999, 9999999...）来表示优先级：

99999. 重要：在文档中捕获原因。

999999. 重要：单一真实来源，无需迁移。

9999999. 成功构建后创建 git 标签。

99999999. 如需调试，添加日志记录。

999999999. 保持 IMPLEMENTATION_PLAN.md 最新。

为什么这有效：
1. 视觉突出 — 大数字更显眼，更难跳过
2. 隐含优先级 — 9 越多越关键（类似于反向的 DEFCON 等级）
3. 无冲突 — 稀疏编号允许插入新规则而无需重新编号
4. 助记性 — Claude 将这些视为不变式，而非建议

"重要："前缀是刻意的——它能触发 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. 设置项目结构

mkdir -p myproject/specs
cd myproject
git init  # Ralph 期望使用 git 进行提交

# 复制模板
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] 替换为你的实际目标：

# 之前：
ULTIMATE GOAL: We want to achieve [PROJECT_GOAL].

# 之后：
ULTIMATE GOAL: We want to achieve a fully functional mood board app with image upload and color extraction.

PROMPT_build.md — 如果不使用 src/，请调整源代码路径：

# 之前：
0c. For reference, the application source code is in `src/*`.

# 之后：
0c. For reference, the application source code is in `lib/*`.

AGENTS.md — 为你的技术栈更新构建/测试/检查命令。

3. 第 1 阶段：需求收集（不要跳过！）

此阶段与人类一起进行。使用访谈模板：

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. 第 2 阶段：规划

./loop.sh plan

等待生成 IMPLEMENTATION_PLAN.md（通常 1-2 次迭代）。审查它——这是你的任务列表。

5. 第 3 阶段：构建

./loop.sh build 20  # 最多 20 次迭代

观察其工作。随着模式出现，添加反向压力（测试、检查）。检查提交以了解进度。

循环脚本选项

./loop.sh              # 构建模式，无限制
./loop.sh 20           # 构建模式，最多 20 次迭代
./loop.sh plan         # 规划模式，无限制
./loop.sh plan 5       # 规划模式，最多 5 次迭代

或者使用 Node.js 包装器以获得更多控制：

```bash
node skills/ralph-loops/scripts/ralph-loop.mjs \
--prompt "./PROMPT_build.md" \
--model opus \
--max 20 \
--done "RALPH_D