（图：Ralph Wiggum 通过 Bash 循环驱动 Claude Code，实现“需求 → 实现 → 测试 → 提交”全自动闭环）

---

0. 为什么普通 AI 编程不够用？

你有没有试过这样和 AI 编程助手对话：

“帮我写一个用户登录 API。”
→ 它返回一段代码。
“现在加个邮箱验证。”
→ 它改了代码，但忘了加测试。
“再加个数据库迁移……”

反复交互、上下文丢失、缺乏持续性——这是当前大多数 AI 编程工具的痛点。

而 Ralph Wiggum 插件，正是为解决这个问题而生。它让 Claude Code 从“一次性问答机”升级为能自主推进整个项目的 AI 开发者。

---

1. Claude Code 是什么？

Claude Code 是 Anthropic 推出的 命令行 AI 编程助手，直接集成在终端中，支持自然语言指令生成、修改和调试代码。

• 支持 Python、TypeScript、SQL 等主流语言
• 能读取 Git 历史，理解项目上下文
• 通过 / 命令触发功能（如 /test、/fix）

但它默认是“单次会话”模式，无法自动完成多步骤任务。

这就像请了一个程序员，但他每写完一行就问你：“下一步干啥？”

---

2. Ralph Wiggum：给 Claude Code 装上“自动驾驶”

Ralph Wiggum（名字来自《辛普森一家》里那个总说奇怪但有道理话的小孩）是一个 Bash 脚本驱动的自动化循环系统，它让 Claude Code 能：

✅ 读取产品需求（PRD）
✅ 按优先级逐个实现用户故事
✅ 自动运行测试
✅ 通过后提交 Git
✅ 记录经验到知识库
✅ 循环直到所有任务完成！

---

3. 核心文件结构

Ralph Wiggum 的工作目录通常如下：

scripts/
└── ralph/
    ├── ralph.sh          # 主循环脚本
    ├── prompt.md         # 每轮给 AI 的指令
    ├── prd.json          # 用户故事列表（需求文档）
    └── progress.txt      # 累积的知识库 & 模式记录

📄 prd.json：你的“AI 任务清单”

{
  "userStories": [
    {
      "id": "auth-01",
      "title": "实现邮箱密码登录",
      "branchName": "feat/auth-login",
      "priority": 1,
      "acceptanceCriteria": [
        "有 /login POST 接口",
        "使用 bcrypt 加密密码",
        "返回 JWT token"
      ],
      "passes": false
    }
  ]
}

低 priority 值先执行，passes: true 表示已完成。

📄 prompt.md：告诉 AI 每轮该做什么

你是一个全栈工程师，请：
1. 读取 prd.json，选择 priority 最低且未完成的故事
2. 在对应分支开发功能
3. 编写单元测试并确保通过
4. 如果成功，提交 Git 并标记 passes=true
5. 将学到的模式（如“用 IF NOT EXISTS 防重复建表”）追加到 progress.txt

📜 progress.txt：AI 的“经验笔记本”

# Reusable Patterns
- Always use `IF NOT EXISTS` in SQL migrations
- Validate email with zod in TypeScript

# Story auth-01 Learnings
- Used bcrypt.hashSync for password
- JWT secret loaded from .env

这些知识会在后续迭代中被复用！

---

4. 内部工作流程：一个智能闭环

1. 启动循环：./scripts/ralph/ralph.sh 10（最多 10 轮）
2. 注入 prompt：将 prompt.md 发送给 Claude Code
3. AI 执行：
   • 读 prd.json 选任务
   • 修改代码
   • 运行测试（如 npm test）
4. 验证结果：
   • ✅ 测试通过 → git commit + 更新 passes: true
   • ❌ 失败 → 下一轮重试
5. 记录经验：关键模式写入 progress.txt 顶部
6. 循环继续，直到所有任务完成或达到最大轮数

当安装好插件之后，就可以执行ralph-loop 命令

---

5. 与 Apidog 深度集成：API 开发神器组合

如果你用 Apidog 管理 API，Ralph Wiggum 能更强大：

• 在 prd.json 的 notes 字段嵌入 OpenAPI 规范链接
• Claude Code 读取规范，自动生成符合 schema 的控制器
• 利用 Apidog Mock 服务进行端到端测试
• 完成后自动同步代码变更回 Apidog，更新文档

{
  "title": "实现用户注册 API",
  "notes": "参考 Apidog 项目 ID: api-12345 的 /users POST 接口"
}

---

6. 快速上手：三步启动你的 AI 开发者

步骤 1：安装依赖

# 安装 Claude Code（按 Anthropic 官方指南）
# 安装 jq（用于 JSON 处理）
brew install jq        # macOS
sudo apt install jq    # Linux

步骤 2：创建脚本目录

mkdir -p scripts/ralph
cd scripts/ralph
# 复制 ralph.sh, prompt.md, prd.json, progress.txt（内容见官方教程）
chmod +x ralph.sh

步骤 3：运行！

# 执行最多 5 轮
./ralph.sh 5

终端将实时输出每轮进展，完成后检查 prd.json 是否全部 passes: true。

---

7. 高级技巧 & 注意事项

• 🔁 拆分大任务：每个用户故事尽量小，避免超出 Claude 上下文窗口
• 🧪 测试驱动：在 acceptanceCriteria 中明确写“测试覆盖率 > 80%”
• 🌐 UI 任务：结合 dev-browser 技能，让 AI 截图验证前端效果
• ⚠️ 防无限循环：设置合理迭代上限（如 20 轮）
• 💰 成本控制：复杂项目整晚跑完，API 费用通常 < $300

---

8. 总结：从“辅助”到“代理”

Ralph Wiggum 不只是插件，它代表了一种新范式：
让 AI 成为可持久工作的“开发代理”，而非临时问答工具。

配合 Apidog 这类专业平台，你甚至可以构建 “需求 → 设计 → 开发 → 测试 → 文档”全自动流水线。

未来，或许你只需写好 prd.json，然后去喝杯咖啡——回来时，项目已 ready for review。

---