Ralph Loops
拉尔夫循环技能
初次使用？请阅读SETUP.md首先安装依赖并验证您的设置。
用于迭代开发的自主AI代理循环。基于Geoffrey Huntley的拉尔夫·维古姆技术，由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的孤立子代理。首次运行时迭代会因"退出代码null"而失败。
修复方法：降级到 2.1.25：
npm install -g @anthropic-ai/claude-code@2.1.25
验证：
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
如何在不阻塞的情况下监控：
- 使用命令启动循环
node ralph-loop.mjs ...（在后台运行） - 告知用户："循环正在运行。我会定期检查进度，您也可以随时询问。"
- 通过以下方式检查
process poll <sessionId>当被询问时或在心跳期间 - 使用位于http://localhost:3939的仪表板
以获得实时可见性— 这正是关键所在。不要为了过度关注它而忽略了你的人类用户。
触发短语
当人类说：
| 短语 | 行动 |
|---|---|
| "针对系统X对我进行访谈" | 启动第一阶段需求访谈 |
| "开始规划系统X" | 运行./loop.sh plan（需要先有规格说明） |
| "开始构建系统X" | 运行./loop.sh build（需要先有计划） |
| "对X进行Ralph循环" | 询问是哪个阶段（见下文） |
当人类说"Ralph循环"时 — 请明确阶段！
不要假设是哪个阶段。请询问：
"我们要进行哪种类型的Ralph循环？
1️⃣访谈— 我将通过提问来制定规格说明（第一阶段） 2️⃣规划— 我将迭代制定实施计划（第二阶段）
3️⃣构建— 我将根据计划进行实施，每次迭代完成一项任务（第三阶段） 4️⃣通用— 针对单一主题进行简单的迭代优化"
然后根据他们的回答进行后续操作：
| 选择 | 行动 |
|---|---|
| 访谈 | 使用templates/requirements-interview.md协议 |
| 规划 | 需要先制定规格说明 → 使用PROMPT_plan.md |
| 运行规划循环 | 构建需要先制定计划 → 使用 |
| PROMPT_build.md | 运行构建循环ralph-loop.mjs直接地 |
通用拉尔夫循环流程（第四阶段）
适用于简单迭代优化（非完整系统构建）：
- 澄清任务——具体需要改进/优化什么？
- 创建提示文件——保存至
/tmp/ralph-prompt-<任务>.md - 设定完成标准——什么信号代表“完成”？
- 运行循环：
node skills/ralph-loops/scripts/ralph-loop.mjs \ --prompt "/tmp/ralph-prompt-<task>.md" \ --model opus \ --max 10 \ --done "RALPH_DONE" - 或作为子代理启动用于长时间运行任务
核心理念
“人类角色从‘告诉代理要做什么’转变为‘设计条件，让良好结果通过迭代自然涌现’。” ——克莱顿·法尔
三大原则驱动一切：
- 上下文是稀缺的——在20万令牌窗口中约17.6万可用令牌，保持每次迭代精简
- 计划是可抛弃的— 漂移计划再生比修复更廉价
- 反向压力胜过方向指引— 构建能自动拒绝错误输出的工程环境
三阶段工作流
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────────────┘
阶段一：需求分析（与人沟通）
目标：在构建之前理解要构建什么
这是最重要的阶段。通过结构化对话实现：
-
识别待完成工作（JTBD）
- 我们要解决的用户需求或成果是什么？
- 不是功能特性——而是成果
-
将JTBD分解为关注主题
- 每个主题 = 一个独立方面/组件
- 使用“不含‘和’字的单句”测试法
- ✓ “颜色提取系统通过分析图像识别主色调”
- ✗ “用户系统处理身份验证、个人资料和账单”→ 应拆分为3个主题
-
为每个主题创建规格说明
- 每个主题对应specs/目录下的一个markdown文件
specs/ - 捕获需求、验收标准、边缘情况
- 每个主题对应specs/目录下的一个markdown文件
模板： templates/requirements-interview.md
阶段 2：规划（差距分析）
目标：创建一份优先任务清单，但不进行任何实现。
使用PROMPT_plan.md在循环中：
- 研究所有规格说明
- 研究现有代码库
- 比较规格说明与代码（差距分析）
- 生成
IMPLEMENTATION_PLAN.md包含优先任务 - 不进行实现—— 仅规划
通常需要 1-2 次迭代完成。
阶段 3：构建（每次迭代一个任务）
目标：每次使用新上下文逐一实现任务。
使用PROMPT_build.md在循环中：
- 阅读
IMPLEMENTATION_PLAN.md - 选择最重要的任务
- 调查代码库（不要假设未实现）
- 实施
- 运行验证（背压）
- 更新计划，提交
- 退出 → 新上下文 → 下一次迭代
关键见解：每次迭代一个任务，保持上下文简洁。智能体保持在"智能区"，而不是积累冗余信息。
为什么新上下文很重要：
- 无累积错误— 每次迭代从零开始；之前的错误不会叠加
- 完整的上下文预算— 20万令牌用于当前任务，不与已完成的工作共享
- 减少幻觉— 更短的上下文 = 更基于现实的响应
- 自然的检查点— 每次提交都是一个保存点；易于回滚单次迭代
文件结构
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 | 需求的事实来源 | 人工 + 阶段 1 |
PROMPT_plan.md | 规划模式指令 | 从模板复制 |
PROMPT_build.md | 构建模式指令 | 从模板复制 |
AGENTS.md | 构建/测试/代码检查命令 | 人工 + Ralph |
IMPLEMENTATION_PLAN.md | 带优先级的任务列表 | Ralph (阶段 2) |
项目组织（系统）
对于 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/ 目录 | 阶段 1：需求 | 运行需求访谈 |
specs/*.md 文件但没有IMPLEMENTATION_PLAN.md 文件 | 准备进入阶段 2 | 运行./loop.sh plan |
specs/*.md 文件加上IMPLEMENTATION_PLAN.md 文件 | 阶段 2 或 3 | 审查计划，运行./loop.sh build |
| 计划显示所有任务已完成 | 完成 | 归档或进入下一轮迭代 |
快速检查：
# 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
- 图像收集 →
- 任务：每个规范生成多个实施任务
主题范围测试
能否用一句话描述该主题而不使用“和”字？
如果需要使用“和”或“也”，很可能涉及多个主题。请拆分。
何时拆分：
- 描述中包含多个动词 → 拆分为不同主题
- 涉及不同的用户角色 → 拆分为不同主题
- 可由不同团队实施 → 拆分为不同主题
- 它有自己的失效模式 → 可能是个独立主题
示例分割：
❌ "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. 下游关卡（硬性）
测试、类型检查、代码规范检查、构建验证。具有确定性。
# In AGENTS.md
## Validation
- Tests: `npm test`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
2. 上游引导（软性）
现有代码模式指导代理。它通过探索发现约定。
3. LLM作为评判者（主观性）
对于主观标准（语气、用户体验、美学），使用另一个LLM调用进行二元通过/失败判定。
从硬性关卡开始。仅在机械反压机制生效后，才针对主观标准添加LLM作为评判者。
提示结构
杰弗里的提示遵循编号模式：
| 部分 | 目的 |
|---|---|
| 0a-0d | 定向：研究规范、源代码、当前计划 |
| 1-4 | 主要指示本次迭代要做什么 |
| 999+ | 防护栏：不变式（数字越大越关键） |
编号防护栏模式
防护栏使用递增的数字（99999、999999、9999999...）来表示优先级：
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.
为什么有效：
- 视觉突出性—— 大数字更显眼，更难被忽略
- 隐含优先级—— 9越多 = 越关键（类似于反向的DEFCON等级）
- 无冲突—— 稀疏的编号让你可以在不重新编号的情况下插入新规则
- 助记性—— Claude将这些视为不变式，而非建议
"Important:"前缀是刻意为之的——它能触发Claude的注意力。
关键语言模式
使用Geoffrey的特定措辞——这很重要：
- "study"（而非"read"或"look at"）
- "不要假设未实现"（关键！）
- "使用并行子代理" / "最多N个子代理"
- "构建/测试仅使用1个子代理"（反压控制）
- "Ultrathink"（深度推理触发器）
- "抓住原因"
- "保持最新状态"
- "解决它们或记录下来"
快速开始
1. 设置项目结构
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]为您的实际目标：
# 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/，请调整源路径：
# Before:
0c. For reference, the application source code is in `src/*`.
# After:
0c. For reference, the application source code is in `lib/*`.
AGENTS.md— 为您的技术栈更新构建/测试/代码检查命令。
3. 阶段1：需求收集（不要跳过！）
此阶段需与人类共同完成。请使用访谈模板：
cat .//templates/requirements-interview.md
工作流程：
- 讨论待办任务（JTBD）——关注成果，而非功能
- 分解为关注主题（每个主题需通过“一句话”测试）
- 为每个主题编写规范文件：
specs/主题名称.md - 人工评审并批准规范
示例输出：
specs/
├── image-collection.md
├── color-extraction.md
├── layout-system.md
└── sharing.md
4. 第二阶段：规划
./loop.sh plan
等待IMPLEMENTATION_PLAN.md生成（通常需要1-2次迭代）。审阅该文件——这是您的任务清单。
5. 第三阶段：构建
./loop.sh build 20 # Max 20 iterations
观察其运行。随着模式出现，添加反向压力（测试、代码检查）。通过提交记录检查进度。
循环脚本选项
./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包装器以获得更多控制：
node skills/ralph-loops/scripts/ralph-loop.mjs \
--prompt "./PROMPT_build.md" \
--model opus \
--max 20 \
--done "RALPH_DONE"
何时重新生成计划
计划会发生漂移。在以下情况时重新生成：
- Ralph偏离轨道（正在实现错误的内容）
- 计划感觉过时或与当前状态不符
- 已完成事项造成太多混乱
- 你对规格做了重大修改
- 你对实际完成情况感到困惑
只需切换回规划模式：
./loop.sh plan
重新生成成本仅为一个规划循环。相比Ralph原地打转来说很便宜。
安全须知
Ralph需要--dangerously-skip-permissions参数才能自主运行。这会完全绕过Claude的权限系统。
核心理念：“问题不在于是否会出故障，而在于何时出故障。以及影响范围有多大？”
防护措施：
- 在隔离环境中运行（Docker、虚拟机）
- 仅提供任务所需的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个代码仓库
- 一份价值5万美元的合同，仅花费了297美元的API成本就完成了
- 在三个月内创建了完整的编程语言
高级：作为子代理运行
对于长循环，请作为子代理生成，以保持主会话响应：
sessions_spawn({
task: `cd /path/to/project && ./loop.sh build 20
Summarize what was implemented when done.`,
label: "ralph-build",
model: "opus"
})
检查进度：
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（推荐）
git init
git add -A
git commit -m "Initial commit before Ralph"
选项 2：修改提示词
- 从 PROMPT_build.md 中移除与 Git 相关的防护措施
- 从 loop.sh 中移除 Git 推送部分
- 改用文件备份：在 loop.sh 中添加
cp -r src/ backups/iteration-$ITERATION/选项 3：使用压缩包快照
超大型代码库
# Add to loop.sh before each iteration:
tar -czf "snapshots/pre-iteration-$ITERATION.tar.gz" src/
对于超过 10 万行代码的代码库：
减少子代理并行度：
- 在提示词中将“最多 500 个并行 Sonnet 子代理”改为“最多 50 个”限定范围：
- 使用针对特定目录的聚焦式规范说明添加路径限制：
- 在 AGENTS.md 中注明哪些目录在范围内In AGENTS.md, note which directories are in-scope
- 考虑工作空间拆分：将大型模块视为独立的Ralph项目
当Claude CLI不可用时
该方法适用于任何Claude界面：
直接使用Claude API：
# 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：组合器模式，使用PROMPT文件作为上下文
无论使用何种工具，关键原则（每次迭代一个任务、全新上下文、反向压力）都适用。
非Node.js项目
根据你的技术栈调整AGENTS.md：
| 技术栈 | 构建 | 测试 | 代码检查 |
|---|---|---|---|
| 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 的 Playbook:https://github.com/ClaytonFarr/ralph-playbook
- Geoffrey 的分支:https://github.com/ghuntley/how-to-ralph-wiggum
致谢
由以下人员构建Johnathan & Q— 一个人机协作体。
- Twitter：@spacepixel
- ClawdHub：clawhub.ai/skills/ralph-loops
微信扫一扫，打赏作者吧～
