frankbria/ralph-claude-code 実践ガイド

はじめに

前回の記事では Ralph の方法論を紹介し、snarktank/ralph では極めてシンプルな外部ループ実装を紹介しました。今回はもう一つのアプローチ、frankbria/ralph-claude-code を見ていきます。

snarktank/ralph の哲学が「最小限のコードで最大限のことをする」だとすれば、frankbria の哲学は「すべてをエンジニアリング化する」です——インタラクティブな設定ウィザード、リアルタイム監視ダッシュボード、サーキットブレーカー、レート制限、セッション有効期限管理。簡潔さではなく、制御性を追求しています。

どちらの実装にも優劣はなく、異なるユースケースに適しています。本記事では frankbria の完全なツールチェーンを紹介します。

インストールと設定

グローバルインストール

# リポジトリをクローン
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# グローバルインストール
./install.sh

インストール完了後、以下のグローバルコマンドが使用可能になります：

プロジェクトの初期化

既存プロジェクトの場合、インタラクティブウィザードを使用します：

cd your-project
ralph-enable

ウィザードがプロジェクトタイプ（Node.js、Python、Go など）とフレームワーク（Next.js、FastAPI など）を自動検出し、対応する設定ファイルを生成します。

新規プロジェクトの場合：

ralph-setup my-new-project

これによりプロジェクトディレクトリの作成、Git の初期化、.ralph/ 設定ディレクトリの生成が行われます。

既存要件のインポート

すでに PRD ドキュメントや要件定義がある場合：

ralph-import path/to/your-prd.md

Ralph がドキュメントを解析し、タスクリストを抽出して、構造化された fix_plan.md を生成します。

.ralph/ ディレクトリ構造

frankbria のメモリと設定は .ralph/ ディレクトリに集約されています：

.ralph/
├── PROMPT.md          # プロジェクト目標とコンテキスト
├── fix_plan.md        # タスクリスト（prd.json に相当）
├── AGENT.md           # ビルド/テストコマンド（自動管理）
├── specs/             # 詳細要件ドキュメント
│   ├── feature-a.md
│   └── feature-b.md
└── sessions/          # セッション永続化データ
    ├── current.json
    └── history/

snarktank/ralph との比較：

AGENT.md は自動管理されることに注意してください。Ralph が実行中に発見したプロジェクト規約に基づいてこのファイルを自動更新します。snarktank/ralph の progress.txt に似ていますが、より構造化されています。

コアコマンド

基本実行

# Ralph ループを起動
ralph

# リアルタイム監視付き
ralph --monitor

# tmux で起動（長時間実行におすすめ）
ralph --live

監視ダッシュボード

# 監視を単独で起動
ralph-monitor

ralph-monitor は tmux ダッシュボードを開き、以下をリアルタイム表示します：

• 現在実行中のタスク
• 完了/未完了のタスク数
• API 呼び出し回数とコスト見積もり
• サーキットブレーカーの状態
• 最近のエラーログ

よく使うパラメータ

# API 呼び出し50回制限、2時間タイムアウト
ralph --calls 50 --timeout 120

# 前回の中断箇所から再開
ralph --resume

セーフティ機構

frankbria の最大の差別化ポイントは、多層のセーフティ機構です。

サーキットブレーカー（Circuit Breaker）

サーキットブレーカーは「進捗なし」を検知すると自動的にループを停止し、無意味な API 消費を防ぎます：

連続無進捗検知：連続 N 回のイテレーションで新たなタスクが完了しない場合、サーキットブレーカーが発動します。

同一エラー検知：同じエラーメッセージが連続で発生する場合、AI が無限ループに陥っていることを示しており、サーキットブレーカーが発動します。

レート制限

デフォルトで 100 calls/hour に制限されており、予期しない API 請求額の急増を防ぎます。パラメータで調整可能です：

ralph --calls 200  # 200 calls に引き上げ

5時間 API 制限の三層検知

Anthropic API には 5 時間スライディングウィンドウの使用制限があります。frankbria には三層の検知機能が組み込まれています：

1. 事前検知：各 API 呼び出し前に残り枠を推定
2. レスポンス検知：API レスポンスの rate limit headers を解析
3. フォールバック戦略：制限に近づくと自動的に呼び出し頻度を低下

セッション有効期限管理

デフォルトのセッション有効期限は 24 時間です。期限超過後はセッションデータを自動クリーンアップし、期限切れのコンテキストが後続の実行に影響するのを防ぎます。

スマート終了検知

frankbria は単純にすべてのタスク完了後に終了するわけではありません。ダブルコンディション終了ゲートを使用しています：

終了条件 = completion_indicators >= 2 AND EXIT_SIGNAL: true

completion_indicators は AI の出力から検知された完了シグナルの数で、以下を含みます：

• 「すべてのタスクが完了」
• 「これ以上の TODO はなし」
• テストがすべてパス
• fix_plan.md のすべての項目が done とマークされている

EXIT_SIGNAL は AI が出力で明示的に宣言する終了意図です。

なぜ 2 つの条件が必要なのでしょうか？早期終了を防ぐためです。単一のシグナルは誤判定の可能性があります。例えば AI が「タスク完了」と言っても、実際には現在の story しか完了していないかもしれません。ダブルコンディションにより、複数の独立したシグナルがすべて完了を確認した場合にのみ本当に終了します。

snarktank/ralph との比較

コアの違い：エンジニアリング化の程度

どちらも外部 bash ループで新しい Claude プロセスを起動します。コアの違いはセッション管理方式（frankbria は --no-continue で新規セッションモードに切替可能）ではなく、エンジニアリング化の程度にあります：

• snarktank：極めてシンプルなスクリプト、数百行の bash、ループそのものに特化
• frankbria：完全にエンジニアリング化されたツールチェーン——監視ダッシュボード、サーキットブレーカー、レート制限、セッション有効期限管理

frankbria はデフォルトで --continue を有効にしてセッションを再利用するため、短いタスクに適しています。長いタスクの場合は --no-continue に切り替えて新規セッションモードにすることで、snarktank と同じ Context Rot 防護を得られると同時に、frankbria のエンジニアリング化された利点を保持できます。

セッション再利用を無効にする方法

frankbria では --continue を無効にする 3 つの方法があります：

# 方法1：コマンドラインパラメータ
ralph --no-continue

# 方法2：環境変数
export CLAUDE_USE_CONTINUE=false

# 方法3：.ralphrc 設定
SESSION_CONTINUITY=false

無効にすると、frankbria の動作は snarktank と同等（毎回新規セッション）になりますが、すべてのエンジニアリング化ツール（監視、サーキットブレーカー、レート制限など）は保持されます。

Context Rot の現実的なトレードオフ

セッション再利用方式の選択は、本質的に Context Rot と起動オーバーヘッドのトレードオフです：

短いタスク（< 50k tokens）：セッション再利用の方が有利です。コンテキストがまだ劣化する前であり、最初の数回のイテレーションの記憶が後続で活用できます。毎回新規セッションを作成する起動オーバーヘッドはむしろ無駄になります。

長いタスク（100k+ tokens）：新規セッションの方が信頼性が高いです。100k tokens を超えると Context Rot が明らかに加速し、蓄積されたコンテキストは資産から負債に変わります。新規セッションには起動オーバーヘッドがありますが、毎回最良の状態で開始できます。

実践的なアドバイス：

frankbria ユーザーはタスクの規模に応じて柔軟に選択できます：短いタスクにはデフォルトの --continue モード、長いタスクには --no-continue モードに切り替えます。snarktank と比較した frankbria の利点は、どちらのモードでも完全なエンジニアリング化ツールチェーンが保持されることです。

まとめ

frankbria/ralph-claude-code は Ralph 方法論のエンジニアリング化された実装路線を代表しています。snarktank の簡潔さを一部犠牲にして、より充実した監視、セーフティ、設定機能を実現しています。

どちらの実装を選ぶかは具体的なニーズ次第です——「より正しい」答えはなく、「より適した」選択があるだけです。

関連記事：

• Ralph Wiggum 詳細解説 — コア原理と方法論
• snarktank/ralph 実践ガイド — 極めてシンプルな外部ループ実装
• GSD 詳細解説 — Ralph をベースに構築された完全なコンテキストエンジニアリングシステム
• Claude システムアーキテクチャ完全解説 — Hooks、Subagent などのコンポーネントの全体アーキテクチャを理解する