Latency Triage

Claude Code 応答遅延・中断のトリアージ

このスキルの目的

ユーザーから「Claude Code が遅い・固まった・中断された」と報告されたとき、サーバー障害と即断せず、決定論的な測定で原因を切り分けて対処を提案する。

既知の根本原因(2026-07-12 の実測分析)

過去の全セッション分析で確定した事実。診断の事前確率として使う:

1. 「5〜10分応答なし」の最有力原因は拡張思考(extended thinking)の長時間化。

alwaysThinkingEnabled: true × effortLevel: xhigh × 巨大コンテキスト(peak 300k+)の組合せで、opus 系は1回8〜10分の思考ブロックを実測(例: セッション 3e3c06d8 で6回)。プロンプト送信→初回応答の gap 自体は 5分超がほぼゼロで、API は遅くない。

1. サーバー障害はまれ。transcript 上の Overloaded / 529 / 接続断は過去実績ゼロ。isApiErrorMessage の大半は「You've hit your limit」= 利用上限到達で、障害ではない。
2. 「ツール出力が壊れて中断」は長考後の生成破損(tool call could not be parsed / AskUserQuestion InputValidationError)。同じ思考設定の問題に帰着する。
3. Bash の Exit 143 は既定2分タイムアウトによる打ち切り。API とは無関係の別要因。
4. 推奨構成は adaptive thinking(alwaysThinkingEnabled: false)× effortLevel: xhigh。公式プロンプティングガイド(opus 4.8 / sonnet 5)の推奨と一致する。xhigh を下げる前に、まず thinking の発動頻度を疑う。

effort と alwaysThinkingEnabled は別の軸: effort = 思考・作業の深さのダイヤル(output_config.effort)、alwaysThinking = 思考の発動頻度スイッチ(毎ターン強制 or adaptive)。

診断フロー

1. 設定確認(最初にやる)

grep -nE '"alwaysThinkingEnabled"|"effortLevel"|"model"' ~/.claude/settings.json

• alwaysThinkingEnabled: true × effortLevel: xhigh|max なら、それが第一容疑。
• ~/.claude/settings.json は dotfiles 実体への symlink(このマシンでは ~/dotfiles/home/.claude/settings.linux.json)。編集提案は実体パスで示す。

2. 定量測定(同梱スクリプト)

生の JSONL を Read/Grep で漁らない。同梱の自己完結スクリプトで測る(依存は Python stdlib のみ、python3 直実行可):

python3 /scripts/latency_probe.py --since 

出力の読み方:

| 指標 | 意味 | 遅延の解釈 | |---|---|---| | turn_duration 分布 | ターン総時間(離席・承認待ちを含む) | 大きくても単独では遅延の証拠にならない | | 実プロンプト→初回応答 gap | 承認待ちを挟まない応答開始まで | ここが5分超なら API/思考が本当に遅い | | thinking 直前 gap | 思考ブロック1回の所要時間の近似 | 5分超が opus に偏っていれば thinking 設定起因 | | isApiErrorMessage | API エラーレコード | 「limit」なら上限到達。500/529 なら障害 |

3. 個別セッションの深掘り

gap が大きいセッションを特定したら、タイムラインで「どこで時間が消えたか」を見る:

python3 /scripts/latency_probe.py --session 

asst[think] 単体の大 gap = 思考時間。queue-operation / away_summary 前後の gap = 人間側の離席で、遅延ではない。

4. 判定と対処

| 症状 | 原因 | 対処 | |---|---|---| | thinking 直前 gap が5分超・opus に集中 | 常時思考 × 高 effort × 巨大コンテキスト | alwaysThinkingEnabled: false(adaptive)を確認・提案。effort は下げずに済むことが多い | | adaptive でも特定セッションだけ長考 | コンテキスト肥大(peak 250k超) | 中間結果のファイル退避・トピック単位の新セッションを提案 | | Bash Exit 143 で作業中断 | 既定2分タイムアウト | run_in_background: true か timeout 明示延長 | | ツール入力の parse エラー | 長考後の生成破損 | 上記 thinking 対処と同じ。単発なら continue で復帰 | | isApiErrorMessage に limit 表示 | 利用上限到達 | リセット時刻まで待つ/プラン確認。障害ではないと報告 | | 500/529 が実在 | 本物の API 障害 | status.anthropic.com を確認し、リトライ待ち |

セッション実行中の一時変更は /effort で可能(ユーザーに案内する。モデル切替 /model と effort は連動しない)。

制約

• settings.json・CLAUDE.md の変更は提案止まり。ユーザーの承認なしに書き換えない。
• 時刻の報告は JST。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yasunori0418
• Source: yasunori0418/skills
• License: MIT

Install and usage instructions live in the source repository linked above.