ralph-wiggum
fstandhartinger/ralph-wiggum加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
凌晨两点，开发者小张把任务清单交给 Claude Code，然后去睡觉了。Claude 自动阅读需求规范、写代码、跑测试、提交 Git——循环往复，直到所有功能全部完成。这是 Ralph Wiggum 描绘的工作场景：一个完全自主运转的 AI 编程循环。
Ralph Wiggum 由澳大利亚开发者 Geoffrey Huntley 首创方法论，结合 SpecKit 规格驱动开发理念，由 fstandhartinger 实现为完整的开源工具集。与传统的「人发指令、AI 执行」模式不同，它追求的是让 AI Agent 在最少干预下完成整个开发周期——就像把程序员从「自己动手干」升级到了「指挥一个不会累的 AI 下属」。
图1：Ralph Wiggum 项目徽标（MIT 许可证）
Ralph Wiggum 的核心哲学并非凭空创造，而是建立在 Geoffrey Huntley 多年的 AI 编程实验之上。Geoffrey Huntley 是澳大利亚知名的开源贡献者，他长期研究如何让 AI Agent 真正「靠谱地」完成真实项目，而非在玩具 demo 里自嗨。
他的核心发现是：大多数 AI 编程工具缺乏「闭环验证」机制。AI 写完代码就算了吗？测试跑过了吗？部署成功了吗？传统模式下这些都需要人类盯着，而人盯着就意味着无法真正「放手」。
Huntley 的解决方案是一个迭代式 bash 循环（Iterative Bash Loop）：AI 每轮只做一件事——实现一个任务 → 验证完成 → 输出完成信号 → 脚本检测到信号 → 进入下一轮。这个模式后来被 fstandhartinger 采纳并扩展为完整的多 Agent 支持框架。
整个系统的核心是 Ralph Loop（Ralph 循环），一个运行在终端里的自动化控制流。它的运转逻辑可以概括为六个阶段，循环往复直至所有规格全部实现：
第一步：定向（Orient）。AI Agent 首先读取规格文件（specs/）中的任务列表，以及宪法文件（constitution.md）中的项目原则。这一步确保 AI 每次都从「正确的上下文」出发，而不是靠记忆中的残留信息。
第二步：选任务（Pick Task）。AI 从两个来源中选择优先级最高的任务：如果项目已有 IMPLEMENTATION_PLAN.md，则从计划中选最高优先级的任务；否则直接从 specs/ 目录按编号顺序选取。每轮只选一个，不贪多。
第三步：实现与测试（Implement & Test）。这是核心工作量。AI 读取对应规格的 spec.md 文件，理解验收标准，然后实施代码、编写测试、验证功能。
第四步：验证标准（Verify Criteria）。这是 Ralph Loop 的「质量门禁」。spec 文件末尾的 Completion Signal 部分列出了具体的检查清单——单元测试通过、集成测试通过、浏览器测试（如果涉及 UI）、控制台无报错——AI 必须逐一确认，只有全部通过才能继续。
第五步：提交并推送（Commit & Push）。验证通过后，AI 自动执行 git commit 和 git push。这一步依赖宪法文件中配置的 YOLO 模式（"You Only Live Once" 模式），即跳过人工确认、直接提交。在 constitution.md 中可选择关闭 YOLO 改为人工审批。
第六步：输出完成信号（Output <promise>DONE</promise>）。这是整个循环的「魔法词」。AI 只有在验收标准 100% 满足时才输出这个短语。bash 脚本持续监控输出，一旦检测到 <promise>DONE</promise>，立即进入下一轮迭代；如果没检测到，则重新触发 AI 继续当前任务。
「魔法词」机制是整个系统的精髓所在。它用最简单的方式解决了 AI 编程中最头疼的问题——**如何判断 AI 真的做完了？**传统 LLM 的输出「看起来完成了」可能只是幻觉，但有了这个结构化信号，脚本层面就能精确判断任务状态。
Ralph Wiggum 的另一个亮点是对多种 AI Agent 工具的统一支持。项目提供了 8 个脚本变体，覆盖当前主流的 AI 编程 CLI：
| AI Agent | Shell 脚本 | PowerShell 脚本 |
|---|---|---|
| Claude Code | ralph-loop.sh | ralph-loop.ps1 |
| OpenAI Codex | ralph-loop-codex.sh | ralph-loop-codex.ps1 |
| Google Gemini | ralph-loop-gemini.sh | ralph-loop-gemini.ps1 |
| GitHub Copilot | ralph-loop-copilot.sh | ralph-loop-copilot.ps1 |
这意味着无论团队使用什么 AI 工具，只要安装了对应的 CLI，就可以用相同的规格驱动流程来自动化开发。Python 开发者用 Claude Code，.NET 团队用 Copilot，都能接入同一个开发规范体系。
每种 Agent 的脚本都针对其 CLI 接口做了适配：Claude Code 通过 /ralph-loop 命令调用；Codex 使用 --full-auto --quiet 参数进入无交互模式；Gemini 和 Copilot 则各自由对应的 prompt 模板驱动。
Ralph Wiggum 的另一核心组件是规格驱动开发（Spec-Driven Development）。项目要求开发者将需求写成结构化的规格文档，放在 specs/ 目录下：
specs/
├── 001-user-auth/spec.md
├── 002-payment-integration/spec.md
└── 003-dashboard-ui/spec.md
每个 spec.md 包含三个关键部分：
这种格式的好处是：AI 不需要猜测「做到什么程度算好」，规格已经写清楚了。AI 照着规格干活，既不会过度设计，也不会漏掉边界情况。
此外，项目还支持规划模式（Plan Mode）：运行 ./scripts/ralph-loop.sh plan 可以让 AI 从规格文件自动生成 IMPLEMENTATION_PLAN.md 任务分解计划，帮助人类理解项目的整体路线图。不过作者也强调，这是可选功能，大多数项目可以直接从规格文件工作，不需要额外的计划层。
Ralph Wiggum 引入了宪法（Constitution）概念。在 .specify/memory/constitution.md 文件中，开发者可以定义：
宪法文件是整个项目的行为准则，AI 每次启动 Ralph Loop 都会首先读取。它解决了 AI Agent 容易「跑偏」的问题——通过明确的规则边界来约束 AI 的行为范围。
Ralph Wiggum 的安装极为轻量。人类开发者只需告诉自己的 AI Agent：
"Set up Ralph Wiggum in this project using https://github.com/fstandhartinger/ralph-wiggum"
AI Agent 会自动阅读 INSTALLATION.md，完成目录创建、脚本下载、配置初始化，还会引导一个交互式的「项目访谈」来生成宪法文件。纯手动安装也不过是几条 curl 命令加 chmod，无需 Docker，无需任何依赖服务。
唯一的前提是：必须已安装对应的 AI Agent CLI（Claude Code / Codex / Gemini / Copilot 之一）。这些工具本身需要各自的 API Key 或认证，但那是 AI 平台侧的配置，与 Ralph Wiggum 无关。
作者在 README 开头就用大号警告文字写明：
⚠️ Use at your own risk. This tool grants AI agents significant autonomy over your codebase and system.
这句话绝非客套。Ralph Wiggum 默认开启 YOLO 模式，AI 会自主 commit、push、甚至部署代码。如果规格写得不够精确，AI 可能「自以为是」地实现了一套与预期不符的功能。更糟糕的是，在未经人工审查的情况下，不正确的代码可能被直接推送到生产分支。
因此，项目文档特别建议：在隔离环境中使用，尽可能先 review 所有变更。对于团队使用，建议在 constitution.md 中关闭 YOLO 模式，改为每次 commit 都需要人工确认。
此外，Ralph Wiggum 本身是一个「框架」，它依赖规格文档的质量。如果规格写得模糊（比如「做一个好看的界面」），AI 就会自己「脑补」，结果可能与预期大相径庭。所以规格写作能力直接决定了项目质量——换句话说，你还是得懂需求，只是把「动手写代码」外包给了 AI。
Ralph Wiggum 出现的时间点很有意思。2025-2026 年间，Claude Code、Codex、Copilot 等 AI 编程工具已经非常成熟，但它们的使用模式大多还是「人在循环中」——人发指令、AI 执行、结果给人看、人决定下一步。这种模式本质上还是「AI 辅助编程」，人始终是瓶颈。
Ralph Wiggum 代表了一个新的方向：Spec-Driven Autonomous Coding（规格驱动的自主编程）。它的核心假设是：如果规格足够精确，AI 可以不需要人盯着就能完成整个开发周期。这与软件工程界长期追求的「形式化规格」理想一脉相承，只不过 LLM 的出现让这个目标第一次有了实际落地的可能。
从 GitHub 数据看，该项目于 2026 年 1 月创建，到 7 月已积累 268 stars、28 forks。作为一个细分领域（AI Agent 自动化框架）的新兴项目，这个增速相当可观。它也带动了一批类似规格驱动 AI 编程工具的出现。
| 维度 | 内容 |
|---|---|
| 核心语言 | Shell（Bash + PowerShell） |
| 支持的 AI Agent | Claude Code、OpenAI Codex、Google Gemini、GitHub Copilot |
| 工作模式 | Build（构建）+ Plan（规划，可选） |
| 核心信号机制 | <promise>DONE</promise> 完成短语 |
| 规格格式 | Markdown (specs/NNN-feature/spec.md) |
| 配置文件 | constitution.md（宪法）、AGENTS.md、CLAUDE.md |
| 依赖要求 | 对应 AI Agent CLI（无服务器依赖） |
| 许可证 | MIT |
总体来说，Ralph Wiggum 是一个方法论 + 工具集的组合。它不依赖任何特定平台或框架，本质上是一套让 AI 编程工具「闭环运转」的工程规范。通过规格文件 + 自动化循环 + 验证信号，它把 AI 从「每次都要人盯着」的状态，升级为可以连续自主工作多个任务。它的上手门槛很低，但背后的工程思想却相当深刻——用规格换约束，用循环换质量。