Back to Details

ralph-wiggum

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ralph Wiggum

Ralph Wiggum

Autonomous AI coding with spec-driven development
基于规范驱动开发的自主AI编码

What is Ralph Wiggum?

什么是Ralph Wiggum？

Ralph Wiggum combines Geoffrey Huntley's iterative bash loop with spec-driven development for fully autonomous AI-assisted software development.
The key insight: Fresh context each iteration. Each loop starts a new agent process with a clean context window, preventing context overflow and degradation.
Ralph Wiggum 将Geoffrey Huntley的迭代bash循环与规范驱动开发相结合，实现完全自主的AI辅助软件开发。
核心亮点：每次迭代使用全新上下文。每次循环都会启动一个新的AI Agent进程，拥有干净的context window，避免上下文溢出和性能下降。

When to Use This Skill

何时使用该工具

Use Ralph Wiggum when:
  • You have multiple specifications/features to implement
  • You want the AI to work autonomously through tasks
  • You need consistent, verifiable completion of acceptance criteria
  • You want to avoid context window problems in long sessions
在以下场景使用Ralph Wiggum：
  • 你有多个功能规范需要实现
  • 希望AI自主完成一系列任务
  • 需要验收标准得到一致、可验证的满足
  • 想要避免长会话中的context window问题

How It Works

工作原理

┌─────────────────────────────────────────────────────────────┐
│                     RALPH LOOP                              │
├─────────────────────────────────────────────────────────────┤
│  Loop 1: Pick spec A → Implement → Test → Commit → DONE    │
│  Loop 2: Pick spec B → Implement → Test → Commit → DONE    │
│  Loop 3: Pick spec C → Implement → Test → Commit → DONE    │
│  ...                                                        │
│                                                             │
│  Each iteration = Fresh context window                      │
│  Shared state = Files on disk (specs, plan, history)        │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                     RALPH LOOP                              │
├─────────────────────────────────────────────────────────────┤
│  Loop 1: Pick spec A → Implement → Test → Commit → DONE    │
│  Loop 2: Pick spec B → Implement → Test → Commit → DONE    │
│  Loop 3: Pick spec C → Implement → Test → Commit → DONE    │
│  ...                                                        │
│                                                             │
│  Each iteration = Fresh context window                      │
│  Shared state = Files on disk (specs, plan, history)        │
└─────────────────────────────────────────────────────────────┘

Installation

安装

Quick Install (via Skill Installers)

快速安装（通过Skill Installers）

bash
undefined
bash
undefined

Using Vercel's add-skill

Using Vercel's add-skill

npx add-skill fstandhartinger/ralph-wiggum
npx add-skill fstandhartinger/ralph-wiggum

Using OpenSkills

Using OpenSkills

openskills install fstandhartinger/ralph-wiggum
undefined
openskills install fstandhartinger/ralph-wiggum
undefined

Full Setup (Recommended)

完整设置（推荐）

For full Ralph Wiggum setup with constitution and interview:
bash
undefined
如需包含章程和项目调研的完整Ralph Wiggum设置：
bash
undefined

Tell your AI agent:

Tell your AI agent:

"Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum"

The agent will guide you through a **lightweight, pleasant setup**:

1. **Quick Setup** (~1 min) — Create directories, download scripts
2. **Project Interview** — Focus on your **vision and goals** (not tech details)
3. **Constitution** — Create a guiding document for all sessions
4. **Next Steps** — Clear guidance on creating specs and starting Ralph

For existing projects, the agent detects your tech stack automatically. The interview prioritizes understanding *what you're building and why*.
"Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum"

Agent会引导你完成**轻量、友好的设置流程**：

1. **快速设置**（约1分钟）—— 创建目录、下载脚本
2. **项目调研**—— 聚焦你的**愿景和目标**（而非技术细节）
3. **章程制定**—— 创建所有会话的指导性文档
4. **后续步骤**—— 明确指导你如何创建规范并启动Ralph

对于现有项目，Agent会自动检测你的技术栈。调研环节优先关注*你要构建什么以及为什么构建*。

Core Concepts

核心概念

1. Fresh Context Each Loop

1. 每次循环使用全新上下文

Each iteration of the Ralph loop starts a new AI agent process. This means:
  • No context window overflow
  • No degradation over time
  • Clean slate for each task
Ralph循环的每次迭代都会启动一个新的AI Agent进程。这意味着：
  • 不会出现context window溢出
  • 不会随时间出现性能下降
  • 每个任务都有全新的开始

2. Shared State on Disk

2. 磁盘存储共享状态

State persists between loops via files:
  • specs/
    — Feature specifications with acceptance criteria
  • ralph_history.txt
    — Log of breakthroughs, blockers, learnings
  • IMPLEMENTATION_PLAN.md
    — Optional detailed task breakdown
循环间的状态通过文件持久化：
  • specs/
    —— 包含验收标准的功能规范
  • ralph_history.txt
    —— 记录突破点、障碍、经验总结的日志
  • IMPLEMENTATION_PLAN.md
    —— 可选的详细任务分解文档

3. Completion Signal

3. 完成信号

The agent outputs 
<promise>DONE</promise>
ONLY when:
  • All acceptance criteria are verified
  • Tests pass
  • Changes are committed and pushed
The bash loop checks for this phrase. If not found, it retries.
只有满足以下所有条件时，Agent才会输出
<promise>DONE</promise>
：
  • 所有验收标准均已验证
  • 测试通过
  • 变更已提交并推送
bash循环会检查该短语，如果未检测到则重试。

4. Backpressure via Tests

4. 测试作为反向约束

Tests, lints, and builds act as guardrails. The agent must fix issues before outputting the completion signal.
测试、代码检查和构建流程充当防护栏。Agent必须解决所有问题后才能输出完成信号。

Usage

使用方法

Creating Specifications

创建规范

The key to success: Each spec needs clear, testable acceptance criteria. This is what tells Ralph when a task is truly "done."
markdown
undefined
成功关键： 每个规范都需要清晰、可测试的验收标准。这是Ralph判断任务是否真正“完成”的依据。
markdown
undefined

Feature: User Authentication

Feature: User Authentication

Requirements

Requirements

  • OAuth login with Google
  • Session management
  • Logout functionality
  • OAuth login with Google
  • Session management
  • Logout functionality

Acceptance Criteria

Acceptance Criteria

  • User can log in with Google
  • Session persists across page reloads
  • User can log out
  • Tests pass
Output when complete: 
<promise>DONE</promise>

**Good criteria:** "User can log in with Google and session persists"
**Bad criteria:** "Auth works correctly"

The more specific your acceptance criteria, the better Ralph performs.
  • User can log in with Google
  • Session persists across page reloads
  • User can log out
  • Tests pass
Output when complete: 
<promise>DONE</promise>

**优质标准示例：** “用户可通过Google登录，且会话在页面刷新后保持有效”
**劣质标准示例：** “认证功能正常工作”

你的验收标准越具体，Ralph的表现就越好。

Running the Loop

启动循环

bash
undefined
bash
undefined

Start building (Claude Code)

开始构建（Claude Code）

./scripts/ralph-loop.sh
./scripts/ralph-loop.sh

With max iterations

设置最大迭代次数

./scripts/ralph-loop.sh 20
./scripts/ralph-loop.sh 20

Using Codex CLI

使用Codex CLI

./scripts/ralph-loop-codex.sh
undefined
./scripts/ralph-loop-codex.sh
undefined

Logging (All Output Captured)

日志记录（捕获所有输出）

Every loop run writes all output to log files in 
logs/
:
  • Session log: 
    logs/ralph_*_session_YYYYMMDD_HHMMSS.log
    (entire run, including CLI output)
  • Iteration logs: 
    logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log
    (per-iteration CLI output)
  • Codex last message: 
    logs/ralph_codex_output_iter_N_*.txt
每次循环运行都会将所有输出写入
logs/
目录下的日志文件：
  • 会话日志： 
    logs/ralph_*_session_YYYYMMDD_HHMMSS.log
    （包含CLI输出的完整运行记录）
  • 迭代日志： 
    logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log
    （每次迭代的CLI输出）
  • Codex最后消息： 
    logs/ralph_codex_output_iter_N_*.txt

RLM Mode (Experimental)

RLM模式（实验性）

Provide a large context file and the agent will treat it as external environment. This is optional and experimental — it does not implement the full recursive runtime from the paper, but it does preserve all loop outputs on disk and guides the agent to query them as needed.
bash
./scripts/ralph-loop.sh --rlm-context ./rlm/context.txt
./scripts/ralph-loop-codex.sh --rlm-context ./rlm/context.txt
RLM workspace (when enabled):
  • rlm/trace/
    — Prompt snapshots per iteration
  • rlm/index.tsv
    — Index of all iterations
  • logs/
    — Full CLI output per iteration
Optional recursive subcalls:
bash
./scripts/rlm-subcall.sh --query rlm/queries/q1.md
This mirrors the Recursive Language Model (RLM) idea: handle huge prompts by inspecting only the slices you need.
提供一个大上下文文件，Agent会将其视为外部环境。 这是可选的实验性功能——它并未实现论文中完整的递归运行时，但确实会将所有循环输出持久化到磁盘，并引导Agent根据需要查询这些内容。
bash
./scripts/ralph-loop.sh --rlm-context ./rlm/context.txt
./scripts/ralph-loop-codex.sh --rlm-context ./rlm/context.txt
启用RLM后的工作区：
  • rlm/trace/
    —— 每次迭代的提示快照
  • rlm/index.tsv
    —— 所有迭代的索引
  • logs/
    —— 每次迭代的完整CLI输出
可选的递归子调用：
bash
./scripts/rlm-subcall.sh --query rlm/queries/q1.md
这呼应了递归语言模型（RLM）的理念：通过仅查看所需的片段来处理超大提示。

Two Modes

两种模式

ModePurposeCommand
build (default)Pick spec, implement, test, commit
./scripts/ralph-loop.sh
plan (optional)Create detailed task breakdown
./scripts/ralph-loop.sh plan
模式用途命令
build（默认）选择规范、实现、测试、提交
./scripts/ralph-loop.sh
plan（可选）创建详细的任务分解
./scripts/ralph-loop.sh plan

Key Principles

核心原则

Let Ralph Ralph

让Ralph自主工作

Trust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.
信任AI能够自我识别问题、自我修正和自我提升。观察模式并调整提示词。

YOLO Mode

YOLO模式

For Ralph to work effectively, enable full autonomy:
  • Claude Code: 
    --dangerously-skip-permissions
  • Codex: 
    --dangerously-bypass-approvals-and-sandbox
⚠️ Use at your own risk. Only in sandboxed environments.
为了让Ralph有效工作，需要启用完全自主权限：
  • Claude Code：
    --dangerously-skip-permissions
  • Codex：
    --dangerously-bypass-approvals-and-sandbox
⚠️ 风险自担。仅在沙箱环境中使用。

Links

相关链接