ralph-wiggum

Ralph Wiggum

仕様駆動開発による自律型 AI コーディング

Ralph Wiggum とは？

Ralph Wiggum は、Geoffrey Huntley の反復型 bash ループと仕様駆動開発を組み合わせ、AI の支援によるソフトウェア開発を完全に自律的に行います。

重要なポイントは、反復ごとに新しいコンテキストを使うことです。各ループでは、コンテキストウィンドウをクリーンな状態にして新しいエージェントプロセスを開始するため、コンテキストのあふれや劣化を防げます。

このスキルを使用する場面

次のような場合に Ralph Wiggum を使用してください。

• 実装する仕様や機能が複数ある
• AI にタスクを自律的に進めてほしい
• 受け入れ基準を一貫して検証可能な形で完了させる必要がある
• 長時間のセッションでコンテキストウィンドウの問題を避けたい

仕組み

┌─────────────────────────────────────────────────────────────┐
│                     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)        │
└─────────────────────────────────────────────────────────────┘

インストール

クイックインストール（スキルインストーラー経由）

# Using Vercel's add-skill
npx add-skill fstandhartinger/ralph-wiggum

# Using OpenSkills
openskills install fstandhartinger/ralph-wiggum

フルセットアップ（推奨）

憲章とインタビューを含む Ralph Wiggum のフルセットアップを行うには、次の手順に従います。

# Tell your AI agent:
"Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum"

エージェントが、手軽で快適なセットアップを案内します。

1. クイックセットアップ（約1分）— ディレクトリを作成し、スクリプトをダウンロードします
2. プロジェクトインタビュー — 技術的な詳細ではなく、ビジョンと目標に焦点を当てます
3. 憲章 — すべてのセッションの指針となるドキュメントを作成します
4. 次のステップ — 仕様の作成と Ralph の開始方法を明確に案内します

既存のプロジェクトでは、エージェントが技術スタックを自動的に検出します。インタビューでは、何を構築しているか、そしてその理由の理解を優先します。

基本概念

1. ループごとに新しいコンテキスト

Ralph ループの各反復では、新しい AI エージェントプロセスを開始します。これにより、次のことが可能になります。

• コンテキストウィンドウがあふれない
• 時間の経過による劣化がない
• 各タスクをクリーンな状態で開始できる

2. ディスク上の共有状態

状態はファイルを介してループ間で保持されます。

• specs/ — 受け入れ基準を含む機能仕様
• ralph_history.txt — ブレークスルー、障害、学びのログ
• IMPLEMENTATION_PLAN.md — 詳細なタスク分解（任意）

3. 完了シグナル

エージェントが <promise>DONE</promise> を出力するのは、次の条件をすべて満たした場合のみです。

• すべての受け入れ基準が検証されている
• テストに合格している
• 変更がコミットされ、プッシュされている

bash ループはこのフレーズを確認します。見つからない場合は再試行します。

4. テストによるバックプレッシャー

テスト、リンター、ビルドがガードレールとして機能します。エージェントは完了シグナルを出力する前に、問題を修正する必要があります。

使用方法

仕様の作成

成功の鍵： 各仕様には、明確でテスト可能な受け入れ基準が必要です。これによって、Ralph はタスクが本当に「完了」したかどうかを判断できます。

# Feature: User Authentication

## Requirements
- OAuth login with Google
- Session management
- Logout functionality

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

良い基準：「ユーザーが Google でログインでき、セッションが保持される」 悪い基準：「認証が正しく動作する」

受け入れ基準を具体的にするほど、Ralph のパフォーマンスが向上します。

ループの実行

# Start building (Claude Code)
./scripts/ralph-loop.sh

# With max iterations
./scripts/ralph-loop.sh 20

# Using Codex CLI
./scripts/ralph-loop-codex.sh

ログ（すべての出力を記録）

ループを実行するたびに、logs/ 内のログファイルにすべての出力が書き込まれます。

• セッションログ： logs/ralph_*_session_YYYYMMDD_HHMMSS.log（CLI の出力を含む実行全体）
• 反復ログ： logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log（反復ごとの CLI 出力）
• Codex の最後のメッセージ： logs/ralph_codex_output_iter_N_*.txt

2 つのモード

モード	目的	コマンド
build（デフォルト）	仕様を選択し、実装、テスト、コミットを行います	./scripts/ralph-loop.sh
plan（任意）	詳細なタスク分解を作成します	./scripts/ralph-loop.sh plan

主な原則

Ralph に Ralph らしくさせる

AI が自ら課題を特定し、修正し、改善することを信頼してください。パターンを観察し、プロンプトを調整します。

YOLO モード

Ralph が効果的に動作するには、完全な自律性を有効にしてください。

• Claude Code：--dangerously-skip-permissions
• Codex：--dangerously-bypass-approvals-and-sandbox

⚠️ 自己責任で使用してください。 サンドボックス環境でのみ使用してください。

リンク

• GitHub： https://github.com/fstandhartinger/ralph-wiggum
• ウェブサイト： https://ralph-wiggum.ai
• 元の方法論： Geoffrey Huntley の how-to-ralph-wiggum