AI コーディング

Claude Code のタスクが停止したとき：リトライを止めて状態を復旧する判断

停止した Claude Code タスクを復旧する実践手順。障害を分類し、ループを中断し、状態を記録して、範囲を絞った検証から再開します。

BT

BetterToken

編集チーム
2 分で読めます

回数を決めない再試行は、Claude Code の利用時にトークンの無駄遣い、コンテキストの劣化、壊れたコード変更を招く大きな原因です。同じテストに繰り返し失敗したり、環境変数が不足したり、同じファイルを循環して編集したりしている場合、新しい外部シグナルなしで再試行しても原因は解決しません。セッションを行き止まりへ深く押し込むだけです。

適切な方針は、早い段階でループを止め、API とコードベースの両面から障害を分類し、実際のリポジトリ状態を記録したうえで、決定的な検証手順からタスクを再開することです。

1. 障害を分類する：リトライが役に立たないとき

すべてのエラーがコマンドの再実行で解消するわけではありません。明確な診断がないと、一時的な API の制限とエージェントの論理ループを取り違えやすくなります。

障害の種類症状リトライの挙動推奨する対応
一時的なネットワーク障害 / 429一時的な API タイムアウトまたはレート制限指数バックオフなら有効（最大 3 回）待機して外部 API 呼び出しだけを再実行する
論理的な行き止まりエージェントが同じ 2 ファイルを循環して変更する無効：誤った前提を繰り返す`Ctrl+C` でセッションを止め、Git の diff を確認する
権限 / 環境エラー`Permission denied`、`.env` の不足無効：環境は自動では変わらない権限またはローカル設定を明示的に修正する
アーキテクチャの不整合不正なスキーマのため統合テストが失敗する無効：計画の見直しが必要変更を戻し、タスクの境界を明確にする

原因を推測してトークンを使い続けないために、外部 API の問題とコードの不具合を分けて扱います。BetterToken の Claude Code ワークフローでは、Dashboard で HTTP ステータス、モデル、応答時間、入力・出力・キャッシュトークンの正確な消費量を確認できます。ゲートウェイタイムアウトや 429 なら、回数を制限した再試行には根拠があります。一方、API が継続して 200 OK を返し、エージェントだけが循環編集しているなら、直ちにセッションを終了してください。

2. 優先順位を付けた復旧プロトコル

エージェントが 2〜3 回連続で成果のない試行を行ったら、次の順序で進めます。

```mermaid
graph TD
A[エージェントがエラーループに入る] --> B[手順 1: Ctrl+C ですぐ停止]
B --> C[手順 2: Git の状態と diff を監査]
C --> D[手順 3: Recovery Card を保存]
D --> E[手順 4: 検証付きのクリーンなセッションを開始]
```

手順：

  1. 手順 1：セッションを終了する。 `Ctrl+C` で実行を中断します。長い言い訳や不要な出力の生成に、これ以上コンテキストを消費させないでください。
  2. 手順 2：状態を確認して整理する。 `git status --short` で変更ファイルを確認します。エージェントが壊れたコードを作った場合は、影響したファイルだけを戻します：`git checkout -- <file>`。
  3. 手順 3：根本原因を分類する。 Dashboard の API 指標とエージェントの実行ログを比較し、ネットワーク障害とエージェントの論理エラーを切り分けます。
  4. 手順 4：構造化した Recovery Card を保存する。

3. 構造化された Recovery Card

新しい復旧セッションを開始する前に、タスクの正確な状態を記録します。

```markdown

Recovery Card: インポートサービスの障害

  • 元の目標: `auth/service.ts` にメールアドレス検証を追加する。
  • 実際の進捗: 正規表現は追加したが、ユニットテスト `auth_test.go` が失敗した。
  • 根本原因: エージェントが公開インターフェースではなく private メソッドをモックしようとした。
  • Git の状態: ブランチは `fix/auth-email`、`auth/service.ts` の有効な diff は保持する。
  • クリーンなセッションでの次の作業: 公開インターフェース `AuthClient` を使ってユニットテストをリファクタリングする。
    ```

[!IMPORTANT]
シークレットを残さない： Recovery Card に API キー、アクセストークン、未加工のメモリダンプを記載してはいけません。エンドポイントの設定とキー管理は、BetterToken の Claude Code ドキュメントで確認してください。

4. 可逆的な復旧と検証

安全に実行を再開するには、次のようにします。

  1. クリーンなコンテキストウィンドウで、新しい Claude Code セッションを開始します。
  2. エージェントにはタスクの目標と Recovery Card の「次の作業」だけを渡します。
  3. 対象を絞ったチェックを要求します：`npm test -- tests/auth.test.ts`。
  4. 対象テストが通ること（`Passed`）を確認してから、最終 diff を `git diff --check` で確認します。

このプロトコルにより、制御不能なエージェントループを管理可能なチェックポイントへ変え、コードベースとトークン予算を守れます。

支払いと残高のチャージ

API 利用の支払いとチャージは、自分の BetterToken アカウントで管理します。BetterToken は従量課金のモデル API アクセスサービスであり、支払い済みでチャージした残高は毎月自動的には失効しません。利用可能な支払い方法、最低金額、手数料、為替レート、処理時間は変わることがあるため、支払い時点のアカウント表示を確認してください。

料金とコスト管理

モデルの提供状況と個別の料金は動的な情報です。コストを判断する前に、古い記事の数値を使い回さず、BetterToken の料金ページで確認してください。テスト呼び出しの後は、Dashboard でモデル、ステータス、入力・出力・キャッシュトークンと対応する消費量を照合できます。

LLM ワークフローを最適化しませんか？

単一 API でモデルを接続し、キーと AI コストを管理できます。