問題の根本原因を特定するための調査・切り分けに関するガイドライン。

<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>