結論：対象セッションで記録し、時刻とIDで照合する
Claude Codeの一時的な不具合を調べるときは、まず症状と発生時刻を控え、対象セッションだけでdebug loggingを有効にしてから再現します。ログはセッションIDと時刻を見て選び、エラーの直前・直後を必要な範囲に絞って確認してください。MCPの接続状況を調べるとき、バックグラウンド実行の出力を調べるとき、インストールや設定を診断するときでは見る記録が異なります。
ログには環境によってローカルパスやhook・serverの出力などが含まれる可能性があります。取得したログをそのまま外部共有せず、共有先のルールを確認してから必要部分だけを扱います。
最初に、見たいログの種類を決める
まず、現在の対話セッション、MCP、background session、supervisor、インストール・設定のどれを調べるのか選びます。目的と違うコマンドを使うと、別の出力を原因と取り違えることがあります。
| 確認したいこと | 主な方法 | 注意点 |
|---|---|---|
| 現在の対話セッションの問題 | claude --debugで起動、またはセッション中に/debug [issue] | 対象のセッションと再現時刻を照合する |
| MCP serverの初期化・応答 | claude --debug=mcp | serverのstderrなど必要な箇所に絞る |
| background sessionの出力 | claude logs <id> | 通常のセッションdebugログとは別の出力 |
| background session supervisor | claude daemon logs | 追尾を止めるときはCtrl+Cを使う |
| インストールや設定ファイル | claude doctor | セッションログを読む機能ではなく、読み取り専用診断 |
claude logsはbackground sessionの出力、claude daemon logsはsupervisorのログです。設定やhookが反映されない場合はmanaged settingsの診断ガイドも確認します。承認理由や担当者の記録は技術debugログと別に設計し、監査ログの記事で解説しています。
debugログを採取する4つの手順
- 症状を記録する。発生時刻、エラー、直前の操作、Claude Codeのバージョン、シェルと実行環境を控えます。プロンプト全文やソースコードは記録へ貼らず、時刻は端末のタイムゾーンも確認します。
- 対象セッションでdebugを有効にする。新しく再現する場合は
claude --debugで起動します。進行中のセッションでは/debug [issue]を使えます。このコマンドはログ出力と設定パスでClaudeに診断を促すため、ログをモデルへ渡す運用が許可されているか先に確認します。 - MCP調査は範囲を絞る。接続済みのserverにツールが表示されない場合などは、
claude --debug=mcpで一度再現し、serverの起動・応答とエラーを確認します。一般的な接続確認はMCP接続のトラブルシューティングも参照してください。 - ファイルを時刻とIDで選ぶ。公式ガイドのMCPログ例は
~/.claude/debug/<session-id>.txtです。macOS・Linux・WSLではls -lt "$HOME/.claude/debug/"で一覧を確認し、再現時刻とsession IDを照合します。Windows Nativeなどは保存先が異なる場合があるため、実環境の公式手順を確認してください。
見つからない場合は、debugを有効にしたsession ID、起動したユーザー、WSLなど実行環境側のホームディレクトリを確認します。会話履歴やホーム全体を無差別に検索する必要はありません。
ログを読む順序：エラーの前後をひとまとまりで見る
全文ではなく再現時刻の前後を読みます。単独の行だけでは処理の関係を誤ることがあるため、次の順に照合します。
- エラー文面と時刻が端末表示に一致するか。違う場合はタイムゾーンを確認する。
- 直前のtool、hook、MCP server、設定読み込みなど、処理対象は何か。
- 前後に権限要求、設定値、server応答、終了コードなどの手掛かりがあるか。
- session IDは一貫しているか。別セッションの記録を混ぜない。
- 同じ条件で再現するか。条件が異なる場合は記録し、原因を断定しない。
「permission」「timeout」の語だけで原因は確定しません。ログは技術的な処理経過を示しますが、業務上の承認理由や判断者までは通常分かりません。設定・hook・MCP・skillの確認は公式の設定デバッグガイドも参照します。
症状別に次の確認先を選ぶ
| 症状 | 次に確認する内容 |
|---|---|
| 同じ操作でエラーが再現する | 該当session IDの時刻前後を読み、直前の処理と直後の応答を対にして記録する |
| MCP serverが接続済みなのにツールがない | claude --debug=mcpを対象セッションで使い、server側のstderrとdebugログを照合する |
| hookやsettingsが反映されない | 実際にどの設定ファイルが読み込まれたか確認し、適用範囲と優先順位を調べる |
| background taskの出力を探している | 対象IDに対してclaude logs <id>を使う。対話セッションのdebugログと混同しない |
| インストール・settingsの診断が必要 | claude doctorはterminalから行う読み取り専用診断。セッション中の/doctorとは役割が異なる |
コマンド仕様は更新されるため、最新の説明は公式CLIリファレンスで確認します。基本操作はClaude Codeの基本操作ガイドを参照してください。
ログを共有する前に確認すること
debug loggingは詳細な処理情報を記録します。環境によって、ユーザー名、ローカルパス、repository名、社内URL、非公開コード、hookやMCP serverの出力を含む可能性があります。共有前に中身を確認し、必要な行だけを選びます。
- API key、token、Cookie、Authorization headerを確認し、必要なら値全体をマスクする。
- 個人名、端末名、顧客名、内部URLやrepository情報は必要分だけ残す。
- hook・MCP・shell出力に秘密値、顧客データ、非公開入力がないか見る。
- 共有先、閲覧権限、保管期限、削除方法を確認する。
- raw logをそのままチャットやissueに添付せず、承認済み窓口を使う。
/debug [issue]はログ出力と設定パスを用いて診断する方法です。外部サービスへの送信が禁じられている場合は使わず、ローカル確認のうえ管理者へ相談します。事故が疑われるときは不用意に転送・削除せず、社内の対応手順に従います。
確認前チェックリスト
- □ 症状、バージョン、操作時刻、実行環境を記録した
- □ 目的に合うセッション・MCP・background・設定診断の方法を選んだ
- □ 対象セッションだけでdebugを有効にし、再現時刻とIDを照合した
- □ エラーの前後を確認し、別sessionのログと混同していない
- □ 秘密情報や個人情報がないか目視し、共有は必要な範囲に絞った
- □ 共有先、保存期限、組織ルールを確認した
よくある質問
Claude Codeのdebugログはどこにありますか？
公式デバッグガイドは、MCPのdebugログ例として~/.claude/debug/<session-id>.txtを案内しています。対象の実行環境、session ID、再現時刻を照合してから開いてください。Windows Nativeなど環境によっては同じパスを使えない場合があります。
claude logs <id>で対話セッションのdebugログを読めますか？
いいえ。公式CLIリファレンスでは、claude logs <id>はbackground sessionの最近の出力を表示します。対話セッションのdebugログやsupervisorの記録とは目的が異なるため、見たい対象に合わせてコマンドを選びます。
/debug [issue]を実行するとログを共有しますか？
公式ガイドでは、ログ出力と設定パスを使ってClaudeに問題を診断させる方法として説明されています。実行環境のデータ取扱ルールに合うか分からない場合は、ログを渡す前に管理者へ確認し、許可されない場合はローカルで必要範囲だけ確認してください。
claude doctorはセッションのdebugログを表示しますか？
いいえ。公式CLIリファレンスのclaude doctorは、セッションを開始せずにインストールと設定を調べる読み取り専用診断です。対話セッションのdebugログを確認する方法とは分けてください。
公式情報と次の相談
debug loggingの有効化、MCPログの例、設定確認はClaude Code公式の設定デバッグガイド、claude logs・claude daemon logs・claude doctorの仕様は公式CLIリファレンスを参照してください。エラーが続く場合は、OS・shell・バージョン、再現手順、対象session ID、時刻、マスク済みの必要なログ範囲をそろえると、問い合わせ内容を整理しやすくなります。
Claude Codeの導入後、権限・ログ保管・問い合わせ経路をチームで整理したい場合は、Miraigentの無料診断からご相談ください。診断内容をもとに、現在の運用課題と次に確認する項目を整理できます。