Claude Codeが途中で止まる(APIエラー・応答停止・サブエージェント待機・コンテキスト切れ)
要点
止まったらまず「何が完了し、何が途中か」を調査だけさせてから再開する。API一時エラーはファイル状態を確認して再実行、安全チェックの停止は回避せず許可を求める、長いコマンドや大きいヒアドキュメントは分割する。
起きたことと対処(guidepocket.net)
| 症状 | 原因 | 対処 |
|---|---|---|
| ファイル書き込み中に一時的なAPIエラー(判定サービスが一時利用不可) | サービス側の一時障害 | 即再実行。書いたファイルの冒頭・末尾・文字数を確認して欠損なしを確認 |
| サーバー書き込みコマンドが止められた | auto mode の安全チェック | 分割や別手段で回避しない。報告して許可を待つ(auto mode の安全チェックでサーバー書き込みが止められたときの対応) |
| 長い作業の途中で会話が要約され続きから再開 | コンテキストの上限 | 進行状況ファイルと管理ファイルで位置を確認して続行(作業の再開方法(途中停止・API Error・コンテキスト切れのあと)) |
Bash のヒアドキュメントが unexpected EOF | 1回のコマンドが大きすぎる(原稿3本・約18KB) | 1〜2ファイルずつに分ける/Write ツールで1ファイルずつ書く |
| PowerShell スクリプトが構文エラー | PS 5.1 が BOM なし UTF-8 を誤読 | BOM を付ける(Windows PowerShell 5.1 で日本語スクリプトが壊れる(UTF-8 BOM が必要)) |
| 複数のサブエージェントの完了待ち | 並列実行中は通知が来るまで結果がない | 完了通知を待つ。待っている間に同じ作業を二重に始めない |
止まったときの再開手順
- 新しい作業を始めさせず、調査だけさせる: 完了した範囲、途中の範囲、最後に成功した処理、今止まっている処理、サーバー側で実行中の処理がないか。
- 途中のファイルを確認(冒頭・末尾・件数)。欠けていれば作り直す。
- 重複作成がないか(同名ページ、同じ原稿)を確認してから続きを実行。
予防
- 大きい処理は区切り(1カテゴリ)ごとに完了させ、状態をファイル(CSVの状態列、進行状況.md)に残す。
- 1コマンドに多くの処理を詰め込まない。
- サブエージェントには本文を返させず、パスと要約だけ返させる(メイン側のコンテキスト節約)。