super-ralph-wiggum

Super Ralph Wiggum

Claude Code 向けの自律反復ループです。タスクが完了するまで同じプロンプトを繰り返し実行し、ファイルと git 履歴を通じてコンテキストを維持します。

Ralph の理念

タスクを選ぶのはあなたではなく、エージェントです。

あなたは最終状態を定義します。そこに到達する方法は Ralph が考えます。

複数フェーズの計画では、人間が各フェーズの開始時に新しいプロンプトを書きます。Ralph では、エージェントが PRD から次に取り組む内容を選びます。目的地を説明すれば、Ralph が道筋を見つけます。

11 のヒント（クイックリファレンス）

AI Hero の決定版ガイドに基づいています。

#	ヒント	要点
1	Ralph はループです	同じプロンプトを複数回反復
2	HITL から始め、その後 AFK に移行	学ぶ → 信頼する → 任せる
3	範囲を定義する	明示的な停止条件で無限ループを防ぐ
4	進捗を追跡する	progress.txt でコンテキストウィンドウ間をつなぐ
5	フィードバックループを使う	型、テスト、リンティングをガードレールとして活用
6	小さなステップで進める	コミットごとに論理的な変更を 1 つ行う
7	リスクの高いタスクを優先する	アーキテクチャを先に、簡単な成果を最後に
8	ソフトウェアの品質を定義する	どのようなリポジトリなのか Ralph に伝える
9	Docker サンドボックスを使う	AFK の安全性に不可欠
10	コストをかけて実行する	AFK を使わなくても HITL は有用
11	自分に合わせてカスタマイズする	代替のループタイプやタスクソース

各ヒントの詳細なガイダンスは @references/tips-and-tricks.md を参照してください。

クイックスタート

テンプレートを使って Ralph ループを開始するには：

Run the super-ralph-wiggum skill with the test-coverage template, max 20 iterations

PRD ファイルを使って開始するには：

Run super-ralph-wiggum with feature-prd template using ./prd.json

利用可能なテンプレート

テンプレート	用途	デフォルトの反復回数
test-coverage	テストカバレッジを目標の割合まで向上させる	30
feature-prd	PRD ファイルから機能を実装する	20
lint-fix	すべてのリンティングエラーを段階的に修正する	30
docs-generation	モジュールのドキュメントを生成する	25
dataset-generation	トレーニングデータのサンプルを生成する	50
migration	新しいフレームワーク／バージョンに移行する	40
entropy-loop	ソフトウェアのエントロピーを減らす（不要なコード、コードの問題）	30
duplication-loop	重複コードを排除する	25

呼び出しパターン

テンプレートモード（推奨）

一般的なタスクには、事前に用意されたテンプレートを使います：

Use super-ralph-wiggum with [template-name] template
Options: --max-iterations N, --browser (for UI verification)

PRD モード

タスクを追跡しながら構造化された機能開発を行う場合：

Use super-ralph-wiggum with feature-prd template
PRD file: ./prd.json

PRD ファイルでは、passes: true/false を使って機能を追跡します。すべての機能が合格するとループが完了します。

HITL モード（1 回の反復）

対話的な学習やペアプログラミングの場合：

Use super-ralph-wiggum with --once flag to [task description]

ループせずに 1 回だけ反復を実行します。Ralph の動作を学ぶのに最適です。

カスタムプロンプト

テンプレートで対応できないタスクの場合：

Use super-ralph-wiggum with custom prompt:
[Your detailed task description with completion criteria]
Completion: Output <promise>COMPLETE</promise> when done
Max iterations: 15

2 つのモード：HITL と AFK

モード	動作	最適な用途
HITL（human-in-the-loop）	1 回実行して見守り、必要に応じて介入する	学習、プロンプトの調整、リスクの高いタスク
AFK（away from keyboard）	最大反復回数を設定してループ実行する	大量作業、低リスクのタスク、夜間の実行

進め方はシンプルです：

1. HITL から始めて、学習と調整を行う
2. プロンプトを信頼できるようになったら AFK に移行する
3. 戻ったらコミットを確認する

AFK では、必ず反復回数に上限を設定してください：

• 小さなタスク：5～10 回
• 中規模のタスク：15～30 回
• 大規模な機能：30～50 回

ソフトウェアの品質を明示的に定義する

Ralph は、これが使い捨てのプロトタイプなのか、本番用コードなのかを知りません。明示して伝えてください。

リポジトリの種類	伝える内容	期待される動作
プロトタイプ	「完璧さより速度を優先。エッジケースは省略してください。」	近道を選ぶ
本番用	「保守しやすいコードにしてください。ベストプラクティスに従ってください。」	テストやドキュメントを追加する
ライブラリ	「公開 API です。後方互換性が重要です。」	互換性を損なう変更に慎重になる

コード品質に関するプロンプト

ループで高いコード品質を維持する必要がある場合は、事実に基づいて指定してください。

既存のコード規約と品質基準を維持してください。 変更を加えるたびに、テストカバレッジを変更前と同等以上にしてください。 大規模な書き換えより、段階的な改善を優先してください。

意欲をかき立てるような表現（「エントロピーに立ち向かう」「徹底する」など）は避けてください。Claude 4.6 はすでに綿密に取り組む傾向があり、こうした表現は計画を立てすぎる方向に働きます。事実に基づく品質基準のほうが効果的です。

リポジトリの実態が優先されます

指示はコードベースと競合することがあります。Ralph がリポジトリを調べると、指示された内容と実際に行われている内容という、2 つの情報源を目にします。

「any 型は絶対に使わないでください」と指示しても、Ralph が既存のコードに any があちこちで使われているのを見れば、指示ではなくコードベースに従います。

Claude は既存のコードベースからパターンを学習します。コードベース全体で any 型を使っていれば、指示にかかわらずループもそのパターンに従います。ループを実行する前に、重視したいパターンを具体的に整えてください。

タスクの優先順位

次のタスクを選ぶ際、Ralph は以下の順に優先してください。

1. アーキテクチャ上の判断と中核となる抽象化
2. モジュール間の統合ポイント
3. 未知の未知とスパイク作業
4. 標準的な機能と実装
5. 仕上げ、クリーンアップ、すぐにできる改善

リスクの高い作業は早めに失敗を確認してください。簡単にできる改善は後回しにします。

初期のアーキテクチャ上の判断には HITL Ralph を使用してください。こうしたタスクで書かれたコードは、ずっと残ります。基盤が固まってから AFK Ralph を使用してください。

実行モード

1. セッション内モード（デフォルト）

ストップフックを使用して、現在の Claude Code セッション内でループを実行します。

Use super-ralph-wiggum with test-coverage template, max 20 iterations

• ストップフックが終了の試みを捕捉します
• 各イテレーションに同じプロンプトが再度渡されます
• コンテキストはファイルと git を通じて保持されます
• 対話しながら、または監視しながら作業する場合に最適です

2. Docker モード（外部）

Docker サンドボックスを使用する bash スクリプトを介して、ループを外部で実行します。

# Generate external script
./scripts/setup-ralph-loop.sh --template test-coverage --docker > run-ralph.sh
chmod +x run-ralph.sh

# Run in background
./run-ralph.sh 20 &

• 各イテレーションで新しい Claude Code インスタンスが起動します
• 安全のために Docker で隔離します
• 夜間や AFK で実行する場合に最適です
• メモリはファイルを通じてのみ保持されます

AFK の安全性を確保するうえで重要です：Docker サンドボックス内の Ralph はプロジェクトファイルを編集してコミットできますが、ホームディレクトリ、SSH キー、システムファイルにはアクセスできません。

動作の仕組み

1. セットアップ：.claude/ralph-loop.local.md に状態ファイルを作成します
2. 進捗：プロジェクトのルートに progress.txt を自動作成します
3. ループ：ストップフックが終了を捕捉し、同じプロンプトを再度渡します
4. 完了：<promise>COMPLETE</promise> または PRD の全項目の合格を検出します
5. 学習：イテレーションを重ねるごとに、パターンが progress.txt に蓄積されます

主なオプション

オプション	説明	デフォルト
--template <name>	事前構築済みのテンプレートを使用します	（指定必須、またはカスタムプロンプトを指定）
--prd <file>	タスク追跡用の PRD ファイル	なし
--max-iterations <n>	イテレーションの上限	テンプレートによって異なります
--completion-promise <text>	カスタムの完了フレーズ	COMPLETE
--progress <file>	進捗ファイルの場所	./progress.txt
--browser	ブラウザテストのプロンプトを有効にします	false
--once	1 回だけ実行します（HITL モード）	false

ベストプラクティス

1. 小さなストーリー

タスクは 1 つのコンテキストウィンドウ内に収めてください。大きな機能は、独立した小さなストーリーに分割します。

2. 検証を最優先

コミットする前に必ず型チェックとテストを実行してください。テンプレートではこれを必須としています。

3. イテレーション数に上限を設定

AFK（無人実行）の Ralph では、必ず --max-iterations を設定してください。確率的なシステムで無限ループが発生すると危険です。

4. 明確な完了基準

タスクが曖昧だと無限ループになるおそれがあります。停止条件を明確にしてください。

5. 進捗ファイルを使用

前回のイテレーションで得た知見は progress.txt に保持されます。テンプレートが自動的にこの情報を取り込みます。

6. 1 回のコミットにつき 1 つの変更

変更は小さく、焦点を絞ってください。大きなコミットを 1 つ作るより、小さなコミットを複数作ることを優先します。

7. 状態を適切に構造化する

カバレッジ率、機能の合否、移行件数などの構造化された進捗データには JSON を使用します。所見やセッションで得た知見は、自由形式のテキストとして progress.txt に記録します。反復の間に git コミットをチェックポイントとして使用し、新しいコンテキストウィンドウからファイルシステム上の状態を確認できるようにします。

参考資料

詳しいガイダンスについては、参考ファイルをお読みください。

• @references/tips-and-tricks.md - AI Hero の知見を取り入れて詳しく解説した 11 のヒント
• @references/prompt-patterns.md - 収束型プロンプトの 10 のパターン
• @references/prd-schema.md - PRD ファイルの構造と使い方
• @references/cost-estimation.md - API コストのガイドライン
• @references/browser-testing.md - Dev-browser との統合

テンプレートの詳細

test-coverage

次の手順でテストカバレッジを向上させます。

1. カバレッジを実行して不足箇所を見つける
2. テストされていないユーザー向け動作のうち、最も重要なものを特定する
3. 反復ごとに意味のあるテストを 1 つだけ作成する
4. 必須ではないコードには /* v8 ignore */ を使用する
5. テストが成功するたびにコミットする

テンプレート全文を読む：@templates/test-coverage.md

feature-prd

次の手順で PRD ファイルの機能を実装します。

1. prd.json を読み、未完了の機能のうち優先度が最も高いものを選ぶ
2. 依存関係が満たされていることを確認する
3. 反復ごとに機能を 1 つだけ実装する
4. 検証を実行する（型チェックとテスト）
5. 発見したパターンを AGENTS.md に追加する
6. 機能を passes: true に設定する

テンプレート全文を読む：@templates/feature-prd.md

lint-fix

次の手順で lint エラーを修正します。

1. リンターを実行してエラー一覧を取得する
2. エラーが最も多いファイルを選ぶ
3. そのファイルのエラーをすべて修正する
4. 修正によってテストが壊れていないことを確認する
5. コミットして次のファイルに進む

テンプレート全文を読む：@templates/lint-fix.md

entropy-loop

次の手順でソフトウェアのエントロピーを低減します。

1. コードの問題点（未使用のエクスポート、デッドコード、TODO など）をスキャンする
2. 反復ごとに問題を 1 つだけ修正する
3. 検証を実行する
4. 変更内容を progress.txt に記録する

テンプレート全文を読む：@templates/entropy-loop.md

duplication-loop

次の手順でコードの重複を解消します。

1. jscpd を実行して重複を見つける
2. 重複グループを 1 つ特定する
3. 共通コードをユーティリティ／ヘルパーに切り出す
4. すべての呼び出し箇所を更新する
5. テストで検証する

テンプレート全文を読む：@templates/duplication-loop.md

docs-generation

次の手順でドキュメントを生成します。

1. ドキュメント化されていない公開関数を特定する
2. 反復ごとにドキュメントを 1 つだけ作成する
3. 例がコンパイル／実行できることを確認する
4. JSDoc と README の更新を含める

テンプレート全文を読む：@templates/docs-generation.md

dataset-generation

次の手順でトレーニングデータを生成します。

1. 品質基準を満たすサンプルを作成する
2. 各反復で品質を検証する
3. progress.txt に件数を記録する
4. 目標件数に達したら停止する

テンプレート全文を読む：@templates/dataset-generation.md

migration

次の手順でコードベースを移行します。

1. ファイルから移行計画を読む
2. 反復ごとにモジュールを 1 つだけ移行する
3. 移行のたびにテストが成功することを確認する
4. 移行済みと未移行の件数を記録する

テンプレート全文を読む：@templates/migration.md

ループのキャンセル

実行中の Ralph ループを停止するには、状態ファイルを削除します。

rm .claude/ralph-loop.local.md

または、最大反復回数に達するまで待ちます。

クレジット

Geoffrey Huntley による Ralph Wiggum 手法に基づいています。 Ryan Carson、Matt Pocock、および AI Hero の知見を取り入れて強化されています。