拉尔夫模式 - 自主开发循环

拉尔夫模式实现了为OpenClaw适配的拉尔夫·维格姆技术：通过结合背压门、完成标准和结构化规划的持续迭代，实现自主任务完成。

使用场景

在以下情况使用拉尔夫模式：

• 构建需要多次迭代和优化的功能
• 处理具有待验证验收标准的复杂项目
• 需要自动化测试、代码检查或类型检查门控
• 希望系统性地跟踪多次迭代的进展
• 更倾向于自主循环而非手动逐步指导

核心原则

三阶段工作流

阶段一：需求定义

• 在specs/目录中记录规范（每个关注主题一个文件）
• 定义验收标准（可观察、可验证的结果）
• 创建包含优先级任务列表的实施计划

阶段二：规划

• 差距分析：将规格说明与现有代码进行比较
• 生成IMPLEMENTATION_PLAN.md 文件包含优先级排序的任务
• 此阶段不进行实现

阶段3：构建（迭代式）

• 每次迭代从计划中选取一个任务
• 实现、验证、更新计划、提交
• 持续进行，直到所有任务完成或达到标准

反向压力门控

通过验证自动拒绝不完整的工作：

程序化门控（始终使用这些）：

• 测试：[测试命令]- 提交前必须通过
• 类型检查：[类型检查命令]- 及早捕获类型错误
• 代码检查：[代码检查命令]- 强制执行代码质量
• 构建：[构建命令]- 验证集成

主观关卡（用于用户体验、设计、质量）：

• LLM作为评审员，审查语气、美学、可用性
• 二元通过/失败 - 通过迭代达成一致
• 仅在编程化关卡可靠工作后添加

上下文效率

• 每次迭代一个任务 = 每次都有新的上下文
• 生成子代理进行探索，而非在主上下文中进行
• 简洁提示 = 智能区域（约40-60%利用率）
• 计划是一次性的 - 重新生成比挽救更廉价

文件结构

为每个Ralph模式项目创建此结构：

project-root/
├── IMPLEMENTATION_PLAN.md     # Shared state, updated each iteration
├── AGENTS.md                  # Build/test/lint commands (~60 lines)
├── specs/                     # Requirements (one file per topic)
│   ├── topic-a.md
│   └── topic-b.md
├── src/                        # Application code
└── src/lib/                    # Shared utilities

IMPLEMENTATION_PLAN.md

优先级任务列表 - 单一事实来源。格式：

# Implementation Plan

## In Progress
- [ ] Task name (iteration N)
  - Notes: discoveries, bugs, blockers

## Completed
- [x] Task name (iteration N)

## Backlog
- [ ] Future task

主题范围测试

你能不用"和"这个词，用一句话描述这个主题吗？

• ✅ "使用JWT和会话管理的用户认证"
• ❌ "认证、配置文件和计费" → 3个主题

AGENTS.md - 操作指南

运行项目的简明指南。请保持在60行以内：

# Project Operations

## Build Commands
npm run dev      # Development server
npm run build     # Production build

## Validation
npm run test      # All tests
npm run lint      # ESLint
npm run typecheck  # TypeScript
npm run e2e       # E2E tests

## Operational Notes
- Tests must pass before committing
- Typecheck failures block commits
- Use existing utilities from src/lib over ad-hoc copies

角色（人物设定）

针对不同任务的专门角色：

角色：架构师(@architect)

• 高层设计、数据建模、API契约
• 关注点：模式、可扩展性、可维护性

角色：实现者(@implementer)

• 编写代码、实现功能、修复缺陷
• 关注点：正确性、性能、测试覆盖率

角色：测试者(@tester)

• 测试编写、验证、边界情况
• 关注点：覆盖率、可靠性、可复现性

角色：评审者(@reviewer)

• 代码审查，PR反馈，质量评估
• 重点：风格，可读性，规范遵循

用法：

"Spawn a sub-agent with @architect hat to design the data model"

循环机制

外层循环（由你协调）

你作为主代理的工作：工程设置，观察，调整方向。

1. 不要在主上下文中分配工作- 生成子代理
2. 让拉尔夫做拉尔夫的事- LLM将自我识别，自我纠正
3. 使用保护措施- 沙盒是你的安全边界
4. 计划是可丢弃的- 当计划错误或过时时，重新生成
5. 置身循环之外- 坐着观察，不要微观管理

内层循环（子代理执行）

每个子代理迭代：

1. 研究- 阅读计划、规格说明和相关代码
2. 选择- 挑选最重要的未完成任务
3. 实施- 编写代码，一次仅处理一个任务
4. 验证- 运行测试、代码检查、类型检查（背压）
5. 更新- 标记任务完成，记录发现，提交
6. 退出- 下一次迭代重新开始

停止条件

循环在以下情况结束：

• ✅ IMPLEMENTATION_PLAN.md 中的所有任务已完成
• ✅ 所有验收标准均已满足
• ✅ 测试通过，无阻塞性问题
• ⚠️ 达到最大迭代次数（配置限制）
• 🛑 手动停止（Ctrl+C）

完成标准

预先定义成功标准——避免“似乎完成”的模糊性。

可程序化（可衡量）

• 所有测试通过：[测试命令]返回 0
• 类型检查通过：无 TypeScript 错误
• 构建成功：生产包已创建
• 覆盖率阈值：例如，80%+

主观评估（LLM 作为裁判）

针对难以自动化衡量的质量标准：

## Completion Check - UX Quality
Criteria: Navigation is intuitive, primary actions are discoverable
Test: User can complete core flow without confusion

## Completion Check - Design Quality
Criteria: Visual hierarchy is clear, brand consistency maintained
Test: Layout follows established patterns

运行 LLM 作为裁判的子代理，进行通过/失败的二元判定。

技术特定模式

Next.js 全栈

specs/
├── authentication.md
├── database.md
└── api-routes.md

src/
├── app/                    # App Router
├── components/              # React components
├── lib/                    # Utilities (db, auth, helpers)
└── types/                   # TypeScript types

AGENTS.md:
  Build: npm run dev
  Test: npm run test
  Typecheck: npx tsc --noEmit
  Lint: npm run lint

Python（脚本/笔记本/FastAPI）

specs/
├── data-pipeline.md
├── model-training.md
└── api-endpoints.md

src/
├── pipeline.py
├── models/
├── api/
└── tests/

AGENTS.md:
  Build: python -m src.main
  Test: pytest
  Typecheck: mypy src/
  Lint: ruff check src/

GPU 工作负载

specs/
├── model-architecture.md
├── training-data.md
└── inference-pipeline.md

src/
├── models/
├── training/
├── inference/
└── utils/

AGENTS.md:
  Train: python train.py
  Test: pytest tests/
  Lint: ruff check src/
  GPU Check: nvidia-smi

快速开始命令

启动 Ralph 模式会话：

"Start Ralph Mode for my project at ~/projects/my-app. I want to implement user authentication with JWT.

我将：

1. 创建 IMPLEMENTATION_PLAN.md，包含优先任务
2. 生成子代理以进行迭代实现
3. 应用背压门控（测试、代码检查、类型检查）
4. 跟踪进度并宣布完成

操作经验总结

当出现 Ralph 模式时，更新 AGENTS.md：

## Discovered Patterns

- When adding API routes, also add to OpenAPI spec
- Use existing db utilities from src/lib/db over direct calls
- Test files must be co-located with implementation

逃生舱口

当执行轨迹出现问题时：

• Ctrl+C- 立即停止循环
• 重新生成计划- "丢弃 IMPLEMENTATION_PLAN.md 并重新规划"
• 重置- "Git 重置到最后已知的良好状态"
• 缩小范围- 为特定工作创建范围更小的计划

高级功能：LLM 作为评审装置的固定模式

对于主观标准（语气、美学、用户体验）：

创建src/lib/llm-review.ts：

interface ReviewResult {
  pass: boolean;
  feedback?: string;
}

async function createReview(config: {
  criteria: string;
  artifact: string; // text or screenshot path
}): Promise<ReviewResult>;

子代理会发现并使用此模式进行二进制通过/失败检查。

关键操作要求

根据经验用法，强制执行以下实践以避免静默失败：

1. 强制进度日志记录

Ralph 必须在每次迭代后写入 PROGRESS.md。这一点不容商量。

创建项目根目录下的 PROGRESS.md（开始时）：原因：

# Ralph: [Task Name]

## Iteration [N] - [Timestamp]

### Status
- [ ] In Progress | [ ] Blocked | [ ] Complete

### What Was Done
- [Item 1]
- [Item 2]

### Blockers
- None | [Description]

### Next Step
[Specific next task from IMPLEMENTATION_PLAN.md]

### Files Changed
- `path/to/file.ts` - [brief description]

外部观察者（父代理、定时任务、人类）可以追踪单个文件，而无需扫描目录或从会话日志推断状态。2. 会话隔离与清理

在启动新的 Ralph 会话之前：

通过

• sessions_list检查是否存在现有的 Ralph 子代理
• 终止或确认先前会话已完成
• 请勿在同一代码库上启动重叠的 Ralph 会话

反模式：在 v1 仍在运行时启动 Ralph v2 = 文件冲突、竞态条件、工作丢失。

3. 显式路径验证

切勿假设目录结构。在每次迭代开始时：

// Verify current working directory
const cwd = process.cwd();
console.log(`Working in: ${cwd}`);

// Verify expected paths exist
if (!fs.existsSync('./src/app')) {
  console.error('Expected ./src/app, found:', fs.readdirSync('.'));
  // Adapt or fail explicitly
}

原因：Ralph 可能从具有不同工作目录的不同上下文中启动。

4. 完成信号协议

完成后，Ralph 必须：

1. 写入最终PROGRESS.md标记为 "## Status: COMPLETE"
2. 列出所有已创建/已修改的文件
3. 干净地退出（没有挂起的进程）

PROGRESS.md 完成示例：

# Ralph: Influencer Detail Page

## Status: COMPLETE ✅

**Finished:** [ISO timestamp]

### Final Verification
- [x] TypeScript: Pass
- [x] Tests: Pass  
- [x] Build: Pass

### Files Created
- `src/app/feature/page.tsx`
- `src/app/api/feature/route.ts`

### Testing Instructions
1. Run: `npm run dev`
2. Visit: `http://localhost:3000/feature`
3. Verify: [specific checks]

5. 错误处理要求

如果 Ralph 遇到不可恢复的错误：

1. 在 PROGRESS.md 中记录 "## Status: BLOCKED"
2. 详细描述阻塞原因
3. 列出已尝试的解决方案
4. 干净地退出（不要挂起）

不要静默失败。一个停止迭代且没有进度记录的 Ralph，与一个仍在工作的 Ralph 是无法区分的。

6. 迭代时间限制

设置明确的迭代超时：

## Operational Parameters
- Max iteration time: 10 minutes
- Total session timeout: 60 minutes
- If iteration exceeds limit: Log blocker, exit

原因：防止在卡住的任务上无限循环，允许父代理进行干预。

内存更新

每次 Ralph 模式会话后，记录：

## [Date] Ralph Mode Session

**Project:** [project-name]
**Duration:** [iterations]
**Outcome:** success / partial / blocked
**Learnings:**
- What worked well
- What needs adjustment
- Patterns to add to AGENTS.md

附录：失败案例集

观察到的常见反模式：

新：会话初始化最佳实践 (2025-02-07)

问题：子代理已生成但未执行

证据：会话日志为空（2字节），无工具调用，使用令牌数为0

根本原因

1. 指令过于复杂- 使隔离的会话初始化过程不堪重负
2. 没有明确的执行触发点- 代理不知道何时开始
3. 分支逻辑- "如果X则做Y，如果Z则做W" 混淆了任务选择
4. 提及多个文件- 无法决定从哪个文件开始

修复：简化的Ralph任务模板

## Task: [ONE specific thing]

**File:** exact/path/to/file.ts
**What:** Exact description of change
**Validate:** Exact command to run
**Then:** Update PROGRESS.md and exit

## Rules
1. Do NOT look at other files
2. Do NOT "check first"
3. Make the change, validate, exit

修改前（错误 - 导致停滞）：

Fix all TypeScript errors across these files:
- lib/db.ts has 2 errors
- lib/proposal-service.ts has 5 errors
- route.ts has errors
Check which ones to fix first, then...

修改后（正确 - 可执行）：

Fix lib/db.ts line 27:
Change: PoolClient to pg.PoolClient
Validate: npm run typecheck
Exit immediately after

关键：单一文件规则

每次Ralph迭代只处理一个文件。不是"所有错误"，也不是"先检查再决定"。一个文件，一次改动，验证，退出。

关键：更新 PROGRESS.md

强制性要求：每次迭代后，使用以下内容更新 PROGRESS.md：

## Iteration [N] - [Timestamp]

### Status: Complete ✅ | Blocked ⛔ | Failed ❌

### What Was Done
- [Specific changes made]

### Validation
- [Test/lint/typecheck results]

### Next Step
- [What should happen next]

为何重要：定时任务会读取 PROGRESS.md 以获取状态更新。如果不更新，状态会显得过时/重复。

调试 Ralph 停滞问题

如果 Ralph 停滞：

1. 检查会话日志（应显示 60 秒内的工具调用）
2. 如果在启动后为空 → 指令过于复杂
3. 简化：一个文件，一个行号，一个更改
4. 更短的超时时间强制任务更小（300 秒而非 600 秒）

修复过时的状态报告

如果定时任务重复报告相同状态：

1. 检查子代理是否更新了 PROGRESS.md
2. 如果未更新 → 子代理跳过了文档记录步骤
3. 更新技能：在提示中添加"强制性更新 PROGRESS.md"
4. 手动修复：更新 PROGRESS.md 以反映实际状态

总结

拉尔夫在工作时：单一文件焦点 + 明确的更改 + 验证 + 退出 拉尔夫在停滞时：复杂的决策 + 多个文件 + 条件逻辑