circuit-breaker について
circuit-breakerは、自律開発ループ向けの安全スキルです。停滞、エラーの反復、API上限、保護対象ファイルを監視し、しきい値に達すると停止して復旧手順を示します。
主な機能
- 01ループの停滞とエラー反復の検出
- 02API呼び出しの追跡と制限
- 03設定ファイルと計画ファイルの保護
- 04クールダウン後に一度だけ試行
- 05反復状況と進捗指標の記録
活用シーン
- 01進展しない自律ループの停止
- 02失敗の反復によるリソース消費の防止
- 03破壊的コマンド前のファイル確認
- 04定めた復旧手順での作業再開
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/circuit-breakerを入力して読み込まれたか確認します。
詳細
概要
サーキットブレーカーのスキルは、自律開発中の無限ループ、リソースの枯渇、意図しない破壊を防ぐ安全機構です。これはループレベルで動作し、タスクレベルで動作する resilient-execution を補完します。サーキットブレーカーによる保護がなければ、自律ループは進展のない問題に何時間も費やしたり、API の制限を使い果たしたり、設定ファイルを誤って破壊したりするおそれがあります。このスキルは、自律的な操作の生産性と安全性を保つための厳格な境界を設けます。
開始時に次のようにアナウンスします：「サーキットブレーカーが有効です — 停滞、レート制限、ファイル保護を監視しています。」
フェーズ 1：サーキット状態の確認
各ループの反復の前に、現在のサーキット状態を確認します。
+-----------+ threshold +-----------+ cooldown +------------+
| CLOSED |----exceeded----->| OPEN |----elapsed------>| HALF-OPEN |
| (normal) | | (halted) | | (probe) |
+-----------+ +-----------+ +-----+------+
^ |
| success |
+--------------------------------------------------------------+
| failure |
| +-----------+ |
+--------------------+ OPEN |<----------------------------+
+-----------+
| 状態 | 意味 | アクション |
|---|---|---|
| CLOSED | 通常動作 | 反復を実行し、すべてのしきい値を監視します |
| OPEN | しきい値超過により停止中 | 状態を報告し、クールダウンを待つか、エスカレーションします |
| HALF-OPEN | クールダウン後のプローブ中 | 反復を 1 回だけ許可します。成功した場合は閉じます。失敗した場合は再度開きます。 |
STOP：ループの反復を実行する前に、必ずサーキット状態を確認してください。サーキットが OPEN の場合は実行しないでください。
フェーズ 2：停滞の検出
自律動作中、以下のしきい値を継続的に監視します。
| 条件 | しきい値 | 検出方法 | アクション |
|---|---|---|---|
| 進展なし | 意味のある変更がない状態が 3 ループ連続 | 各ループで変更されたファイルと完了したタスクを追跡します | サーキットを OPEN にします |
| 同一のエラー | 同じエラーが発生する状態が 5 ループ連続 | 反復間でエラーメッセージを比較します | サーキットを OPEN にします |
| 出力の減少 | 反復をまたいで出力量が 70% 減少 | 直近 3 回の反復の出力行数を比較します | サーキットを OPEN にします |
| 権限拒否 | ツールの権限エラーが 3 回連続 | 権限エラーを追跡します | サーキットを OPEN にします |
| テスト修正ループ | 作業の 80% 超がテスト修正のみに費やされている | 反復ごとに作業の種類を追跡します | サーキットを OPEN にし、根本原因を調査します |
| 循環するアプローチ | 同じ 2～3 個のアプローチが解決しないまま交互に繰り返される | アプローチの履歴を追跡します | サーキットを OPEN にします |
停滞スコアリング
各反復で、進捗スコアを計算します。
| 指標 | スコア |
|---|---|
| 以前は失敗していたテストが新たに成功 | +3 |
| タスクを完了としてマーク | +5 |
| 意味のある変更を加えてファイルを修正 | +1 |
| ビルド／リントエラーを解決 | +2 |
| 前回の反復と同じエラー | -2 |
| ファイルの変更なし | -3 |
| 以前の変更を取り消した | -1 |
しきい値： 3 回の反復における累積スコアが負の場合、サーキットを OPEN にします。
STOP：いずれかのしきい値を超えた場合、直ちにサーキットを OPEN にしてください。「もう一度だけ」試してはいけません。
フェーズ 3：復旧プロトコル
サーキットが開いた場合、次の復旧手順に従います。
クールダウン期間
- デフォルト： 再試行まで 30 分
- 目的： 同じ失敗状態を短時間に繰り返すのを防ぎます
- クールダウン後： サーキットは HALF-OPEN 状態になります
HALF-OPEN の動作
- 実行を許可する反復は、正確に 1 回だけです
- 成功した場合（進捗スコアが正）：サーキットを閉じ、通常動作を再開します
- 失敗した場合（同じ停滞パターン）：サーキットを再度開き、クールダウン時間を 2 倍にします
停滞からの復旧戦略決定表
| 停滞の種類 | 戦略 1 | 戦略 2 | 戦略 3 | 戦略 4 |
|---|---|---|---|---|
| 進捗なし（同じタスクで行き詰まっている） | 新たな分析に基づいて計画を再生成する | 行き詰まったタスクを 3 つ以上のサブタスクに分割する | 次のタスクに進み、後で戻る | ユーザーにエスカレーションする |
| 同一のエラー（同じエラーが繰り返し発生する） | アプローチを完全に変更する | エラーが環境に起因するか確認する | 既知の問題や回避策を検索する | エラーログを添えてエスカレーションする |
| テスト修正ループ（テストが繰り返し失敗する） | テストの前提を見直す | 実装方針に問題がないか確認する | 実装範囲を縮小する | テスト分析を添えてエスカレーションする |
| 循環的なアプローチ（同じ修正を交互に繰り返す） | いったん立ち止まり、根本原因を再分析する | まだ試していないアプローチを試す | 動作する最小限のバージョンまで範囲を縮小する | アプローチの履歴を添えてエスカレーションする |
停止：復旧後の次の 3 回の反復を注意深く監視してください。停滞が再発した場合は、ただちにエスカレーションしてください。
フェーズ 4：レート制限
API の使用制限を追跡し、適用します。
| パラメーター | デフォルト | 目的 |
|---|---|---|
| MAX_CALLS_PER_HOUR | 100 | API の過剰使用を防止します |
| リセット間隔 | 1 時間（ローリング方式） | カウンターを自動的にリセットします |
| カウントダウン表示 | 有効 | 制限に達するまでの残り呼び出し回数を表示します |
レート制限の動作
- ローリング方式の 1 時間あたりの API 呼び出し回数を追跡します
- 制限の 80% に達した時点で警告を表示し、残りの呼び出しを優先します
- 制限の 100% に達した時点で実行を一時停止し、リセットまでのカウントダウンを表示します
- 制限を超過することはありません。リセット間隔が経過するまで待機します
3 層のタイムアウト検出
長時間実行される操作（特に制限時間が長い API 呼び出し）の場合：
| 層 | 検出方法 | フォールバック |
|---|---|---|
| 1. タイムアウトガード | 終了コード 124 またはタイムアウトシグナル | 部分的な出力を取得し、完了した内容を記録します |
| 2. JSON 検証 | レスポンスの構造を解析します | 生のレスポンスからテキストの抽出を試みます |
| 3. テキストフォールバック | 生の出力を取得します | すべてを記録し、人によるレビューのために報告します |
フェーズ 5：ファイル保護
自律的な操作中に設定ファイルを削除してはなりません。これは絶対に譲れない条件です。保護対象パス
| パス | 種類 | 保護する理由 |
|---|---|---|
.ralph/ | ディレクトリ | ループの状態と設定 |
.ralphrc | ファイル | Ralph の設定 |
IMPLEMENTATION_PLAN.md | ファイル | 現在の計画 — ループの信頼できる唯一の情報源 |
AGENTS.md | ファイル | エージェントの定義 |
specs/ | ディレクトリ | 仕様 — 機能の信頼できる唯一の情報源 |
.claude/ | ディレクトリ | Claude Code の設定 |
CLAUDE.md | ファイル | エージェントの操作マニュアル |
memory/ | ディレクトリ | セッションをまたいで保持される学習内容 |
保護の仕組み
| 仕組み | 動作方法 | 実行されるタイミング |
|---|---|---|
| 許可リストの適用 | 許可されたツールのみが保護対象ファイルを変更できます | 保護対象パスへのファイル書き込みの前 |
| 整合性検証 | 各反復後に保護対象ファイルの存在を確認します | すべてのループ反復の終了時 |
| 操作前チェック | 破壊的な操作の前に保護対象ファイルを確認します | rm、git clean、git checkout . の実行前 |
| コマンド制限 | 保護対象パスに対する git clean、git rm、設定ディレクトリに対する rm -rf をブロックします | コマンドが保護対象パスを指定したとき |
破壊的な操作の前のチェックリスト
rm、git clean、または git checkout . を実行する前に：
- 影響を受けるすべてのファイルを一覧表示します
- 各ファイルを保護対象パスの一覧と照合します
- 保護対象ファイルが 1 つでも影響を受ける場合：中止して報告します
- 安全な場合：注意して続行します
- 操作後：すべての保護対象ファイルが引き続き存在することを確認します
停止：操作後に保護対象ファイルが見つからない場合は、ただちに停止して復元してください。
フェーズ 6：監視とメトリクス
ループの各反復で、以下のメトリクスを追跡します。
| メトリクス | 目的 | アラートのしきい値 |
|---|---|---|
| ループ回数 | 実行した反復の合計 | 1 つのタスクで >20 |
| 完了したタスク | 進捗の測定 | 3 回以上の反復で 0 |
| 変更したファイル | 変更のペース | 3 回以上の反復で 0 |
| テスト合格率 | 品質の傾向 | 3 回以上の反復で低下 |
| エラー頻度 | 停滞の早期警告 | 3 回以上の反復で増加 |
| 出力量 | 生産性の傾向 | 70% の低下 |
| 残りの API 呼び出し回数 | レート制限への接近度 | 残り <20% |
| 進捗スコア | 全体的な健全性 | 3 回の反復で負の値 |
各反復のステータスログ
## Iteration [N] — [timestamp]
- Circuit state: CLOSED / HALF-OPEN
- Tasks completed: [N]
- Files modified: [list]
- Tests: [X passed, Y failed, Z skipped]
- Errors encountered: [list]
- Progress score: [+/- N]
- API calls remaining: [N]
- Stagnation risk: LOW / MEDIUM / HIGH
アンチパターン／よくある間違い
| やってはいけないこと | 失敗する理由 | 代わりにすること |
|---|---|---|
| 停滞の兆候を無視する | 解決できない問題に何時間も費やすことになります | しきい値を超えたらサーキットを開きます |
| 開いたサーキットを手動で上書きする | 安全機構を迂回します | 復旧手順に正しく従います |
| ファイル保護の確認を省略する | 設定の削除によりプロジェクト全体が頓挫します | 操作後は必ず保護対象のファイルを確認します |
| クールダウンをゼロに設定する | 同じ失敗をすばやく繰り返すことになります | 最低 30 分のクールダウンを守ります |
| テスト修正だけの反復を進捗として数える | 本当の問題（アプローチの欠陥）を覆い隠します | テスト修正に >80% の労力を費やしている場合は、停滞として記録します |
| 保護対象のファイルを削除して作り直す | 設定の状態が失われます | 保護対象のファイルは決して削除せず、更新のみ行います |
| レート制限の警告を無視する | 操作の途中でハードリミットに達します | 上限の 80% に達したら優先的に対処します |
| 事前確認なしで破壊的なコマンドを実行する | 保護対象のファイルを削除する可能性があります | 影響を受けるファイルを必ず事前に確認します |
正当化を防ぐガード
| 考え | 現実 |
|---|---|
| 「あと 1 回試せば直る」 | 3 回前にもそう言っていました。サーキットを開きましょう。 |
| 「エラーはほぼ修正できている」 | 5 回の反復で「ほぼ」なら、アプローチが間違っています。 |
| 「ここでは止められない。もう少しで終わる」 | サンクコストの誤謬です。サーキットを開いて、見直しましょう。 |
| 「クールダウンが長すぎる」 | クールダウンによって、同じ失敗にさらに時間を費やさずに済みます。 |
| 「これらの設定ファイルは重要ではない」 | 保護されているのには理由があります。削除しないでください。 |
| 「レート制限には達しない」 | 追跡しましょう。推測してはいけません。 |
| 「これは別のエラーだ」 | 本当に別のエラーなのか、それとも同じ根本原因が異なる形で現れているのか確認しましょう。 |
開いたサーキットを上書きしてはいけません。復旧手順に従ってください。
統合ポイント
| スキル | 関係 |
|---|---|
resilient-execution | タスクレベルの再試行（3 回）。サーキットブレーカーは、個々のタスク内で resilient-execution の再試行を使い切った後に作動します。 |
autonomous-loop | サーキットブレーカーがループを監視します。ループレベルの停滞を検知すると、サーキットを開きます。 |
ralph-status | ステータスブロックが停滞検知用のメトリクスを提供します。 |
verification-before-completion | サーキットブレーカーは、ループを終了する前に検証が通ることを確認します。 |
self-learning | 停滞パターンをメモリに保存し、今後の回避に役立てます。 |
auto-improvement | サーキットブレーカーのイベントを改善メトリクスに反映します。 |
適用範囲の明確化
| 適用範囲 | スキル | 動作 |
|---|---|---|
| タスクレベル | resilient-execution | 1 つの失敗したタスクに対して 3 つのアプローチを試します |
| ループレベル | circuit-breaker | パターンからシステム全体の障害が示唆された場合、ループ全体を停止します |
サーキットブレーカーは、個々のタスク内で resilient-execution が再試行を使い切った後に作動します。各タスクが 3 回再試行しても失敗し続ける場合、サーキットブレーカーがそのパターンを検知します。
プロセスの概要
- 各ループの反復前： サーキットの状態（CLOSED/HALF-OPEN/OPEN）を確認します
- OPEN の場合： 状態を報告し、クールダウンを待つか、エスカレーションします
- HALF-OPEN の場合： 1 回のプローブ反復を許可し、結果を評価します
- CLOSED の場合： 通常どおり実行し、すべてのしきい値を監視します
- 各反復の後： メトリクスを更新し、進捗スコアを算出して、しきい値を評価します
- しきい値を超えた場合： サーキットを開き、理由を報告して、クールダウンを開始します
- クールダウンの後： HALF-OPEN に移行し、1 回のプローブを許可します
- プローブの後： 成功した場合は閉じ、失敗した場合はクールダウン時間を 2 倍にして再度開きます
スキルの種類
RIGID — しきい値と保護ルールを厳密に守る必要があります。サーキットブレーカーの条件を緩和してはいけません。開いているサーキットを上書きしてはいけません。ファイル保護チェックを省略してはいけません。停滞の兆候を無視してはいけません。
コメント
Markdown 対応