CodeCraft Lab

体系的なトラブルシューティング

個別エラーの対処法ではなく、問題を切り分け・原因を特定し・解決へ導く方法論を学ぶ、応用コース最終レッスンです

応用20分で読了
トラブルシューティング問題解決ログ解析応用コース修了

このレッスンで学ぶこと

  • 個別のエラーメッセージに頼らず、問題を切り分けるための一般的な方法論を身につける
  • ログや診断情報を読み解き、原因の仮説を立てて検証する実践的なアプローチを理解する
  • 「直す」のではなく「作り直す」べきタイミングの判断基準を持つ
  • 応用コース全体を振り返り、次に学ぶべき領域への見通しを立てる

前提条件

  • 応用コース Lesson 1〜14（MCP、Hooks、Skills、サブエージェント、Agent SDK、IDE連携、Remote Control、デスクトップアプリ、パフォーマンス最適化）の内容に一通り触れていること
個別エラーの解決方法を探しているなら

「このエラーメッセージが出た、今すぐ直したい」という場合は、実践レシピ「よくあるエラーと対処法まとめ」がQ&A形式で頻出エラーをカバーしています。このレッスンはそれとは異なり、**個別のエラーを離れて「問題解決そのものの考え方」**を扱います。初めて見るエラーや、レシピに載っていない複合的な問題に直面したときの拠り所として読んでください。

なぜ「考え方」を学ぶ必要があるのか

エラーメッセージを検索してコピー&ペーストで解決する方法は、既知の問題には強力です。しかし実際の開発現場では、次のような「検索しても出てこない」状況に何度も出会います。

  • 複数の要因が絡み合って、単一のエラーメッセージに収束しない
  • 自分の環境固有の組み合わせ（OS・ネットワーク・プラグイン構成）でしか起きない
  • 「遅い」「たまに失敗する」のように、エラーメッセージそのものが存在しない

こうした問題に対しては、個別の対処法を暗記するのではなく、どんな問題にも適用できる切り分けの手順を持っていることが力になります。このレッスンでは、その手順を4つの段階に分けて解説します。

flowchart LR
    A["1. 再現条件の特定"]
    B["2. 影響範囲の絞り込み"]
    C["3. ログ解析と仮説検証"]
    D["4. 解決 or 環境再構築の判断"]
 
    A --> B --> C --> D
 
    style A fill:#e8f4fd,stroke:#1a73e8
    style D fill:#fff3e0,stroke:#e65100

ステップ1: 再現条件を特定する

問題解決の第一歩は、「いつ・どんな条件で」問題が起きるのかを明確にすることです。再現条件が曖昧なまま対処を始めると、たまたま症状が収まっただけなのに「直った」と勘違いしてしまうことがあります。

再現条件を絞り込む質問

  • 毎回起きるのか、それとも特定の条件下でだけ起きるのか
  • 特定のファイル・特定のプロジェクトでだけ起きるのか、どこでも起きるのか
  • 直前に何か変更を加えたか(プラグインの追加、設定変更、バージョンアップなど)
  • 同じ操作を繰り返すと、毎回同じ結果になるか

最小再現手順を作る

問題が起きる手順を、できるだけ少ないステップに削っていきます。「このプロジェクトで、この指示を出すと、必ず同じ症状になる」という最小限の手順が見つかれば、それだけで原因の範囲が大きく絞られます。

「いつから」を特定する

「昨日まで動いていた」のであれば、その間に何が変わったかを洗い出します。Claude Codeのバージョンアップ、プロジェクトの依存関係の更新、CLAUDE.mdやhooksの変更など、変化点はすべて疑いの対象です。

再現しない条件も記録する

「Aプロジェクトでは起きるが、Bプロジェクトでは起きない」という情報は、「起きる条件」と同じくらい価値があります。両者の違いが、原因の手がかりになります。

再現しない問題は「解決」と区別する

一度試して症状が出なかっただけで「直った」と判断するのは早計です。特に環境依存の問題は、条件がたまたま揃わなかっただけということがあります。可能であれば複数回試し、再現条件の理解そのものが正しかったかを確認しましょう。

ステップ2: 影響範囲を絞り込む

再現条件が見えてきたら、次は「どこに原因があるか」のレイヤーを絞り込みます。Claude Codeの動作は、複数のレイヤーが重なって成り立っています。

レイヤー具体例
ネットワーク・認証プロキシ、ファイアウォール、OAuthトークンの期限切れ
Claude Code本体の設定settings.json、permissions、環境変数
拡張部分MCPサーバー、Hooks、Skills、プラグイン
IDE統合VS Code拡張機能、JetBrainsプラグイン
プロジェクト固有の要因CLAUDE.mdの記述、リポジトリの規模、.gitignoreの設定

レイヤーを切り分ける実践的な方法

応用コース Lesson 14で紹介した--safe-modeは、まさにこの切り分けのための機能です。プラグイン・MCPサーバー・Hooksをすべて無効にした状態で同じ操作を試し、症状が消えるかどうかを確認します。

claude --safe-mode

症状が消えれば、原因は拡張部分のどこかにあると判断できます。そこから1つずつ機能を有効化し直し、症状が再発したタイミングで原因が特定できます。これは「全部疑う」のではなく「疑う対象を半分ずつ減らしていく」という、効率のよい絞り込み方です。

flowchart TD
    A["症状が発生"]
    B["--safe-mode で再現するか確認"]
    C{"safe-modeでも<br/>再現する?"}
    D["原因はClaude Code本体<br/>・ネットワーク・認証側"]
    E["原因は拡張部分<br/>(MCP/Hooks/Skills/プラグイン)"]
    F["1つずつ有効化し直して<br/>再発ポイントを特定"]
 
    A --> B --> C
    C -->|はい| D
    C -->|いいえ| E --> F
 
    style D fill:#fff3e0,stroke:#e65100
    style E fill:#fff3e0,stroke:#e65100

IDE統合特有の問題かどうかを切り分けたい場合は、応用コース Lesson 11で扱った通り、IDE経由ではなくCLI単体で同じ操作を試してみるのも有効な絞り込み方法です。IDEでは起きるがCLI単体では起きないなら、原因はIDE統合のレイヤーにあると判断できます。

ステップ3: ログ解析と仮説検証

絞り込みができたら、具体的な手がかりを集める段階です。

まず/doctorを実行する

何から手をつければよいか迷ったときの共通の入口は/doctorです。インストールの整合性、設定ファイルの構文エラー、MCPサーバーの接続状態、コンテキスト使用量を一括でチェックしてくれます。Claude Codeが起動すらしない場合は、シェルから直接claude doctorを実行します。

/doctor

ログ・診断情報の読み方

診断情報やエラーメッセージを読むときは、次の順序で読み解くと効率的です。

エラーの発生箇所を特定する

どの処理の最中に発生したエラーなのか(ファイル読み込み中か、MCPサーバー通信中か、コマンド実行中か)を最初に確認します。発生箇所がわかるだけで、疑うべきレイヤーがぐっと絞られます。

エラーメッセージの「型」を見る

EACCESのような権限エラー、403のような認証エラー、Could not resolve hostのようなネットワークエラーなど、エラーメッセージの型がわかれば、原因のカテゴリも自動的に絞られます。

直前のログ・出力と突き合わせる

エラー単体ではなく、その直前に何が実行されていたか、どんな出力があったかを合わせて見ます。エラーの原因は、エラーメッセージそのものではなく、その手前の処理にあることが多いものです。

仮説を立てて、最小限の変更で検証する

「これが原因ではないか」という仮説ができたら、一度に複数の変更を試すのではなく、1つだけ変更して結果を確認します。複数同時に変更すると、何が効いたのかわからなくなります。

メモリ使用量が異常に高いといった、エラーメッセージとして現れにくい問題には/heapdumpが有効です。JavaScriptヒープのスナップショットが出力され、何がメモリを占有しているかを詳しく分析できます。

Claude Code自身に診断を手伝わせる

ログや診断情報の量が多く、人間が読むには大変なときは、Claude Code自身にその解析を依頼するのも有効な手段です。「このログファイルの中でエラーパターンを分析して」「直近の失敗に共通する条件を抽出して」という指示は、ログ解析そのものをコンテキストの新しいセッションに委ねる良い使い方です。応用コース Lesson 14で扱ったサブエージェントへの委譲の考え方がここでも活きます。

ステップ4: 環境再構築の判断基準

調査を重ねても原因が特定できない、あるいは原因はわかったが修正コストが見合わない場合、「直す」のではなく「作り直す」という選択肢を検討する段階に入ります。

再構築を検討すべきサイン

  • 設定ファイル(settings.json、.mcp.jsonなど)に手を加えた履歴が積み重なり、何が有効な設定か把握できなくなっている
  • 複数の問題が複雑に絡み合い、1つを直すと別の症状が出るような状態が続いている
  • 同じ環境で繰り返し似たトラブルが起きており、場当たり的な対処を繰り返している

再構築の進め方

現状の設定を退避する

再構築する前に、現在の~/.claude/settings.jsonやプロジェクトの.mcp.json、CLAUDE.mdなどをバックアップしておきます。クリーンな状態と比較する基準にもなります。

クリーンな状態で症状が再現するか確認する

最小限の設定(あるいは--safe-mode)で同じ操作を試し、問題が起きないことを確認します。これにより、「環境の問題だった」という仮説そのものを検証できます。

設定を1つずつ復元する

バックアップした設定を、全部一度に戻すのではなく、必要なものから順に復元していきます。どこかで症状が再発すれば、それが根本原因だったとわかります。

「とりあえず再インストール」で終わらせない

再構築は有効な手段ですが、原因を特定しないまま「とりあえず入れ直したら直った」で済ませると、同じ問題が形を変えて再発するリスクが残ります。可能な範囲で、再構築の前後の違い(何を変えたら直ったか)を記録しておくと、次に同種の問題が起きたときの財産になります。

困ったときの最終手段

ここまでの手順を尽くしても解決しない場合の選択肢を整理しておきます。

選択肢こんなときに使う
/feedbackコマンドClaude Code自体のバグの可能性が高い場合に、Anthropicへ直接報告する
GitHub Issues同じ問題が既に報告されていないか確認する、または新規に報告する
実践レシピ「よくあるエラーと対処法まとめ」既知の頻出エラーに当てはまらないか、改めて確認する
/doctorの出力をそのまま添付する問題報告の際、再現条件と合わせて診断結果を共有すると解決が早まる

応用コースを振り返る

応用コース全15レッスンを通じて、あなたはClaude Codeを「与えられた機能を使うツール」から「目的に応じて拡張・カスタマイズし、複数の入口を使い分け、問題が起きても自力で立て直せる基盤」へと捉え直してきました。

  • 拡張する技術(Lesson 1〜10): MCPでの外部ツール連携、Hooksによる自動化、Skillsでのコマンド化、サブエージェントとAgent SDKによる高度なカスタムエージェント構築、マルチエージェントパターンの設計
  • 使う場所を選ぶ技術(Lesson 11〜13): VS Code・JetBrainsとの統合、Remote Controlによる場所を選ばない操作、デスクトップアプリでの並行作業とスケジュール実行
  • 持続させる技術(Lesson 14〜15): パフォーマンスとコストの継続的な最適化、そして問題が起きたときに体系的に立て直す方法論

これらはどれも、一度学んだら終わりではなく、プロジェクトの規模や働き方が変わるたびに見直す価値のあるスキルです。

応用コース修了おめでとうございます

入門コース・実践コースで身につけた日常的な活用力に、応用コースの拡張・統合・最適化の技術が加わったあなたは、Claude Codeを自分のワークフローに合わせて自在に組み替えられる段階に到達しています。ここから先は、実際のプロジェクトで試行錯誤を重ねながら、自分とチームに合った形を見つけていくフェーズです。

次のステップ: 組織導入コースへ

個人としてのClaude Code活用を極めた次に待っているのは、「チームや組織でどう安全に・効率よく導入するか」というテーマです。組織導入コース(近日公開)では、次のような内容を予定しています。

  • 導入計画の策定とROIの考え方
  • 権限設計とセキュリティポリシーの構築(allow/denyリストの設計、監査ログ)
  • 組織全体で使うCLAUDE.mdテンプレートの階層設計
  • GitHub Actions・GitLab CI/CDとの連携による自動化
  • チーム運用ルールの策定とコスト管理
  • 導入効果の測定と経営層への報告

このレッスンで学んだ「体系的に問題を切り分ける考え方」は、個人の開発作業だけでなく、チーム全体でClaude Codeを運用する際のトラブル対応にもそのまま応用できます。応用コースで身につけた拡張・統合・最適化・問題解決の力を土台に、ぜひ組織導入コースの公開も楽しみにお待ちください。

公開までの間は、引き続き実践レシピ集や更新ウォッチでも新しい知見を発信していきます。応用コースの修了、おめでとうございました。