ralph-wiggum

Ralph Wiggum：通过上下文工程实现自主迭代

Ralph 是一种自主 AI 开发技术。最纯粹的形式是，Ralph 会反复向 AI Agent 发送同一条提示词，让它不断迭代任务，直到完成。关键在于，上下文就像内存——当你将数据 malloc() 到上下文窗口后，除非重新开始，否则就无法 free()。

核心理念

“Ralph 的妙处就在于——在一个非确定性的世界里，这项技术会确定性地犯错。”

Ralph 会犯错，这是意料之中的。每次错误都是添加一个“标志”（防护措施）的机会，以防止今后再次犯同样的错误。就像调试吉他一样，你需要不断调整 Ralph，直到它能弹出正确的音符。

malloc/free 的比喻

• 上下文就是内存：载入大模型上下文窗口的所有内容都会一直留在那里
• 无法 free() 上下文：清除上下文的唯一方法是开启新的对话
• 每个上下文只处理一个任务：混杂多个关注点会导致自回归失败
• 不要顶格使用：将上下文推到极限会降低性能
• 识别球沟：保龄球一旦落入球沟，就要重新开始

此技能的工作方式

状态文件（持久记忆）

Ralph 会在文件中跟踪状态，而不是在上下文中：

.ralph/
├── state.md           # Current iteration, task, completion criteria
├── guardrails.md      # Accumulated "signs" from observed failures  
├── context-log.md     # What's been loaded into context
├── failures.md        # Failure patterns for learning
└── progress.md        # What's been accomplished

迭代周期

1. 读取状态文件，了解当前任务和进度
2. 检查防护措施，查看需要遵循的相关“标志”
3. 处理任务——实现、测试、改进
4. 在文件中更新进度（不只是更新上下文）
5. 通过 git 提交检查点
6. 根据标准评估是否完成
7. 如果尚未完成：发出信号，开始下一轮迭代
8. 如果遇到阻碍：识别球沟，并建议使用全新的上下文

防护措施（“标志”）

Ralph 犯错时，添加一个标志：

## Sign: Don't Jump Off The Slide
- **Trigger**: When implementing authentication
- **Instruction**: Always validate tokens before trusting claims
- **Added after**: Iteration 5 - security vulnerability introduced

标志会累积在 guardrails.md 中，并注入后续迭代。

用法

启动 Ralph 循环

在项目根目录创建一个 RALPH_TASK.md 文件：

---
task: Build a REST API for task management
completion_criteria:
  - All CRUD endpoints working
  - Input validation implemented
  - Tests passing with >80% coverage
  - API documentation complete
max_iterations: 50
---

## Requirements

Build a task management API with the following endpoints:
- POST /tasks - Create a task
- GET /tasks - List all tasks
- GET /tasks/:id - Get a task
- PUT /tasks/:id - Update a task
- DELETE /tasks/:id - Delete a task

## Constraints

- Use TypeScript
- Use Express.js
- Use SQLite for storage
- Follow REST conventions

然后告诉 Cursor：“针对这个任务启动 Ralph 循环”

监控进度

查看 .ralph/progress.md，了解已完成的内容：

## Iteration 1
- Created project structure
- Implemented POST /tasks endpoint
- Status: Partial progress

## Iteration 2
- Added GET endpoints
- Fixed validation bug
- Status: Continuing

何时重新开始

Ralph 会检测“球沟”情况：

• 同一错误重复 3 次或更多
• 上下文接近上限
• 出现循环失败模式

检测到这些情况时，Ralph 会建议：“上下文已受污染。建议开启新的对话。”

最佳实践

1. 明确完成标准

❌ 不好：“做一个好用的 API” ✅ 好：“所有测试通过，覆盖率 >80%，文档完整”

2. 制定渐进式目标

❌ 不好：“构建完整的电子商务平台” ✅ 好：阶段 1：身份验证，阶段 2：商品，阶段 3：购物车

3. 让失败成为教训

不要过早干预。让 Ralph 先失败，然后添加标志。

4. 相信文件

进度记录在文件和 git 中，而不是你的脑海或上下文里。

5. 开启全新上下文成本很低

不要犹豫，随时开启全新上下文。状态会保存在文件中。

与 Cursor Hooks 集成

此技能使用 Cursor Hooks 来：

• beforeSubmitPrompt：注入防护措施并感知上下文
• beforeReadFile：跟踪上下文分配
• afterFileEdit：更新进度跟踪
• stop：评估是否完成，并触发下一轮迭代或重新开始

钩子的实现请参见 scripts/。

了解更多

• 原始技术：https://ghuntley.com/ralph/
• 上下文工程：https://ghuntley.com/gutter/
• malloc/free 比喻：https://ghuntley.com/allocations/