# Ralph Wiggum

> 强制 Stop hook loop，避免 Codex 只做一步就停止；直到满足“完成承诺”才允许结束并输出总结。

- Skill: `stellarlinkco/ralph-wiggum` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add stellarlinkco/ralph-wiggum`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stellarlinkco/ralph-wiggum/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stellarlinkco (https://skillmd.com/u/stellarlinkco)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stellarlinkco/ralph-wiggum

---


# Ralph Wiggum（循环防早停）

## 目的

- 解决“模型做完一步就停”的常见失败模式：在同一个 turn 内，Stop hook 会在模型尝试结束时进行拦截，并把你写在状态文件里的原始任务提示重新注入上下文，让模型继续迭代直到真正完成。
- 设计参考：Claude Code 的 ralph-wiggum 插件（Stop hook 驱动的自循环）。

## 使用时机

- 需要强制完成多步骤任务（例如 1/2/3/4/5 的实现步骤 + 最终总结）。
- 需要在自动化 loop 中设置“最大迭代次数”与“完成承诺”，避免无限循环。

## 快速开始（项目内文件）

1) 在项目根目录创建脚本（必须存在，否则 hook 会失败）：

- 路径：`.claude/hooks/ralph-wiggum-stop-hook.py`
- 内容：直接拷贝 `references/ralph-wiggum-stop-hook.py` 到上述路径。

2) 启动 loop：创建状态文件 `.claude/ralph-loop.local.md`

模板：

```md
---
iteration: 0
max_iterations: 20
completion_promise: "BUS-STOP-WEB-DONE"
---
请开发一个公交站台记录的 web 应用，按 1/2/3/4/5 步骤完成，并在最终输出中包含清晰的“总结”。
```

3) 结束 loop：仅当任务真的完成时，在最终回复中输出：

```txt
<promise>BUS-STOP-WEB-DONE</promise>
```

Stop hook 看到该标签后会自动删除状态文件并允许停止。

## 约束

- 这是“Stop hook 驱动的循环”，不是新工具；它只影响何时允许停止。
- 如果 `max_iterations > 0` 且达到上限，hook 会停止循环并删除状态文件，避免卡死。