ralph-loop

Ralph Wiggum ループモード

「混乱していても決して諦めない」シンプソンズのキャラクターにちなんで名付けられたこの手法では、プロンプトは同じまま、コードベースに変更が蓄積されるループで Claude Code を実行します。各イテレーションでは前回までの作業を読み込み、完了するまで続けます。

Ralph モードを使用するタイミング

最適な用途：

• 完了条件が明確で、適切に定義された実装タスク
• リファクタリングや移行作業（例：React v16 から v19 への移行）
• テスト駆動開発のサイクル（テストに合格するまで実行）
• バッチ処理や反復的なタスク
• 夜間の自律的な作業セッション

適していない用途：

• 設計上の判断や人間の判断が必要なタスク
• 明確な終了状態がない探索的な作業
• 実行中に要件が変わる可能性のあるタスク
• コードを理解する必要がある初回の実装

有効化の手順

ステップ 1：タスクの適性を確認する

有効化する前に、以下を確認してください。

• タスクの完了条件が明確で、測定可能である
• 成功をプログラムで検証できる（テスト、ビルド、特定のファイルの状態など）
• 作業対象が Git で追跡されているディレクトリである
• 成功がどのような状態か理解している

ステップ 2：状態ファイルを作成する

以下の構成で .claude/ralph-loop.local.md を作成します。

---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

# Your Task Prompt Here

## Objective
[Clear statement of what needs to be accomplished]

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
Run these to check progress:
- `[test command]`
- `[build command]`

## Context
- Read [relevant files] for specifications
- Follow [conventions file] for code style

ステップ 3：TODO.md を作成する（推奨される完了方法）

プロジェクトのルートに TODO.md を作成します。

# Task Checklist

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Completion
- [ ] ALL_TASKS_COMPLETE

ステップ 4：ループを開始する

通常どおり Claude を実行するだけです。Stop フックが状態ファイルを検出し、完了が検知されるまでループを継続します。

claude

2 つの完了方法

方法 1：TODO.md マーカー（推奨）

フックは TODO.md に [x] ALL_TASKS_COMPLETE があるかを確認します。次の理由から、こちらのほうが信頼性が高くなります。

• ファイルシステム上で確認できる
• Git で追跡できる
• Claude が簡単に更新できる
• 進捗を確認できる（X/Y 個のタスクが完了）

方法 2：Promise タグ（従来の方法）

状態ファイルで completion_promise を設定し、完了時に <promise>YOUR_TEXT</promise> を出力します。

---
active: true
iteration: 0
max_iterations: 20
completion_promise: "feature implemented"
---

Claude が <promise>feature implemented</promise> を出力すると、ループが終了します。

設定オプション

.claude/ralph-loop.local.md のフロントマターで設定します。

オプション	デフォルト	説明
active	true	ループを無効にするには false に設定します
iteration	0	現在のイテレーション回数（自動的に増加）
max_iterations	20	安全のための上限（0 = 無制限）
completion_promise	null	Promise による完了判定で一致させるテキスト

実行中

イテレーションのステータス

各イテレーションで以下を表示します。

• 現在のイテレーション番号
• タスクの進捗（TODO.md に基づく）
• 完了条件
• 残りの最大イテレーション回数

チェックポイント通知

5 回のイテレーションごとにチェックポイントのリマインダーが表示されます。

• 変更を確認する：git log --oneline -10
• 進捗が予定どおりか確認する
• 行き詰まっている場合はプロンプトの調整を検討する

手動での介入

ループを一時停止するには：

# Edit the state file
# Change active: true → active: false

すぐに停止するには：

rm .claude/ralph-loop.local.md

再開するには：

# Re-create or edit the state file
# Set active: true
claude

安全機能

• イテレーションの上限：無限ループを防止します（デフォルト：20）
• Git による追跡：すべての変更を元に戻せます
• チェックポイント通知：進捗確認を促します
• 明確な完了条件：明示的な成功が確認された場合にのみループを終了します
• コストの把握：イテレーション回数を追跡し、API コストを見積もれます

例：MetricFlow フェーズ 7～8

---
active: true
iteration: 0
max_iterations: 25
completion_promise: null
---

# MetricFlow Phase 7-8: Educator Agent

## Objective
Implement the Educator Agent that uses Claude API to generate educational
explanations for code metrics.

## Completion Criteria
Complete when TODO.md shows [x] ALL_TASKS_COMPLETE

## Verification Commands
- `cd backend && python -m pytest tests/test_educator.py -v`
- `cd backend && python -c "from app.agents.educator import EducatorAgent; print('OK')"`

## Context
- Read docs/plans/MASTER_PLAN.md sections 5.3 (Educator Agent)
- Follow CLAUDE.md for project conventions
- Analyzer and Pattern agents already complete (use their output formats)

## Instructions
1. Check TODO.md for current task list
2. Implement next incomplete task
3. Write tests as you go
4. Run verification after each change
5. Mark [x] ALL_TASKS_COMPLETE when done

対応する TODO.md：

# Phase 7-8: Educator Agent

## Tasks
- [ ] Create EducatorAgent class skeleton in backend/app/agents/educator.py
- [ ] Add Claude API client initialization
- [ ] Implement explain_complexity() method
- [ ] Implement explain_maintainability() method
- [ ] Implement explain_code_smells() method
- [ ] Add course concept mapping
- [ ] Write unit tests for all methods
- [ ] Integration test with Analyzer output

## Completion
- [ ] ALL_TASKS_COMPLETE

トラブルシューティング

ループが開始しない場合：

• .claude/ralph-loop.local.md が存在することを確認します
• frontmatter で active: true が設定されていることを確認します

ループが停止しない場合：

• TODO.md に [x] ALL_TASKS_COMPLETE が正確に記載されていることを確認します（大文字と小文字は区別されません）
• または、completion_promise が出力タグと一致していることを確認します
• max_iterations が 0（無制限）に設定されていないことを確認します
• 手動で停止する場合：rm .claude/ralph-loop.local.md

同じエラーで行き詰まる場合：

• エラーのパターンを確認します
• より具体的な指示を追加してプロンプトを調整します
• タスクをより小さなサブタスクに分割することを検討します

コストが高すぎる場合：

• max_iterations を減らします
• 早い段階で確認できるよう、チェックポイントの間隔を短くします
• タスクが Ralph モードには複雑すぎないか検討します

成功のためのヒント

1. 明確なプロンプトでイテレーションを 40～60% 削減できます - 具体的に指示します
2. 慣れるまでは max_iterations を小さく（5～10）設定します
3. チェックポイントごとに Git コミットします - 簡単にロールバックできます
4. TODO.md の完了条件を使います - promise タグより信頼性が高くなります
5. 最初の数回のイテレーションを監視します - 問題のあるパターンを早期に発見できます
6. 監督付きの自律性 - コースのプロジェクトではチェックポイントで確認します

コストの見積もり

タスクの複雑さ	イテレーション	推定コスト
シンプル（単一の機能）	5-10	$5-15
中程度（複数ファイルの変更）	10-20	$15-30
複雑（フェーズ全体）	20-50	$30-75

クイックスタートテンプレート

# 1. Create state file
mkdir -p .claude
cat > .claude/ralph-loop.local.md << 'EOF'
---
active: true
iteration: 0
max_iterations: 20
completion_promise: null
---

# Your Task

## Objective
[What you want to accomplish]

## Completion
Check TODO.md for [x] ALL_TASKS_COMPLETE
EOF

# 2. Create TODO.md
cat > TODO.md << 'EOF'
# Tasks
- [ ] First task
- [ ] Second task

## Completion
- [ ] ALL_TASKS_COMPLETE
EOF

# 3. Start Ralph loop
claude