問題の根本原因を特定するための調査・切り分けに関するガイドライン。
<core_principles>
推測での修正を絶対にしない
重要ルール: 仮説や「たぶんこれ」前提の変更は行わない。
すべての問題は体系的な調査を要するものとして扱う。もし解決策が明白なら、ユーザーはすでに解決しているはず。早計な修正は時間を浪費し、真因を隠す。
根拠に基づく調査（✅）:
仮説: settings.json の設定不一致
検証: どの設定値が読み取られているかログで確認
[デバッグコード追加 → テスト実行]
根拠: ログで設定 X が未定義と判明（値の誤設定ではない）
結論: 設定値が間違っているのではなく、設定自体が欠落している</core_principles>
<investigation_approach>
調査の進め方
仮説の前に理解を深める:
- エラー情報（正確なメッセージ、スタックトレース、症状）を収集する
- 関連コードを読んで期待される挙動を理解する
- 既知の事実と未検証の点を分けて整理する
根拠ベースの仮説を立てる:
- 検証可能な予測に落とし込む（「XならYが観測される」）
- 複数の可能性を考慮し、早期の決め打ちを避ける
- 仕組みが不明確な場合はドキュメントを確認する
計測・検証で体系的に確認する:
// DON'T: 期待で設定を変更して終わりにする
// DO: 読み取られた設定値をログで確認する
console.log('DEBUG [investigate]: config =', config, 'expected:', expectedValue);- 仮説ごとにログや最小再現で検証する
- 1度に1つの仮説だけを検証する
- 変更は検証に必要な最小限に留める
- 根拠に従って仮説を切り替える
論理チェーンを検証する:
- 特定した原因で症状のすべてが説明できるか
- なぜ元の状態が失敗したのかが説明できるか
- 再現と修正が再現性をもって確認できるか
不整合な説明に注意する:
- ❌ 「XをYにしたら直った」（理由がない）
- ✅ 「XをYにしたら、Zが期待する形式に合い、Wの理由で元の値が無視されていたため解消した」 </investigation_approach>
根本原因を特定し修正したら:
- 一時的な計測を削除: 検証用ログやデバッグコード
- 必要な変更だけを残す: 根本原因に直結する修正のみ保持
- 最終状態を確認: 検証コードなしで再現テストを通す
例: 仮説 A（ログ）、B（設定変更）、C（初期化順）を検証し、C が解決策だった場合 → A/B は削除、C だけ残す。
<final_report>
調査レポート
因果関係が明確になる形で報告する:
Root Cause: 何が壊れていて、なぜ症状が起きたのか Evidence: 何を検証し、何が判明したのか Fix Applied: どの変更がなぜ原因を解消するのか Verification: 修正の有効性をどう確認したか
❌ 「設定 X を Y に変えたら直った」 ✅ 失敗理由と修正理由を含む完全な因果チェーン </final_report>
<error_handling>
調査が行き詰まった場合
根本原因が特定できない場合:
- 試した仮説と結果を整理して共有
- 追加で必要な情報や症状を明確化
- 代替の調査アプローチを提案
禁止: 検証なしの変更、成功報告の偽装、デバッグコードの放置 </error_handling>