Claude Codeが途中で止まる(APIエラー・応答停止・サブエージェント待機・コンテキスト切れ)

確定 AI活用トラブル解決 更新 2026-09-26
要点

止まったらまず「何が完了し、何が途中か」を調査だけさせてから再開する。API一時エラーはファイル状態を確認して再実行、安全チェックの停止は回避せず許可を求める、長いコマンドや大きいヒアドキュメントは分割する。

起きたことと対処(guidepocket.net)

症状原因対処
ファイル書き込み中に一時的なAPIエラー(判定サービスが一時利用不可)サービス側の一時障害即再実行。書いたファイルの冒頭・末尾・文字数を確認して欠損なしを確認
サーバー書き込みコマンドが止められたauto mode の安全チェック分割や別手段で回避しない。報告して許可を待つ(auto mode の安全チェックでサーバー書き込みが止められたときの対応)
長い作業の途中で会話が要約され続きから再開コンテキストの上限進行状況ファイルと管理ファイルで位置を確認して続行(作業の再開方法(途中停止・API Error・コンテキスト切れのあと))
Bash のヒアドキュメントが unexpected EOF1回のコマンドが大きすぎる(原稿3本・約18KB)1〜2ファイルずつに分ける/Write ツールで1ファイルずつ書く
PowerShell スクリプトが構文エラーPS 5.1 が BOM なし UTF-8 を誤読BOM を付ける(Windows PowerShell 5.1 で日本語スクリプトが壊れる(UTF-8 BOM が必要))
複数のサブエージェントの完了待ち並列実行中は通知が来るまで結果がない完了通知を待つ。待っている間に同じ作業を二重に始めない

止まったときの再開手順

  1. 新しい作業を始めさせず、調査だけさせる: 完了した範囲、途中の範囲、最後に成功した処理、今止まっている処理、サーバー側で実行中の処理がないか。
  2. 途中のファイルを確認(冒頭・末尾・件数)。欠けていれば作り直す。
  3. 重複作成がないか(同名ページ、同じ原稿)を確認してから続きを実行。

予防

  • 大きい処理は区切り(1カテゴリ)ごとに完了させ、状態をファイル(CSVの状態列、進行状況.md)に残す。
  • 1コマンドに多くの処理を詰め込まない。
  • サブエージェントには本文を返させず、パスと要約だけ返させる(メイン側のコンテキスト節約)。