Ralph Mode - Autonomous Development Loops

# Ralph Mode - Autonomous Development Loops

Ralph 模式实现了 Ralph Wiggum 技术适配于 OpenClaw 的版本：通过具有背压门、完成标准和结构化规划的持续迭代来实现自主任务完成。

## 何时使用

在以下情况使用 Ralph 模式： - 构建需要多次迭代和优化的功能 - 处理具有验收标准需验证的复杂项目 - 需要自动化测试、Lint 或类型检查门控 - 想要系统地跟踪跨许多迭代的进度 - 相比手动逐轮指导，更倾向于自主循环

## 核心原则

### 三阶段工作流

**阶段 1：需求定义** - 在 `specs/` 中记录规格（每个关注点一个文件） - 定义验收标准（可观察、可验证的结果） - 创建包含优先任务的实现计划

**阶段 2：规划** - 差距分析：对比规格与现有代码 - 生成包含优先任务的 `IMPLEMENTATION_PLAN.md` - 此阶段不进行实现

**阶段 3：构建（迭代）** - 每次迭代从计划中选择一项任务 - 实现、验证、更新计划、提交 - 持续进行直到所有任务完成或标准达成

### 背压门控

通过验证自动拒绝未完成的工作：

**程序化门控（始终使用这些）：** - 测试：`[test command]` - 提交前必须通过 - 类型检查：`[typecheck command]` - 尽早捕获类型错误 - Lint：`[lint command]` - 强制代码质量 - 构建：`[build command]` - 验证集成

**主观门控（用于 UX、设计、质量）：** - 用于语气、美学、可用性的 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

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

```markdown # Implementation Plan

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

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

## Backlog - [ ] Future task ```

### 主题范围测试

你能在不使用“and”的情况下用一句话描述该主题吗？ - ✅ “使用 JWT 和会话管理的用户认证” - ❌ “认证、资料和计费” → 3 个主题

### AGENTS.md - 操作指南

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

```markdown # 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`) - 编写代码、实现功能、修复 Bug - 重点：正确性、性能、测试覆盖率

**角色：测试员** (`@tester`) - 测试编写、验证、边缘情况 - 重点：覆盖率、可靠性、可复现性

**角色：审查者** (`@reviewer`) - 代码审查、PR 反馈、质量评估 - 重点：风格、可读性、遵循规格

**用法：** ``` "Spawn a sub-agent with @architect hat to design the data model" ```

## 循环机制

### 外层循环（你进行协调）

你作为主智能体的职责：工程设置、观察、航向修正。

1. **不要将工作分配给主上下文** - 生成子智能体 2. **让 Ralph 做 Ralph** - LLM 将自我识别、自我修正 3. **使用保护** - 沙箱是你的安全边界 4. **计划是可抛弃的** - 当错误或陈旧时重新生成 5. **置身于循环之外** - 坐着观察，不要微管理

### 内层循环（子智能体执行）

每个子智能体迭代： 1. **研究** - 阅读计划、规格、相关代码 2. **选择** - 选取最重要的未完成任务 3. **实现** - 编写代码，仅限一项任务 4. **验证** - 运行测试、Lint、类型检查（背压） 5. **更新** - 标记任务完成、记录发现、提交 6. **退出** - 下次迭代重新开始

### 停止条件

循环在以下情况结束： - ✅ 所有 IMPLEMENTATION_PLAN.md 任务已完成 - ✅ 所有验收标准已达成 - ✅ 测试通过，无阻塞问题 - ⚠️ 达到最大迭代次数（配置限制） - 🛑 手动停止 (Ctrl+C)

## 完成标准

预先定义成功 - 避免“看起来完成”的歧义。

### 程序化（可测量） - 所有测试通过：`[test_command]` 返回 0 - 类型检查通过：无 TypeScript 错误 - 构建成功：创建了生产环境包 - 覆盖率阈值：例如，80%+

### 主观（LLM 即评判）

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

```markdown ## 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. 应用背压门控（测试、Lint、类型检查） 4. 跟踪进度并宣布完成

## 运营心得

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

```markdown ## 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 即评判装置

针对主观标准（语气、美学、UX）：

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

```typescript 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`：

```markdown # 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. 显式路径验证

永远不要假设目录结构。在每次迭代开始时：

```typescript // 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. 写入带有“## Status: COMPLETE”的最终 `PROGRESS.md` 2. 列出所有已创建/修改的文件 3. 干净地退出（无挂起进程）

完成后的 PROGRESS.md 示例：

```markdown # 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. 使用“## Status: BLOCKED”记录到 PROGRESS.md 2. 详细描述阻碍因素 3. 列出尝试过的解决方案 4. 干净地退出（不要挂起）

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

### 6. 迭代时间限制

设置显式迭代超时：

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

**原因：** 防止在卡住的任务上无限循环，允许父智能体介入。

## 记忆更新

在每个 Ralph 模式会话之后，记录：

```markdown ## [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 ```

## 附录：失败案例库

观察到的常见反模式：

| 反模式 | 后果 | 预防 | |--------------|-------------|------------| | 无进度记录 | 父智能体无法确定状态 | 强制 PROGRESS.md | | 静默失败 | 工作丢失、时间浪费 | 显式错误记录 | | 重叠会话 | 文件冲突、状态损坏 | 生成前检查/清理 | | 路径假设 | 错误目录、错误文件 | 显式验证 | | 无完成信号 | 父智能体无限期等待 | 明确的 COMPLETE 状态 | | 无限迭代 | 资源浪费、无进度 | 时间限制 + 阻断因素 | | 复杂的初始提示词 | 子智能体从未启动（空的会话日志） | 简化指令 |

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

### 问题：子智能体生成但不执行 **证据：** 空的会话日志（2 字节）、无工具调用、0 Token 使用量

### 根本原因 1. **指令过于复杂** - 使隔离的会话初始化过载 2. **无明确的执行触发器** - 智能体不知道何时开始 3. **分支逻辑** - “如果 X 做 Y，如果 Z 做 W”混淆了任务选择 4. **提到了多个文件** - 无法决定从哪个开始

### 修复：简化的 Ralph 任务模板

```markdown ## 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，包含： ```markdown ## 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 以反映实际状态

## 总结 Ralf 在以下情况下工作：单文件聚焦 + 显式更改 + 验证 + 退出 Ralf 在以下情况下停滞：复杂决策 + 多个文件 + 条件逻辑