阅读原文：如何让 Claude Code 长时间工作

一、本章核心学习目标

• 理解 AI 编程助手过早停止的核心原因，掌握长任务的迭代解决原理
• 学会使用 Ralph Wiggum 官方插件，实现自动化的长任务迭代
• 掌握长任务的 Prompt 编写技巧，定义明确可验证的完成标准
• 了解不同长任务方案的适用场景，学会根据任务选择合适的工具
• 掌握安全防护机制，防止无限循环和 API 成本失控

---

二、引言：为什么我们需要长任务？

传统的 AI 编程助手是 “对话式” 的 —— 你说一句，它回一句，然后停下了。但对于真正的开发任务来说，这种模式远远不够：

• 重构整个项目，写完几个文件就说 “我完成了”
• 持续修复 bug 直到测试全部通过，但它跑一次就停下来
• 想让 AI “过夜干活”，但第二天发现它早就停了

2025 年夏天，澳大利亚开发者 Geoffrey Huntley 写了一个 5 行的 bash 脚本，不断重启 Claude Code 并喂给它同样的任务，命名为 “Ralph Wiggum”。这个项目在 GitHub 两周内获得 7,000+ 星标，人们用它：

• 一晚上生成 6 个完整项目，$297 的 API 成本完成 $50,000 的合同
• 3 个月内构建了一门完整的编程语言

---

三、核心原理：为什么 AI 会 “过早停止”？

3.1 AI 的 “完成判断” 不可靠

LLM 有一个根本缺陷：它无法准确判断自己的工作是否真正完成。

• 人类的完成标准是客观的：所有测试通过、功能完整可用、代码质量达标
• AI 只能基于 “感觉” 来判断：觉得 “看起来差不多了”、“输出够多了” 就停下

3.2 解决方案的核心思想

解决方案的核心是：让 AI 在一个 “循环” 中工作。

每次它想退出时，外部系统会检查三个问题 —— 真的完成了吗？符合客观标准了吗？还有没有遗漏？如果没有，就重新注入任务，继续下一轮。

---

四、方法一：While True Bash Loop（最原始的方法）

这是最简单、最直接的实现方式，本质上就是写一个无限循环，每次循环都重新启动 Claude Code 并喂给它同样的任务描述。

4.1 最简实现

最简单的实现只需要 5 行代码：

#!/bin/bash
while true; do
 cat PROMPT.md | claude
done

4.2 工作原理

1. 读取 PROMPT.md 文件中的任务描述

2. 启动 Claude Code 并将任务描述传递给它

3. Claude 开始工作并输出结果

4. Claude 完成后退出

5. 循环自动重新启动，直到手动按 Ctrl+C 中断

4.3 优缺点

维度	说明
优点	极其简单，无需配置，立即可用，适合快速实验
缺点	无法判断任务是否真的完成，可能无限空转，没有安全保护

4.4 安全改进版

为了避免无限循环，可以添加迭代次数限制：

#!/bin/bash
MAX_ITERATIONS=50
iteration=0

while true; do
 iteration=$((iteration + 1))
 echo "=== 迭代 $iteration/$MAX_ITERATIONS ==="

 cat PROMPT.md | claude

 if [ $iteration -ge $MAX_ITERATIONS ]; then
 echo "达到最大迭代次数，停止"
 break
 fi

 sleep 5 # 稍作等待，避免 API 限流
done

---

五、方法二：Ralph Wiggum Plugin（官方推荐）

Ralph Wiggum 是 Anthropic 官方推出的插件，专门解决长时间任务问题，象征着 “尽管失败，仍坚持尝试” 的精神。

5.1 核心机制：Stop Hook

Ralph 的核心机制是 Stop Hook：

1. 当 Claude 想要退出时，Stop Hook 会拦截这个退出信号

2. 系统检查：输出了特定的完成标记吗？

3. 如果没有找到完成标记，就重新注入原始 prompt，开始下一轮迭代

4. 如果找到了完成标记，才允许 Claude 退出

5.2 安装方法

方式一：通过官方插件市场安装（推荐）

# 在 Claude Code 中运行
claude

# 添加官方插件市场
/plugin marketplace add anthropics/claude-code

# 安装 Ralph Wiggum
/plugin install ralph-wiggum@claude-code-plugins

# 验证安装
/plugin

方式二：直接从 GitHub 安装

# 进入插件目录
cd ~/.claude/plugins/

# 克隆插件仓库
git clone https://github.com/anthropics/ralph-wiggum-plugin.git

5.3 基本使用

基本使用方式是通过 /ralph-wiggum:ralph-loop 命令：

/ralph-wiggum:ralph-loop "构建一个待办事项 API，包含 CRUD 操作、输入验证、测试。
 全部完成后输出 <promise>COMPLETE</promise>" 
 --max-iterations 50 
 --completion-promise "COMPLETE"

关键参数说明：

• --max-iterations：最大迭代次数，安全机制，推荐 20-100 之间
• --completion-promise：完成标记文本，明确唯一的标识，比如 COMPLETE

5.4 Prompt 编写最佳实践

不好的 Prompt 没有明确的完成标准，AI 可能写个基础框架就说完成了。好的 Prompt 应该：

1. 分阶段描述任务，明确每一步要做什么

2. 列出详细的验收标准，比如测试通过、类型检查通过

3. 指定唯一的完成标记，让 Ralph 能判断任务结束

5.5 常用 Prompt 模板

模板 1：测试迁移（Jest → Vitest）

/ralph-wiggum:ralph-loop "
将项目中所有测试从 Jest 迁移到 Vitest：
- 保持所有测试逻辑不变
- 更新配置文件（vite.config.js、vitest.config.js）
- 替换 Jest 特有的 API（如 jest.mock → vi.mock）
- 确保所有测试通过
- 移除 Jest 相关依赖

验收标准：
- npm test 全部通过
- package.json 中无 jest 依赖
- 项目能正常构建

完成后输出：<promise>VITEST_MIGRATION_COMPLETE</promise>
" --max-iterations 40 --completion-promise "VITEST_MIGRATION_COMPLETE"

模板 2：UI/UX 优化（移动端优先）

/ralph-wiggum:ralph-loop "
把这个项目的 UI/UX 做得更像一款精致的、移动端优先的语言学习 App：
- 统一间距与留白（使用 4px 基础单位）
- 建立清晰的字体层级（标题/正文/辅助信息）
- 统一卡片、列表等组件样式
- 添加底部导航（Home/Learn/Quiz/Progress/Settings）
- 确保在移动设备上显示良好

验收标准：
- npm run build 成功
- 无 TypeScript 错误
- 主要页面在移动端预览正常

完成后输出：<promise>UI_UX_COMPLETE</promise>
" --max-iterations 25 --completion-promise "UI_UX_COMPLETE"

模板 3：批量添加 TypeScript 类型

/ralph-wiggum:ralph-loop "
给项目中所有函数添加 TypeScript 类型注解：
- 优先处理 src/ 目录
- 为函数参数和返回值添加类型
- 避免使用 any，使用具体类型或 unknown
- 添加必要的类型定义

验收标准：
- npm run typecheck 通过
- 无 @ts-ignore 或 @ts-any 注释
- 代码能正常运行

完成后输出：<promise>TYPES_ADDED</promise>
" --max-iterations 30 --completion-promise "TYPES_ADDED"

5.6 实战案例

• YC 黑客松案例：晚上 11 点设置任务，第二天醒来得到 6 个可演示项目，API 成本仅 $297
• Boris Cherny 案例：Claude Code 负责人用 Ralph 30 天提交 259 个 PR，新增 4 万行代码，全程无人工编码
• CURSED 编程语言：用 Ralph 在 3 个月内自主构建了一门完整的编程语言，包含 LLVM 编译器
• 遗留项目重构：周末运行 Ralph，周一回来项目完成 47 次提交，测试覆盖率达到 75%，成本约 $12

5.7 Ralph 的哲学

• 迭代大于完美：不要指望一次就完美，每次循环都比上一次更好
• 失败是数据：每次测试失败都是改进的机会，不要害怕失败
• 持续尝试：Keep trying until it works，这就是 Ralph 的精神

5.8 适用场景判断

✅ 适合使用 Ralph 的场景

场景	原因
测试迁移	有明确目标，测试通过即可验证
大规模重构	可以定义具体的重构规则
框架迁移	迁移完成后代码能正常运行
批量添加类型	typecheck 通过即完成
测试覆盖率提升	覆盖率百分比是客观指标
文档生成	API 文档可以自动验证
Bug 修复（有复现步骤）	测试通过即修复成功

❌ 不适合使用 Ralph 的场景

场景	原因
架构设计决策	微服务 vs 单体需要权衡
安全相关代码	安全漏洞可能很隐蔽
需求模糊的任务	没有明确完成标准
探索性工作	需要不断调整方向
创意性设计	需要人类审美判断
简单一次性任务	使用 Ralph 是浪费

判断标准：

1. 我能定义明确的完成标准吗？

2. 有客观的验证方法吗？（测试、构建、类型检查）

3. 这个任务需要我持续反馈吗？
   如果三个答案都是 “否”，那就放手让 Ralph 去做吧！

---

六、方法三：增强版 Ralph（社区优化）

这是社区对官方 Ralph 的增强实现，在 GitHub 上的 frankbria/ralph-claude-code 项目，增加了更多安全机制。

6.1 额外特性

• 双重退出条件：需要同时满足完成标记和显式 EXIT_SIGNAL 才会停止
• 速率限制功能：默认 100 次 / 小时，防止 API 账单爆炸
• 智能熔断器：连续 5 次检测到完成标记就强制退出
• 实时仪表盘：显示迭代次数、进度、预估成本

6.2 安装与使用

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

# 初始化项目
ralph-setup my-project

# 启动循环
ralph loop

6.3 配置文件

{
 "maxIterations": 50,
 "rateLimitPerHour": 100,
 "completionPromise": "TASK_COMPLETE",
 "exitSignal": "EXIT_NOW",
 "costAlertThresholds": [10, 50, 100]
}

---

七、方法四：Agent Teams（多代理并行）

当任务足够大时，单个 Claude 不够用，需要 “团队协作”。

Agent Teams 允许多个 Claude 实例并行工作，通过共享任务列表协调依赖关系。这适合超大型项目，比如 Nicholas Carlini 的实验中，16 个并行 Agent 在 2 周内编写了 100,000+ 行代码，构建出一个能编译 Linux 内核的 C 编译器。

---

八、方法五：后台任务（Ctrl+B）

这是一个简单但实用的非阻塞执行方法，适合短时间的长任务。

8.1 基本操作

当 Claude 开始运行一个任务时，你可以按 Ctrl+B 把它推送到后台。比如：

1. 你说：“运行完整测试套件”

2. Claude 开始运行

3. 你按 Ctrl+B，Claude 会返回：“任务已推送到后台（ID: task_abc123）”

4. 然后你可以继续让 Claude 帮你分析日志，同时测试在后台运行

8.2 查看后台任务

• 使用 /tasks 命令可以列出所有后台任务
• 按 Ctrl+T 可以快速查看任务状态的摘要
• 可以把后台任务恢复到前台，查看实时输出

8.3 适用场景

• 长时间运行的测试
• 大型项目构建
• 批量文件处理
• 任何你不想等待的事情

---

九、安全机制：防止无限循环

任何自动循环系统都必须有安全保护，否则可能出现失控的情况。

9.1 硬性限制

最基本的保护是设置最大迭代次数，无论任务是否完成，达到这个次数后都会停止，防止无限循环消耗 API 额度。你还可以设置时间限制，比如最长运行 4 小时后自动停止。

9.2 智能检测

可以添加智能检测来发现死循环，比如检查最近几次提交有没有实质变化：

if [ $(git diff HEAD~5 | wc -l) -eq 0 ]; then
 echo "最近 5 次提交没有实质变化，可能陷入循环"
 exit 1
fi

9.3 成本预警

配置成本预警阈值，当花费达到一定金额时暂停并通知你：

{
 "costAlertThresholds": [10, 50, 100],
 "alertAction": "pause_and_notify"
}

---

十、本章总结

长任务技术让 Claude Code 从对话式助手，变成了可以 24 小时工作的数字员工：

1. 核心原理：用外部循环解决 AI 完成判断不可靠的问题，让 AI 持续迭代直到任务真正完成

2. 主流方案：从简单的 bash 循环，到官方的 Ralph 插件，再到社区增强版，满足不同需求

3. 关键技巧：定义明确的完成标准、写好分阶段的 Prompt、设置安全防护机制

4. 无限可能：你可以让 AI 过夜干活，周末自动重构，甚至用几个月时间构建复杂项目

掌握了长任务，你就能把 Claude Code 的能力发挥到极致，真正实现用自然语言完成从开发到重构、从测试到部署的全流程自动化。