Ralph で Claude Code を自律ループさせる｜仕組み・使い方・向く作業

Claude Code は、1 回の依頼で終わる作業なら最後まで進めてくれます。ただ、テストが全部通るまで直し続ける、タスク一覧を上から順に片付けるといった長い作業では、途中で「ここまでで一区切りです」と止まり、人が「続けて」と打つ必要があります。

Ralph は、この「続けて」を自動にする手法です。同じ指示を何度も Claude Code に渡し、作業が終わるまで回し続けます。

この記事でわかること

• Ralph という手法の考え方
• 2 つの実装（ralph-claude-code と公式プラグイン ralph-loop）の違い
• ralph-claude-code のファイル構成、終了条件、安全装置
• 導入と実行の手順
• 向く作業と向かない作業、運用するときの注意点

Ralph とは：同じ指示を繰り返し渡すループ

Ralph は、開発者の Geoffrey Huntley さんが広めた手法です。名前はアニメ『ザ・シンプソンズ』の登場人物ラルフ・ウィガムから取られていて、「Ralph Wiggum 手法」とも呼ばれます。

考え方はとても単純で、最小の形は次の 1 行のシェルループです。

while :; do cat PROMPT.md | claude ; done

PROMPT.md に書いた同じ指示を、Claude Code に何度も渡すだけです。それでも作業が前に進むのは、前の回の成果がファイルと git の履歴に残るからです。毎回の Claude Code は、前の回が書いたコードやテスト結果を読み、残っている作業に取りかかります。

一方で、この 1 行のままでは止まりません。終わったかどうかを判定し、空回りしたら止める仕組みが要ります。そこを補ったのが、次の 2 つの実装です。

2 つの実装

以下では、設定項目が多く仕組みを追いやすい ralph-claude-code を中心に説明し、最後に公式プラグインの使い方を紹介します。記載は 2026 年 10 月時点の ralph-claude-code v0.11.5 と、公式プラグインの README に基づきます。

ralph-claude-code の仕組み

ファイル構成

プロジェクトを Ralph 用に設定すると、.ralph/ ディレクトリに次のファイルが作られます。

人が主に手を入れるのは PROMPT.md と fix_plan.md です。何を作るかと、どの順に片付けるかを書いておけば、あとはループが進めます。

1 回のループで行うこと

1. PROMPT.md を読み込む
2. Claude Code を実行し、fix_plan.md の残りのタスクに取りかからせる
3. タスク一覧とログを更新する
4. 終了条件を満たしたかを確かめる
5. 満たしていなければ 1 に戻る

前の回のセッションは既定で引き継がれます（24 時間で失効）。毎回まっさらな状態から始めたいときは --no-continue を付けます。

終了の判定

「終わりました」と書いたからといって、すぐには止まりません。次の 2 つがそろったときに初めて終了します。

• Claude Code の出力に、完了を示す表現が 2 回以上出ている
• Claude Code が明示的に EXIT_SIGNAL: true を返している

完了らしい表現が多くても、EXIT_SIGNAL が true でなければループは続きます。ほかにも、fix_plan.md のタスクがすべて終わったとき（「Optional」「Future」などの見出しの下にある任意のタスクは数えない）や、テストだけを繰り返す回が続いたときにも止まります。

空回りを防ぐ安全装置

放置して回すため、暴走を止める仕組みが 2 つ用意されています。

• 呼び出し回数の上限：既定は 1 時間に 100 回（MAX_CALLS_PER_HOUR）です。トークン数の上限（MAX_TOKENS_PER_HOUR）も設定できますが、既定では無効です
• サーキットブレーカー：電気のブレーカーと同じく、異常が続いたらループを遮断します。既定では次のどれかで作動し、30 分待ってから少しずつ再開を試みます
  • ファイルが 1 つも変わらない回が 3 回続いた
  • 同じエラーが 5 回続いた
  • 出力の量が 70% 以上減った

導入と実行の手順

前提として、Bash 4.0 以上、Claude Code の CLI、jq、git が必要です。監視画面を使うなら tmux も入れておきます。

# 1. Ralph 本体を入れる（システムに 1 回だけ）
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

# 2. 既存のプロジェクトで Ralph を有効にする（対話形式で設定）
cd ~/work/my-project
ralph-enable

# 3. 監視画面付きでループを始める
ralph --monitor

要件をまとめた Markdown がすでにあるなら、ralph-enable の代わりに ralph-import 要件.md プロジェクト名 で Ralph 用のファイルに変換できます。

初回は --dry-run で、実際に Claude Code を呼ばずに流れだけを確かめておくと安心です。1 回あたりの実行時間は --timeout（分単位、既定 15 分）で調整できます。

Claude Code がコマンドの実行権限を拒否されると、Ralph は止まります。そのときは .ralphrc の ALLOWED_TOOLS に必要なコマンドを追加し、ralph --reset-session でやり直します。

公式プラグイン ralph-loop の使い方

ループの仕組みだけを手軽に使いたいなら、Anthropic の公式プラグインがあります。Claude Code の中で /plugin を開き、公式マーケットプレイスから ralph-loop をインストールします。

/ralph-loop "認証 API のテストをすべて通す。全件パスしたら <promise>DONE</promise> と出力する" --max-iterations 20 --completion-promise "DONE"

• --completion-promise：Claude Code の出力のうち <promise> タグで囲まれた部分がこの文字列と一致したら、完了とみなします。完全一致で判定するため、「成功」と「行き詰まり」のように複数の終わり方を区別することはできません
• --max-iterations：繰り返しの上限です。既定は無制限なので、必ず指定します。README でも、これを主な安全装置にするよう勧めています
• 途中で止めるときは /cancel-ralph を実行します

向く作業・向かない作業

公式プラグインの README は、向く作業と向かない作業を次のように整理しています。

ポイントは、ループの中に「できたかどうか」を機械的に判定できる手段があるかです。判定の手段がないと、Claude Code は自分で「できた」と判断して進めるしかなく、ずれたまま回り続けます。

運用するときの注意点

止まる条件を先に決める

ループを始める前に、「何ができたら終わりか」と「どこまで回したら諦めるか」を決めておきます。完了条件はテストや lint のように自動で確かめられる形で書き、PROMPT.md や /ralph-loop の指示に入れます。行き詰まったときにどうするか（作業を止めて状況を書き残す、など）も書いておくと、上限まで空回りするのを防げます。

コストを見積もる

ループは終わるまで Claude Code を呼び続けます。従量課金の API キーで動かすなら、呼び出し回数やトークン数の上限を、払ってよい金額から逆算して設定します。サブスクリプションで使う場合も、利用上限に達すると止まります（ralph-claude-code は 5 時間の利用上限に達したことを検知すると、待つか終了するかを尋ねます）。

権限を絞り、サンドボックスで動かす

人が見ていない間にコマンドが実行されるので、許可するツールは作業に必要なものだけに絞ります。ralph-claude-code には Docker や E2B のサンドボックスで実行するオプション（--sandbox docker など）があり、手元の環境を壊すおそれを減らせます。本番環境の認証情報には触れさせないようにします。

終わった後に人がレビューする

ループが完了しても、それは決めた条件を満たしたというだけです。テストが通っていても、設計の筋が悪い、不要な変更が混ざっているといったことは起こりえます。差分を人が読んでからマージします。

まとめ

• Ralph は、同じ指示を Claude Code に繰り返し渡して作業を続けさせる手法で、進み具合はファイルと git の履歴に残る
• ralph-claude-code は外部の bash ループで動き、終了の判定、呼び出し回数の上限、サーキットブレーカーを備える
• 公式プラグイン ralph-loop は Stop フックでセッション内をループさせ、完了の文字列か回数の上限で止まる
• テストで成否を判定できる作業に向き、設計判断が要る作業や本番の障害調査には向かない
• 止まる条件、コストの上限、権限とサンドボックス、終わった後のレビューを、始める前に決めておく

参考

• frankbria/ralph-claude-code（GitHub）
• ralph-loop プラグインの README（anthropics/claude-plugins-official）