ralph-mode

Ralph モード

Ralph は、自律型 AI コーディングループです。すべてのタスクが完了するまで、新しいコンテキストウィンドウを繰り返し起動します。各イテレーションは新しい状態から始まり、メモリは git の履歴とテキストファイルを通じて保持されます。

名前の由来は、『ザ・シンプソンズ』の Ralph Wiggum です。いつも混乱していて、よく間違えますが、決して止まりません。基本理念は、完璧さよりも反復です。

2 つの実行モード

Ralph は、2 つの環境で動作します。

モード	環境	動作	新しいコンテキストを得る方法
ローカル	CLI ターミナル	Bash ループが claude -p を起動します	新しい CLI プロセス
リモート	Web/API/Agent SDK	コントローラーが Task サブエージェントを起動します	新しい Task 呼び出し

どちらのモードも、コンテキストの劣化を避けるため、イテレーションごとに新しいコンテキストを用意するという同じ目標を達成します。

クイックスタート

Ralph を初期化する

bun .claude/skills/ralph-mode/scripts/init-ralph.ts

これにより、必要なファイル一式を含む scripts/ralph/ が作成されます。

PRD を作成する

ユーザーストーリーを scripts/ralph/prd.json に記述します（prd-guide.md を参照）。

Ralph を実行する

ローカルモード（CLI）：

./scripts/ralph/ralph.sh 20      # AFK: 20 iterations max
./scripts/ralph/ralph-once.sh    # HITL: single iteration

リモートモード（Web/API）： scripts/ralph/ralph-controller.md を読み込み、指示に従います。コントローラーは各ストーリーに対して Task サブエージェントを起動します。

動作の仕組み

ローカルモード（Bash ループ）

┌─────────────────────────────────────────┐
│  ralph.sh (bash loop)                   │
│  └─▶ claude -p < prompt.md              │
│       └─▶ Implements ONE story          │
│       └─▶ Commits if passing            │
│       └─▶ Updates state files           │
│  └─▶ Loop until done or max iterations  │
└─────────────────────────────────────────┘

リモートモード（Task ベース）

┌─────────────────────────────────────────┐
│  Ralph Controller (you or outer agent)  │
│  └─▶ Reads prd.json, progress.txt       │
│  └─▶ Selects next story                 │
│  └─▶ Task(general-purpose) ────────────────┐
│       │                                    │
│       ▼                                    │
│  ┌─────────────────────────────────────┐   │
│  │  Ralph Worker (subagent)            │   │
│  │  - Fresh context window             │   │
│  │  - Implements ONE story             │   │
│  │  - Runs feedback loops              │   │
│  │  - Commits if passing               │   │
│  │  - Updates state files              │   │
│  └─────────────────────────────────────┘   │
│       │                                    │
│       ◀────────────────────────────────────┘
│  └─▶ Verifies result                    │
│  └─▶ Loop until done or max iterations  │
└─────────────────────────────────────────┘

重要なポイント：各 Task() 呼び出しによって新しいコンテキストウィンドウが作成されます。これはまさに Ralph に必要なものです。

ファイル構成

scripts/ralph/
├── ralph.sh            # Local: AFK mode loop
├── ralph-once.sh       # Local: HITL single iteration
├── ralph-controller.md # Remote: Controller instructions
├── ralph-worker.md     # Remote: Worker template
├── prompt.md           # Local: Iteration prompt
├── prd.json            # User stories with completion status
└── progress.txt        # Accumulated learnings

リモートモード：サブエージェントの使用を徹底する

リモートモードでは、コントローラーがコードを直接実装してはなりません。

❌ Controller writes code     → Context rot, defeats purpose
✅ Controller spawns workers  → Fresh context per story

コントローラーが行うのは、次の作業だけです。

1. 状態ファイルを読み込む
2. 次のストーリーを選ぶ
3. Task サブエージェントを起動する
4. 結果を検証する
5. ループを繰り返す

実装はすべて、新しいコンテキストを持つサブエージェントが行います。

ワーカーの起動

Task({
  subagent_type: "general-purpose",
  description: "Implement US-003: Add email validation",
  prompt: `[contents of ralph-worker.md with story details filled in]`
})

ワーカーの責任

各ワーカーサブエージェントは、次の作業を行います。

1. コンテキストを読み込む（progress.txt、AGENTS.md）
2. ストーリーを 1 つ実装する
3. フィードバックループを実行する（typecheck、lint、test）
4. すべて合格した場合にのみコミットする
5. prd.json と progress.txt を更新する
6. 結果をコントローラーに報告する

メモリの保持

Ralph はイテレーションごとにすべてを忘れます。メモリが保持されるのは、次のものを通じてのみです。

ファイル	目的
prd.json	タスクの状態（passes フィールド）
progress.txt	学び、パターン、注意点
Git commits	実装履歴
AGENTS.md	プロジェクトの恒久的なパターン

成功のための 11 のヒント

1. Ralph はループです

タスクを選ぶのはあなたではなく、エージェントです。最終状態を定義すれば、Ralph がそこに到達します。

2. まずは HITL、その後 AFK

• HITL：見守り、介入し、プロンプトを調整します
• AFK：基盤が固まったら、大量の作業を任せます

3. スコープを定義する

明示的な passes フィールドと受け入れ条件を備えた PRD 項目を作成します。

4. 進捗を記録する

progress.txt がメモリです。Codebase Patterns を冒頭に記載します。

5. フィードバックループを使う

typecheck、lint、test がすべて合格しない限り、コミットを禁止します。

6. 小さなステップで進める

1 回のイテレーションにつき 1 つのストーリーに取り組みます。コンテキストの劣化は実際に起こります。

7. リスクの高いタスクを優先する

アーキテクチャ → 統合 → 機能 → 仕上げ

8. 品質への期待を明確にする

プロトタイプ、製品品質、ライブラリのどれを目指すかを Ralph に伝えます。

9. サンドボックスを使う

ローカルでの AFK には Docker を使います。リモートでは分離された環境を使います。

10. 対価を払って活用する

HITL であっても、Ralph は手動で複数フェーズのプロンプトを使うより効果的です。

11. 自分流にする

Ralph は単なるループです。カバレッジ、lint、リファクタリングなどに合わせて調整してください。

使用例

ローカル HITL（学習）

./scripts/ralph/ralph-once.sh
# Watch output, intervene if needed
# Run again when ready

ローカル AFK（一晩）

./scripts/ralph/ralph.sh 50  # Let it run

リモート HITL（Web セッション）

1. ralph-controller.md を読む
2. prd.json と progress.txt を読む
3. ストーリーを選ぶ
4. ワーカープロンプトを使って Task サブエージェントを 1 つ起動する
5. 結果を検証する
6. 手動で繰り返す

リモート AFK（エージェント間）

外側のエージェントまたは Agent SDK プログラムがコントローラーループを実行し、すべてのストーリーが合格するまでサブエージェントを起動します。

進捗の監視

# Story status
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

# Learnings
cat scripts/ralph/progress.txt

# Recent commits
git log --oneline -10

安全性

• ローカルの AFK では --dangerously-skip-permissions を使用します
• 可能な場合は Docker サンドボックスを使用します
• 反復回数には必ず上限を設定します
• Ctrl+C を押すと、ローカルのループが直ちに停止します
• git reset --hard を実行すると、コミットされていない変更が元に戻ります

使用しないケース

• 明確な成果が定まっていない探索的な作業
• 明示的な基準のない大規模なリファクタリング
• 人間によるレビューが必要なセキュリティ上重要なコード
• 初期段階のアーキテクチャ上の決定（HITL を使用します）

参考資料

• prd-guide.md - 効果的なユーザーストーリーの作成方法
• patterns.md - 一般的なパターンと注意点
• ralph-controller.md - リモートコントローラーの手順
• ralph-worker.md - ワーカーサブエージェントのテンプレート