debugging

モード：認知／プロンプト駆動 — 単独で実行できるユーティリティスクリプトはありません。エージェントのコンテキストで使用します。

体系的なデバッグ

概要

場当たり的な修正は時間を浪費し、新たなバグを生み出します。応急処置は根本的な問題を覆い隠します。

基本原則： 修正を試みる前に、必ず根本原因を見つけてください。症状への対処は失敗です。

このプロセスの文言に違反することは、デバッグの本質に違反することです。

絶対のルール

1. 絶対に、フェーズ1の根本原因調査を完了する前に修正を提案または実施しないでください。根本原因を特定せずに行う修正は、失敗するか新たなバグを生み出す推測にすぎません。
2. 必ず、デバッグの前にバグを確実に再現してください。一貫して再現できないなら、実際の問題をデバッグしているとは言えません。
3. 絶対に、仮説を検証するときに一度に複数の変更を加えないでください。複数の変更を同時に行うと、どの変更で問題が解決したのか判断できなくなります。
4. 必ず、修正を3回試して失敗したら立ち止まり、アーキテクチャを見直してください。修正のたびに新たな問題が明らかになるなら、問題は症状ではなくアーキテクチャにあります。
5. 絶対に、修正を実施する前に失敗するテストケースを作成する手順を省略しないでください。テストがなければ、修正が機能したか、または後退を引き起こさないかを検証できません。

使用する場面

使用する場面

あらゆる技術的な問題に使用します。

• テストの失敗
• 本番環境のバグ
• 予期しない動作
• パフォーマンスの問題
• ビルドの失敗
• 統合の問題

特に次のような場合に使用してください。

• 時間に追われているとき（緊急時は推測に頼りたくなります）
• 「とりあえず、すぐ直す方法」が明らかに思えるとき
• すでに複数の修正を試しているとき
• 以前の修正がうまくいかなかったとき
• 問題を十分に理解できていないとき

次のような場合でも省略しないでください。

• 問題が単純に見えるとき（単純なバグにも根本原因があります）
• 急いでいるとき（慌てて進めると、必ずやり直しになります）
• マネージャーが今すぐ直すよう求めているとき（体系的に進めるほうが、試行錯誤を繰り返すより速く済みます）

使用する場面：debugging と smart-debug の使い分け

シナリオ	debugging を使用	smart-debug を使用
単純で、ローカルで再現できるバグ	はい	過剰
根本原因の領域がすでにわかっている	はい	任意
静的解析／コードレビューで見つかったバグ	はい	いいえ
実行時／本番環境の問題	まずはこちら	推奨
断続的／再現が難しい問題	エスカレーション	はい
仮説の順位付けによるゲートが必要	いいえ	はい（必須）
計測とログ分析が必要	いいえ	はい
オブザーバビリティ主導（トレース、APM）	いいえ	はい

目安： 単純なバグには debugging から始めてください。仮説の順位付け、構造化された計測が必要な場合、またはバグが断続的／本番環境でのみ発生する場合は、smart-debug に切り替えてください。

関連項目： .claude/skills/smart-debug/SKILL.md

4つのフェーズ

次のフェーズに進む前に、必ず各フェーズを完了してください。

フェーズ 1：根本原因の調査

修正を試みる前に、必ず次のことを行ってください。

1. エラーメッセージを注意深く読む

   • エラーや警告を読み飛ばさないでください
   • 多くの場合、正確な解決策が記載されています
   • スタックトレースを最後まで読んでください
   • 行番号、ファイルパス、エラーコードを確認してください

2. 再現性を確認する

   • 確実に再現できますか？
   • 正確な手順は何ですか？
   • 毎回発生しますか？
   • 再現できない場合は、推測せず、さらにデータを集めてください

3. 最近の変更を確認する

   • これを引き起こした可能性がある変更は何ですか？
   • Git の差分、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

4. 複数コンポーネントから成るシステムでは証拠を集める

   システムに複数のコンポーネントがある場合（CI - ビルド - 署名、API - サービス - データベースなど）：

   修正案を提示する前に、診断用の計測を追加してください。

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   例（多層システム）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   これにより判明すること： どの層で失敗しているか（シークレット - ワークフロー OK、ワークフロー - ビルド FAIL）

   分散システム／マイクロサービスシステムでは、OpenTelemetry のトレースを優先してください。

   # Query traces by component (preferred over manual echo/env logging)
   pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200
   
   # When trace ID is already known
   pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
   

   断片化したトレース（各サービスに独自のルートスパンがあり、トレース ID が境界を越えて一致しない状態） ＝コンテキスト伝播の破損です。ビジネスロジックを調査する前に、traceparent／tracestate ヘッダーの転送を修正してください。

   計測のゲート（仮説の生成前）： 静的解析を行ってもランタイムの動作が不明な場合は、仮説を生成する前に、重要な判断ポイントに対象を絞ったログ出力を追加してください。セッション単位のログファイル（.claude/context/tmp/debug-{sessionId}.log）を使用して、ランタイムの状態を記録します。ヒューマン・イン・ザ・ループ：計測を追加した後、結果を分析する前に、ユーザーにバグを再現するよう依頼してください。ランタイムの証拠を収集してから、フェーズ 2 に進んでください。

5. データフローを追跡する

   エラーがコールスタックの深い場所で発生している場合：

   完全な逆方向トレース手法については、このディレクトリの root-cause-tracing.md を参照してください。

   簡易版：

   • 不正な値はどこで発生していますか？
   • 不正な値を渡してこれを呼び出したのは何ですか？
   • 発生源が見つかるまで、上へ向かって追跡を続けてください
   • 症状ではなく発生源を修正してください

フェーズ 2：パターン分析

修正する前に、パターンを見つけてください。

1. 動作する例を見つける

   • 同じコードベース内で、類似した動作するコードを見つけてください
   • 壊れているものと似ていて、正常に動作するものは何ですか？

2. リファレンスと比較する

   • パターンを実装する場合は、リファレンス実装を最後まで読んでください
   • 斜め読みせず、すべての行を読んでください
   • 適用する前に、パターンを完全に理解してください

3. 違いを特定する

   • 動作するものと壊れているものの違いは何ですか？
   • どんなに小さくても、すべての違いを列挙してください
   • 「それは関係ないはず」と決めつけないでください

4. 依存関係を理解する

   • これにはほかにどのコンポーネントが必要ですか？
   • どのような設定、構成、環境が必要ですか？
   • どのような前提がありますか？

フェーズ 3：仮説とテスト

科学的手法：

1. 仮説を 1 つ立てる

   • 「Y が理由で、X が根本原因だと思います」と明確に述べてください
   • 書き留めてください
   • 曖昧にせず、具体的にしてください

2. 最小限のテストを行う

   • 仮説を検証するために、可能な限り最小限の変更を加えてください
   • 一度に 1 つの変数だけを変更してください
   • 一度に複数の問題を修正しないでください

3. 続行する前に検証する

   • 動作しましたか？ はいの場合は、フェーズ 4 に進みます
   • 動作しませんでしたか？ 新しい仮説を立ててください
   • 修正をさらに重ねないでください

4. わからない場合

   • 「X が理解できません」と伝えてください
   • 知っているふりをしないでください
   • 助けを求めてください
   • さらに調べてください

フェーズ 4：実装

症状ではなく、根本原因を修正します。

1. 失敗するテストケースを作成する

   • 可能な限りシンプルに再現します
   • 可能であれば自動テストを作成します
   • テストフレームワークがない場合は、単発のテストスクリプトを作成します
   • 修正前に必ず作成します
   • 適切な失敗テストを書くには、tdd スキルを使用します

2. 修正を1つ実装する

   • 特定した根本原因に対処します
   • 一度に変更するのは1つだけです
   • 「ついでに」改善しません
   • リファクタリングをまとめて行いません

3. 修正を検証する

   • テストは合格しましたか？
   • ほかのテストは壊れていませんか？
   • 問題は実際に解決しましたか？

4. クリーンアップする

   • このデバッグセッションで追加した計測機能をすべて削除します（ログ文、一時的な診断コードなど）
   • クリーンアップを検証します。セッションのデバッグ ID または計測マーカーを grep して、本番コードにデバッグ用の残骸がないことを確認します
   • 例：rg "debug-{sessionId}" --type-add 'src:*.{js,ts,cjs,mjs}' -tsrc .

5. 修正が機能しない場合

   • 停止します
   • これまでに試した修正の数を数えます
   • 3 回未満の場合：フェーズ 1 に戻り、新しい情報をもとに再分析します
   • 3 回以上の場合：停止して、アーキテクチャを見直します（下記のステップ 6）
   • アーキテクチャについて話し合う前に、修正を 4 回目まで試してはいけません

6. 修正に 3 回以上失敗した場合：アーキテクチャを見直す

   アーキテクチャ上の問題を示すパターン：

   • 修正のたびに、別の場所で新たな共有状態、結合、問題が明らかになる
   • 修正の実装に「大規模なリファクタリング」が必要になる
   • 修正のたびに、ほかの場所で新たな症状が発生する

   停止して、根本から見直します：

   • このパターンは根本的に妥当ですか？
   • 「惰性だけでこの方法に固執」していませんか？
   • 症状の修正を続けるより、アーキテクチャをリファクタリングすべきですか？

   さらに修正を試みる前に、人間のパートナーと話し合ってください

   これは仮説の失敗ではありません。アーキテクチャが間違っています。

危険信号 — 停止して手順に従ってください

次のように考えていることに気づいたら：

• 「とりあえず応急処置をして、あとで調査しよう」
• 「X を変えて、うまくいくか試してみよう」
• 「変更をいくつか加えて、テストを実行しよう」
• 「テストは省略して、手動で確認しよう」
• 「たぶん X だろう。修正してみよう」
• 「完全には理解していないけれど、うまくいくかもしれない」
• 「パターンでは X となっているが、違う方法で調整しよう」
• 「主な問題は以下のとおりです：[調査せずに修正案を列挙する]」
• データフローを追跡する前に解決策を提案する
• 「もう一度だけ修正を試す」（すでに 2 回以上試している場合）
• 修正のたびに別の場所で新しい問題が明らかになる

これらはすべて、停止してフェーズ 1 に戻るべきサインです。

修正に 3 回以上失敗した場合： アーキテクチャを見直してください（フェーズ 4.5 を参照）

人間のパートナーが、あなたの進め方が間違っていると示すサイン

次のような軌道修正に注意してください：

• 「それは起きていないのでは？」— 確認せずに決めつけています
• 「それで分かるのは……ですか？」— 証拠を集めるべきでした
• 「推測はやめて」— 理解しないまま修正を提案しています
• 「徹底的に考えて」— 症状だけでなく、根本から見直す必要があります
• 「行き詰まっているの？」（苛立った様子）— そのアプローチはうまくいっていません

このようなサインがあったら： 停止して、フェーズ 1 に戻ってください。

よくある言い訳

言い訳	実情
「問題は単純なので、手順は必要ありません」	単純な問題にも根本原因はあります。単純なバグなら、手順に沿ってもすぐに解決できます。
「緊急なので、手順に沿う時間がありません」	体系的なデバッグは、当てずっぽうに試して混乱するよりも速いです。
「まずこれを試してから、調査します」	最初の修正が、その後の進め方を決めます。最初から正しく進めましょう。
「修正が機能することを確認してから、テストを書きます」	テストしていない修正は定着しません。まずテストを書けば、修正を検証できます。
「一度に複数の修正をすれば時間を節約できます」	何が機能したのかを切り分けられず、新たなバグの原因になります。
「参考資料が長すぎるので、パターンを応用します」	部分的な理解では、必ずバグが発生します。最後まで読みましょう。
「問題がわかったので、修正します」	症状が見えていることと、根本原因を理解していることは同じではありません。
「もう一度だけ修正を試します」（2回以上失敗した後）	3回以上の失敗は、アーキテクチャ上の問題を示しています。パターンを疑い、再度修正するのはやめましょう。

クイックリファレンス

フェーズ	主な活動	成功基準
1. 根本原因	エラーを読む、再現する、変更を確認する、証拠を集める	何が、なぜ起きたのかを理解する
2. パターン	動作する例を探し、比較する	違いを特定する
3. 仮説	仮説を立て、最小限のテストを行う	仮説を確認する、または新たな仮説を立てる
4. 実装	テストを作成し、修正して、検証する	バグが解決し、テストに合格する

手順を踏んでも「根本原因が見つからない」場合

体系的に調査した結果、問題が本当に環境要因、タイミング依存、または外部要因によるものだとわかった場合：

1. 手順を完了しています
2. 調査した内容を記録します
3. 適切な処理（再試行、タイムアウト、エラーメッセージ）を実装します
4. 今後の調査に備えて、モニタリング／ログ記録を追加します

ただし：「根本原因が見つからない」ケースの95%は、調査が不十分です。

関連する手法

以下の手法は体系的なデバッグの一部であり、このディレクトリから利用できます：

• root-cause-tracing.md - コールスタックを遡ってバグを追跡し、最初の引き金を特定します
• defense-in-depth.md - 根本原因を特定した後、複数のレイヤーに検証を追加します
• condition-based-waiting.md - 任意に設定されたタイムアウトを、条件をポーリングする方式に置き換えます
• find-polluter - テストの汚染を二分探索する場合（共有状態が原因の不安定なテスト）：プロジェクトのルートから .claude/tools/analysis/find-polluter/find-polluter.sh（Windowsでは find-polluter.ps1）を実行して、どのテストがテストスイートを汚染しているかを特定します。

関連スキル：

• tdd - 失敗するテストケースを作成する場合（フェーズ4、ステップ1）
• verification-before-completion - 成功を宣言する前に、修正が機能したことを検証します

実際の効果

デバッグセッションでの実績：

• 体系的なアプローチ：修正に15～30分
• ランダムな修正アプローチ：2～3時間の試行錯誤
• 初回での修正成功率：95% 対 40%
• 新たに発生するバグ：ほぼゼロ 対 頻発

AI を活用したデバッグと最新の可観測性（2025年以降）

OpenTelemetry：新しいスタックトレース

分散システムでは、OpenTelemetry のトレースを使うことで、手動で echo／env を使って証拠を集める必要がなくなります。トレースには、span ID と trace ID（W3C Trace Context 標準：traceparent／tracestate ヘッダー）を通じて、サービス境界をまたぐリクエストの全経路が表示されます。

分散障害の証拠の優先順位（上から順に推奨）：

1. Distributed traces (OpenTelemetry spans, correlated trace IDs)
2. Structured logs with correlation IDs
3. Metrics with timestamps
4. Manual instrumentation (Phase 1 Step 4 bash examples)

よくある症状 — 分断されたトレース： 各サービスにそれぞれ独自のルートスパンが表示され、境界をまたぐとトレース ID が一致しません。これはコンテキスト伝播が機能していないことを意味します。ビジネスロジックを調査する前に、ヘッダー転送を修正してください。

AI 支援による根本原因分析

LLM ベースのデバッグエージェント（2025 年の手法）は、本番環境のトレースを読み取り、コードベースのコンテキストと照合して最小限の再現ケースを提案することで、フェーズ 1 を補強します。

AI 支援を利用するケース：

• 影響範囲が複数のサービスに及ぶ、複雑度の高い分散障害
• 根本原因を迅速に特定する必要があるオンコールインシデント
• 本番環境のトレースを決定論的なテスト再現ケースに変換する場合

AI 支援を利用する場合でも、フェーズ 1 を省略しないでください。AI の提案は仮説です。AI が提案した修正を実装する前に、フェーズ 3（仮説の検証）を適用してください。AI は体系的な調査の代わりにはなりません。証拠収集を加速させるものです。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
「とりあえず応急処置をして、調査は後で」	応急処置が恒久化し、根本原因が別の症状として再発します	本番コードに手を加える前に、必ずフェーズ 1 を完了してください
複数の変更を一度に行う	どの変更がシステムを修正または破損させたのか判断できず、リグレッションが発生します	仮説検証ごとに変更は 1 つだけにし、次の変更の前に検証してください
テストせずに AI が提案した修正を適用する	AI の提案は事実ではなく仮説です。盲目的に適用するとフェーズ 3 を省略することになります	AI の提案は実装する答えではなく、検証する仮説として扱ってください
3 回失敗した後に 4 回目の修正を試みる	うまくいっていない方針で N+1 回目の修正を試みると、問題が悪化します	修正に 3 回失敗したら、アーキテクチャレビューにエスカレーションしてください
修正前に失敗するテストを省略する	修正が機能したか検証できず、リグレッションも見えなくなります	まず失敗するテストを作成してください。これにより根本原因を証明し、修正を検証できます

メモリープロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます。

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 発見した問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリーに記録されていなければ、起きていないのと同じです。