Claude Code CLI + Ralph：让 AI 自动完成大型编程任务的终极方案

TL;DR

当你的编程任务大到一个 AI 对话窗口装不下时，Ralph 会帮你把任务拆成小块，让 Claude Code CLI 一个接一个地自动完成——每轮都用全新的上下文窗口，不会越写越糊涂。

一、什么是 Ralph？

Ralph 是一个开源项目（GitHub 16k+ Stars），基于 Geoffrey Huntley 提出的 "Ralph Pattern" 构建。它的核心理念很简单：

不要让 AI 在一个漫长的会话里做完所有事情，而是把大任务拆成小故事，每个故事用一个全新的 AI 实例来完成。

这解决了 AI 编程中最常见的痛点——上下文窗口耗尽。当对话越来越长，AI 的输出质量会明显下降。Ralph 通过「每轮一个新实例」的方式，确保每次 AI 都在最佳状态下工作。

核心特性

• 自主循环：无需人工干预，自动一个接一个完成用户故事
• 上下文常新：每轮迭代都启动全新的 AI 实例，告别上下文污染
• 跨轮记忆：通过 Git 历史 + progress.txt + prd.json 实现"记忆传递"
• 质量守护：每轮自动运行 typecheck、lint、测试，确保代码质量
• 支持多种 AI 工具：兼容 Claude Code CLI 和 Amp CLI

二、安装与配置

前置要求

• Claude Code CLI：npm install -g @anthropic-ai/claude-code
• jq（JSON 处理工具）：brew install jq（macOS）或 apt install jq（Linux）
• 一个 Git 仓库（Ralph 依赖 Git 来持久化进度）

安装方式一：复制到项目（推荐入门）

# 克隆 Ralph
git clone https://github.com/snarktank/ralph.git

# 复制到你的项目
mkdir -p scripts/ralph
cp ralph/ralph.sh scripts/ralph/
cp ralph/CLAUDE.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh

安装方式二：全局安装 Skills

# 安装 PRD 生成和 Ralph 转换技能
cp -r skills/prd ~/.claude/skills/
cp -r skills/ralph ~/.claude/skills/

安装后你可以在 Claude Code 中直接使用 /prd 和 /ralph 命令。

安装方式三：Claude Code 插件市场

# 在 Claude Code 中执行
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

三、工作原理

Ralph 的核心就是一个 Bash 循环脚本。下面这张流程图展示了它的完整工作流：

每轮迭代的 10 个步骤

1. 检查/创建特性分支：根据 prd.json 中的 branchName 字段
2. 启动全新 AI 实例：将 CLAUDE.md 作为 prompt 传入 Claude Code
3. 读取任务状态：AI 读取 prd.json 和 progress.txt
4. 选取最高优先级的未完成故事：找到 passes: false 的用户故事
5. 实现该故事：编写代码、修改文件
6. 运行质量检查：typecheck → lint → test
7. 提交代码：feat: [Story ID] - [Story Title]
8. 更新 prd.json：标记故事为 passes: true
9. 记录经验到 progress.txt：供后续迭代参考
10. 检查是否全部完成：是 → 输出 COMPLETE 并退出；否 → 下一轮

记忆传递的三大支柱

虽然每轮 AI 实例都是"失忆"的，但 Ralph 通过三个文件实现了跨轮记忆：

此外，Ralph 还会更新 AGENTS.md 文件，记录代码库的模式和注意事项。Claude Code 会自动读取这个文件，相当于给 AI 提供了"团队知识库"。

四、完整使用教程

Step 1：创建 PRD（产品需求文档）

在 Claude Code 中使用 /prd 技能：

> Load the prd skill and create a PRD for:
  为博客系统添加文章标签过滤功能

Ralph 会向你提 3-5 个澄清问题，然后生成结构化的 PRD 文件，保存为 tasks/prd-tag-filter.md。

Step 2：将 PRD 转换为 Ralph 格式

> Load the ralph skill and convert tasks/prd-tag-filter.md to prd.json

这会生成核心的 prd.json 文件，结构如下：

{
  "project": "MyBlog",
  "branchName": "ralph/tag-filter",
  "goal": "为博客添加标签过滤功能",
  "userStories": [
    {
      "id": "US-001",
      "title": "创建标签数据模型",
      "passes": false,
      "priority": 1
    },
    {
      "id": "US-002",
      "title": "实现标签 API 端点",
      "passes": false,
      "priority": 2
    },
    {
      "id": "US-003",
      "title": "添加前端标签过滤 UI",
      "passes": false,
      "priority": 3
    }
  ]
}

注意事项：每个用户故事必须足够小，能在一个 AI 上下文窗口内完成。好的拆分粒度示例：

• ✅ "添加数据库字段和迁移"
• ✅ "为现有页面添加一个 UI 组件"
• ❌ "构建整个仪表盘"（太大）
• ❌ "添加完整的认证系统"（太大）

Step 3：启动 Ralph

# 使用 Claude Code 运行，最多 15 轮迭代
./scripts/ralph/ralph.sh --tool claude 15

然后就可以泡杯咖啡，看 Ralph 自动干活了。它会：

1. 创建 ralph/tag-filter 分支
2. 逐个完成用户故事
3. 每完成一个就提交代码并更新状态
4. 全部完成后自动停止

Step 4：检查进度

在 Ralph 运行过程中，你随时可以查看进度：

# 查看每个故事的完成状态
cat prd.json | jq '.userStories[] | {id, title, passes}'

# 查看经验记录
cat progress.txt

# 查看 Git 提交历史
git log --oneline -10

五、实际运行效果

以一个典型的中型功能为例，Ralph 的表现大致如下：

六、最佳实践与注意事项

1. 故事要小：每个用户故事应该能在单个上下文窗口内完成，这是 Ralph 能正常工作的前提
2. 测试先行：确保项目有完善的 typecheck、lint 和测试，Ralph 依赖这些反馈循环来保证质量
3. 按依赖排序：priority 字段决定执行顺序，确保被依赖的故事优先完成
4. 定制 CLAUDE.md：根据你的项目添加特定的质量检查命令、代码规范和常见坑点
5. 定期检查：虽然 Ralph 是自动化的，但建议每隔几轮检查一下 progress.txt 和代码质量

七、项目关键文件一览

总结

Ralph 代表了 AI 辅助编程的一个重要演进方向：不是让 AI 更聪明，而是让 AI 更聪明地工作。通过将大任务拆解为小故事、每轮使用全新上下文、并通过文件系统传递记忆，Ralph 突破了单次对话的局限，让 Claude Code 能够处理真正大规模的编程任务。

如果你正在使用 Claude Code 进行日常开发，强烈建议尝试 Ralph。它可能会改变你对 AI 编程的认知——从"AI 助手"变成"AI 自动化工程团队"。

相关链接：

• Ralph GitHub 仓库
• Ralph 交互式流程图
• Geoffrey Huntley 的 Ralph Pattern 原文
• Claude Code 官方文档