ralph-claude-code: AIエージェントを"止める"技術——サーキットブレーカーパターンが暴走を防ぐ仕組み

ralph-claude-code: AIエージェントを"止める"技術 cover image

「Claude Code を無限ループで回したら一晩で6つのリポジトリが完成した」——そんなYCombinatorハッカソンの実験が話題になりました。これを実現しているのがralph-claude-code です。

AI エージェントの自律ループは強力ですが、「いつ止めるか」が最大の課題です。止めるタイミングを間違えると、APIコストが爆発するか、同じエラーで延々とループし続けます。ralph-claude-codeは、サーキットブレーカーパターンと終了検出アルゴリズムでこの問題を解決しています。

本記事では、既存記事では触れられていない実装の内部ロジックに焦点を当て、どうやって「止める技術」が実現されているかを解説します。

ralph-claude-codeとは

Ralphテクニックの起源

Geoffrey Huntley が提唱した手法で、最もシンプルな形は以下のBashループです：

1
while :; do cat PROMPT.md | claude-code ; done

このループは「決定論的に悪い結果を非決定論的な世界で生み出す」という思想に基づいています。つまり、失敗パターンが明確なので、チューニングで改善できるということです。

ralph-claude-codeの役割

frankbria/ralph-claude-code は、このシンプルなループに以下の機能を追加した実装です：

インテリジェント終了検出: タスク完了を自動判定
サーキットブレーカー: 無限ループを防止
レート制限管理: API使用量を制御
セッション継続性: コンテキストを保持

バージョン0.9.8時点で、276個のテストが100%パスしており、プロダクション利用に近い品質です。

「止める技術」の核心：サーキットブレーカーパターン

サーキットブレーカーの3つの状態

ralph-claude-codeのサーキットブレーカーは、マイクロサービスアーキテクチャで使われるサーキットブレーカーパターンをAIエージェントに適用しています。

状態	説明	動作
Closed（正常）	正常動作中	ループを継続
Open（回路オープン）	異常検出	ループを停止
Half-Open（半開）	回復モニタリング	段階的に再開

回路オープンのトリガー条件

サーキットブレーカーは以下の条件で回路をオープンします：

1. 進捗なしループ（3回）

1
CB_NO_PROGRESS_THRESHOLD=3

3ループ連続でファイル変更がない場合、進捗なしと判定します。

2. 同一エラーの繰り返し（5回）

1
CB_SAME_ERROR_THRESHOLD=5

5ループ連続で同じエラーメッセージが出力された場合、スタックループと判定します。

3. 出力量の激減（70%以上減少）

1
CB_OUTPUT_DECLINE_THRESHOLD=70

前回ループと比較して、出力が70%以上減少した場合、異常と判定します。これは、AIエージェントが「やることがない」状態に陥っている可能性を示します。

二段階エラーフィルタリング

サーキットブレーカーの実装で特筆すべきは、誤検知を防ぐ二段階フィルタリングです。

問題: JSONレスポンスの "is_error": false をエラーとして誤検知してしまう

解決策: 以下の二段階でフィルタリング

第一段階: JSON構造を認識し、フィールド名を除外
第二段階: 複数行にまたがるエラーメッセージをマッチング

1
2
3
4
5
6
7
8
9
# 第一段階: JSONフィールドを除外
if [[ $line =~ \"is_error\".*false ]]; then
  continue
fi

# 第二段階: マルチライン対応
if [[ $current_block =~ $error_pattern ]]; then
  error_count=$((error_count + 1))
fi

この仕組みにより、誤検知率が大幅に低下しました。

終了検出アルゴリズム

サーキットブレーカーとは別に、ralph-claude-codeは正常終了を検出する仕組みも持っています。

終了シグナルの種類

1. タスク完了の検出

@fix_plan.md 内のすべてのタスクが完了マークされている場合、終了します。

2. 連続doneシグナル（2回）

1
MAX_CONSECUTIVE_DONE_SIGNALS=2

Claude Codeが2回連続で「完了」を示すレスポンスを返した場合、終了します。

3. テスト専用ループの検出（3回）

1
MAX_CONSECUTIVE_TEST_LOOPS=3

3回連続でテストだけを実行し、機能実装がない場合、機能開発が完了したと判定します。

Claude 5時間API制限のハンドリング

Claudeには5時間あたりの使用量制限があります。ralph-claude-codeはこれを自動検出し、以下の選択肢を提示します：

60分待機: カウントダウンタイマー付きで待機
終了: 30秒後に自動終了

これにより、無駄なリトライループを防ぎます。

セッション継続性の仕組み

バージョン0.9.6以降、ralph-claude-codeはセッション継続性をサポートしています。

セッションファイルの構造

1
2
3
4
# .ralph_session
SESSION_ID="ses_abc123def456"
CREATED_AT="1704585600"  # Unix timestamp
EXPIRES_AT="1704672000"  # 24時間後

自動リセットトリガー

以下のイベントでセッションが自動リセットされます：

サーキットブレーカーオープン時: 停滞検出
手動中断（Ctrl+C）: ユーザーの明示的な停止
プロジェクト完了時: 正常終了

セッション履歴は .ralph_session_history に最大50件まで記録されます。

実運用での注意点

トークン消費量の現実

既存記事では「ものすごくToken消費が多い」と書かれていますが、YCombinatorハッカソンでの実測データが公開されています：

YCombinatorハッカソンでは、6つのリポジトリを一晩でポーティングするのに約$800を消費し、1,100以上のコミットが生成されました。Sonnetエージェント1台あたり約$10.50/時間のコストがかかるとのことです。

参考: We Put a Coding Agent in a While Loop and It Shipped 6 Repos Overnight

レート制限の設定調整

デフォルトの100コール/時は、プロジェクトによっては過剰です。調整例：

1
2
3
4
5
6
7
8
# 小規模プロジェクト向け
ralph --calls 50

# 急ぎの場合（コスト注意）
ralph --calls 150

# 予算重視の場合
ralph --calls 30

プロンプトチューニングのコツ

Geoffrey Huntleyの「看板チューニング」手法が効果的です：

最初のループ: Ralphに自由にやらせる
失敗パターンの観察: ログから問題を特定
PROMPT.mdに看板を追加: 「このエラーが出たら〜してください」
再実行: Ralphは看板を見て改善される

例：

1
2
3
4
5
6
7
# PROMPT.md

## ⚠️ 注意事項

- テストが失敗した場合、必ずエラーメッセージを読んでから修正してください
- 同じエラーを3回繰り返す場合、アプローチを変更してください
- ファイルを削除する前に、依存関係を確認してください

公式プラグインとの違い

Claude Code公式プラグインの「Ralph Wiggum」と、frank bria版のralph-claude-code は、名前は似ていますが実装が異なります。

機能	公式Plugin	frankbria版
サーキットブレーカー	❌ なし	✅ あり
二段階エラーフィルタリング	❌ なし	✅ あり
セッション継続性	❌ なし	✅ あり
テストカバレッジ	❓ 不明	✅ 276テスト100%パス
tmux統合	❌ なし	✅ あり

公式プラグインは「シンプルなループ」、frankbria版は「プロダクション品質の自律ループ」という位置づけです。

まとめ

ralph-claude-codeの「止める技術」は、以下の3つの仕組みで実現されています：

サーキットブレーカー: 進捗なし、同一エラー、出力減少を検出して停止
終了検出アルゴリズム: タスク完了、doneシグナル、テスト専用ループを判定
セッション管理: コンテキストを保持しつつ、異常時は自動リセット

これらの仕組みにより、「一晩で6リポジトリ完成」のような長時間自律実行が可能になっています。

個人的には、二段階エラーフィルタリングのアプローチが特に興味深いと思いました。JSON構造を理解してフィールド名を除外する実装は、LLM ツールの品質管理において参考になります。

ralph-claude-codeはまだv0.9.8で、v1.0に向けて開発中です。興味のある方はGitHubリポジトリをチェックしてみてください。

Fragments of verbose memory

冗長な記憶の断片 - Web技術のメモをほぼ毎日更新