Claude Ralph Loop とは｜自律反復プラグインの使い方を解説

Ralph Loop とは — Stop Hook で終了を遮る「死なないループ」

Ralph Loop は、Geoffrey Huntley が「everything is a ralph loop」で提唱した極めてシンプルなパターンです。中身は while ループ 1 個と LLM トークンであり、エージェントに同じプロンプトを延々と読ませて、ファイルシステムを記憶領域として使い倒すというだけのアイデアです。Anthropic 公式実装ではこれを Claude Code の Stop Hook で実現しています。Claude が「タスクは終わった」と判断して終了しようとした瞬間に Hook がそれをブロックし、最初に与えたプロンプトをそのまま再投入することで、人間が介入しない反復改善サイクルを生成します。なぜ「Ralph」かというと、シンプソンズの登場人物 Ralph Wiggum がジェットコースターでループする画像が原典記事の表紙に使われているからで、「物事はとにかくループさせれば形になる」という思想を象徴的に表しています。Huntley 自身の表現では「ソフトウェアは陶芸の粘土のようなもので、必要なだけ何度もろくろに戻せばよい」というのが思想の核です(出典: ghuntley.com/loop)。

公式プラグイン化された Ralph Loop — /plugin install ralph-wiggum 1 行で導入

本節のコマンド・構文は 2026 年 5 月時点の公式 README に基づきます。 マーケットプレイスのプラグインは仕様やコマンド構文の改定が早いため、最新の構文は導入後に /plugin 一覧と公式 README で必ず確認してください。

Anthropic は 2026 年に公開した公式マーケットプレイス claude-plugins-official の中に、Ralph Loop を ralph-wiggum プラグインとして組み込みました。Claude Code 起動後にプラグイン一覧を開くか、コマンドラインから次のコマンドを実行すれば 1 行で導入できます。

# 公式マーケットプレイスから ralph-wiggum プラグインを導入
/plugin install ralph-wiggum@claude-plugins-official

# 導入後に有効化(/ralph-loop と /cancel-ralph が使えるようになる)
/reload-plugins

インストール後は /reload-plugins で有効化し、/ralph-loop と /cancel-ralph の 2 コマンドが使えるようになります。プラグインの実体は ~/.claude/plugins/cache/claude-plugins-official/ralph-wiggum/<hash>/hooks/hooks.json に展開され、Stop Hook の起動コマンドだけがハンドラとして登録されます。Windows 環境では Git for Windows 同梱の Git/bin/bash.exe(ラッパー版)を使う設定が公式 README に明記されており、Git/usr/bin/bash.exe(MinGW 版)では Hook 自体が起動しない既知問題があるため、初期設定のままで問題なく動きます。プラグイン化されたことで、自前で Stop Hook の YAML を書かなくてもよくなり、導入の心理的ハードルが大幅に下がりました(出典: claude-plugins-official ralph-loop README)。

/ralph-loop コマンドの使い方 — --max-iterations と --completion-promise を必ずセットで

/ralph-loop コマンドの基本構文は /ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>" です。3 つの要素のうち、プロンプトは Claude が毎反復で読み返す「指示書」そのものなので、明確な完了基準と完了時に出力すべきトークンを必ず書き込みます。例えば次のように、要件・テストカバレッジ目標・完了トークンの 3 点を 1 文字列に詰め込むのが推奨されます。

# プロンプト + --completion-promise + --max-iterations の 3 要素を必ずセットで指定
/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests with coverage > 80%. Output <promise>COMPLETE</promise> when done." \
  --completion-promise "COMPLETE" \
  --max-iterations 50

--max-iterations は省略時は無制限となるため、初回利用時は必ず 10〜20 程度を指定して暴走を防ぎます。--completion-promise は完全一致で判定されるため、ゆらぎが許されません。プロンプト内では「成功時のみ <promise>COMPLETE</promise> を出力せよ」と明示し、完了条件をテストの全通過や lint エラー 0 件などに紐づけておくと事故を減らせます。終了条件を満たさないまま --max-iterations に到達すると、Claude が「これ以上進めない理由」「試した内容」「代替案」を残して停止する設計になっており、続きから人間が判断できる形で引き継げます(出典: ralph-loop プラグイン仕様)。

内部仕組みの解剖 — Stop Hook が終了をインターセプトする 6 ステップ

Ralph Loop の内部動作は 6 ステップに分解できます。

1. ユーザーが /ralph-loop を起動し、Claude にプロンプトを渡します。
2. Claude が通常通りツールを呼び出してコードを書き、テストを走らせ、結果を観察します。
3. タスクが終わったと判断した Claude がセッションを終了しようとします。
4. Stop Hook がその終了試行をインターセプトし、終了を阻止します。
5. Hook は最初のプロンプトを再投入し、Claude は前回の作業で書き換えられたファイルと git の変更履歴を見ながら状況を再評価します。
6. completion-promise トークンが Claude の出力に含まれるか、--max-iterations 上限に達するまでステップ 2〜5 が繰り返されます。

重要なのは、プロンプトが反復間で一切変わらないことと、状態が会話履歴ではなくファイルと git 履歴に永続化されることです。これにより、コンテキストウィンドウの肥大化を避けながら長時間タスクを回せます。Huntley が「failure is deterministically bad and informative」と表現するように、テスト失敗のような決定論的な失敗は次の反復で Claude が読み直すと「直すべき場所」として明確に機能するため、自己修正のフィードバックループが自然に成立します。

プロンプト設計のベストプラクティス — 完了基準・段階目標・自己修正手順を 1 文字列に

Ralph Loop の効果はプロンプトの質に強く依存します。

1. 完了基準を検証可能な形で書く。「make it good」のような曖昧な指示は反復の収束を不可能にします。All CRUD endpoints working、Tests passing (coverage > 80%)、README with API docs のように、Claude 自身がテスト実行や grep で確認できる条件に分解します。
2. 段階目標を明示する。「Phase 1: ユーザー認証(JWT 実装+テスト)、Phase 2: 商品カタログ(一覧・検索+テスト)、Phase 3: ショッピングカート(追加・削除+テスト)」のように分割し、最後にすべてが揃ったら完了トークンを出力するように指示します。
3. 自己修正プロセスを TDD 形式で書き込む。「失敗するテストを書く → 実装 → テスト実行 → 失敗時はデバッグ → リファクタ → 全グリーンになるまで繰り返し → COMPLETE 出力」という流れをプロンプト内に組み込んでおくと、各反復の挙動が安定します。
4. 安全装置としての文言を入れる。「15 反復後に未完了なら、進捗を阻んでいる原因・試した内容・代替案を文書化して停止せよ」と書き添えると、暴走時に有意義な記録が残ります。

暴走を防ぐ安全装置 — --max-iterations 必須・/cancel-ralph の役割

Ralph Loop は便利な反面、設定を誤るとトークンを延々と消費する危険があります。最大の安全装置は --max-iterations で、これは公式 README が「主要な制御機構」と明記する必須オプションです。completion-promise は完全一致のためゆらぎに弱く、プロンプトに書いた COMPLETE を Claude が Complete. のように出力した瞬間に終了判定が外れて永遠に回り続けます。これを補完するのが --max-iterations で、初回は 10〜20、慣れてきても最大 50 程度に抑えるのが安全です。実行中にループを止めたいときは別セッションから /cancel-ralph を呼び出すと、進行中のループを中断できます。さらに防御層を厚くしたい場合は、Claude Code 自体のサブスクリプション側でコスト警告を有効にしておくと、Claude Max 20x プランでも想定外の月次消費を避けられます。/ralph-loop を本番リポジトリで動かす場合は、必ず作業用ブランチを切って git push で安全網を張ってから始めるのが鉄則です(出典: Geoffrey Huntley によるセーフティ言及)。

向くタスクと向かないタスク — TDD グリーンフィールドに刺さり、本番デバッグには使うな

Ralph Loop は万能ツールではなく、明確に向くケースと向かないケースがあります。

向くケース:

1. 明確な成功基準があるタスク。テストの全通過や lint エラー 0 件のように機械的に判定できる目標があると効果が最大化します。
2. 反復改善が本質的に必要なタスク。TDD(テスト駆動開発)でレッド(失敗テスト)→グリーン(テスト通過)→リファクタを繰り返すような開発スタイルと相性が抜群です。
3. グリーンフィールド(既存コードのない新規プロジェクト)。既存コードベースへの影響を考えなくてよいため、暴走の被害が最小化されます。
4. 繰り返し作業の自動化。CI で検証可能なスクリプト整備や、テストフィクスチャの大量生成などが該当します。

向かないケース:

1. 人間の判断が必要なデザイン決定。UI のトーン&マナーやアーキテクチャ選定はループでは収束しません。
2. ワンショット操作。1 回で終わるタスクにループを被せるのは過剰設計です。
3. 成功基準が不明確なタスク。completion-promise を機械判定できない時点でループは破綻します。
4. 本番環境のデバッグ。副作用が読みにくい本番リソースに対して反復実行を許すのは事故の温床です。

実績と費用対効果 — $297 で $50k 相当のコードを生んだ事例

Geoffrey Huntley が公開している実績は、Ralph Loop の費用対効果を端的に示しています。Y Combinator が主催したハッカソンでは、彼は一晩で 6 つのリポジトリを生成し、その中には完全に動作するアプリケーションも含まれていたと報告しています。さらに $50k 規模で受注した契約案件を、$297 程度の Claude API コストで完了させた事例もあり、人間の手作業を Claude に置き換えることで桁違いの生産性が出ることを示しています。3 ヶ月で「cursed」という新しいプログラミング言語を 1 人で作り上げた話も同じ系統で、長期に粘着的な反復作業が必要なタスクほど Ralph Loop の真価が出ます。これらの実績は再現性があるわけではなく、提唱者本人がプロンプト設計の達人であることが前提ですが、「人間が同じことを続ける時間を、ループに置き換える」という発想自体は誰にでも適用可能です。Anthropic が公式マーケットプレイスにこのプラグインを取り込んだのは、こうした成功例を踏まえて、開発者が安全に Ralph Loop を試せる入口を整備するためと考えられます(出典: ghuntley.com/loop)。

Claude Code に Ralph Loop を組み込む実践手順

最後に、いま手元の Claude Code に Ralph Loop を組み込むための具体手順を整理します。

1. Claude Code を最新版に更新し、/plugin marketplace を開いて claude-plugins-official が登録されているか確認します。

2. /plugin install ralph-wiggum@claude-plugins-official を実行してインストールし、/reload-plugins で有効化します。

3. 作業用 git ブランチを切り、git status がクリーンな状態であることを確認します。

4. 小さなタスクで試運転します。たとえば次のコマンドをそのままコピーして実行できます。

   /ralph-loop "./scripts/lint.sh の失敗を 0 件にせよ。完了したら <promise>COMPLETE</promise> と出力せよ" \
     --completion-promise "COMPLETE" \
     --max-iterations 10
   

5. 完了またはイテレーション上限到達後、git diff で変更内容を必ず人間がレビューし、不要な変更が混入していないか確認してからコミットします。

6. 成功体験を踏まえて段階的にタスクの粒度を上げていき、最終的に「テスト駆動で新機能を 1 つ実装する」レベルのタスクを 30〜50 反復で回せるようになれば、Ralph Loop は手放せない武器になります。

注意点として、本番リポジトリの main ブランチで直接走らせない、長時間放置する場合は事前に課金状況を確認する、の 2 点は徹底してください(出典: claude-plugins-official ralph-loop)。