debugging

デバッグ

恒久的な修正は、証拠に裏付けられた因果関係の説明に基づいて行います。仮説は、範囲を限定した可逆的な実験を正当化する場合がありますが、検証が済むまでは実験として明示してください。インシデントが進行中の場合、根本原因が判明する前でも、権限のあるロールバックや機能の無効化によってサービスを復旧できることがあります。残る不確実性を記録し、修正の調査を継続してください。緩和策は修正の証明ではありません。

範囲とモード

診断のみを求められた場合は、呼び出し元の権限の範囲内で、ソースや成果物を調査し、安全な読み取り専用の確認を実行してください。修正を行ったり、ビルド禁止の制約に違反したりしてはいけません。診断では、提案された修正が未検証のままでも、証拠に裏付けられた原因を特定して完了できます。要求された作業を妨げる情報が不足している場合に限り、NEEDS_CONTEXT を使用してください。

編集は仮説で定めた狭いファイル範囲内にとどめ、範囲を広げる前に仮説を見直してください。他の作業は保持してください。診断情報を共有したり外部検索を行ったりする前に、必要に応じて認証情報、顧客データ、ホスト名、IP アドレス、パス、SQL 断片を削除してください。シークレットを埋め込まず、環境から取得した認証情報を使用してください。ブランチやビルドの比較、または診断データの共有については、baseline-and-data-handling.md を参照してください。

プロセス

1. 読み取って再現します。 フィルターに一致した箇所だけでなく、エラーと合計値をすべて読み取ります。セッション再開後は、引き継いだファイルの内容を信頼する前に HEAD を確認します。編集する前に、提供された再現手順を実行します。報告された症状を正確に再現します。近い別の失敗は、同じ再現ではありません。実際に引き金となる方法のうち、最も低コストなものを使います。間欠的なバグでは、試行回数に上限を設け、条件と発生頻度を報告します。有限回の実行で問題が起きなかったからといって、競合状態が否定されたわけではありません。再現手順の作成、縮小、計測を行う際は、reproduction-and-investigation.mdを読みます。
2. 仮説を根拠に基づいて立てます。 観察内容をそれぞれ根拠として挙げ、候補を2～3個立てます。検証済みの単純なタイプミスであれば、短い因果関係の確認だけで十分です。インポートエラーだけでは、インポートに失敗した理由は特定できません。実際の引き金を保ったまま、無関係な入力を減らします。再現ループを利用できない場合は、不足しているアクセス権、成果物、認証情報、または手順を報告し、再現したと主張せずに、独立して行えるソースの調査を続けます。
3. 追跡して原因を切り分けます。 固定のスタック深度にとらわれず、破られた不変条件と発生条件を説明します。コード、入力、状態、タイミング、環境、ビルド設定を比較します。別のビルドで同じソースが正常に動作しても、未定義動作や競合状態が潜んでいる可能性があります。バックワードトレーシングやテストの汚染についてはroot-cause-tracing.mdを、関連する環境情報の収集にはcollect-diagnostics.shを使用します。調査する前に、確認したい問いと判断基準を明確にします。結果を信頼する前に、対照条件とビルドの同一性を確認します。修正する前に、報告者が無関係としたものも含め、観察された症状をすべて列挙します。原因はそれぞれを説明できなければなりません。説明できない症状があれば、別の原因があるのか、仮説が未完成なのかを明記します。観察結果とログやプローブの結果が食い違う場合は、観察結果を退ける前に、計測されていない経路を疑います。
4. 変更は一度に一つだけテストします。 名前を付けた因果仮説を、最小限の実験で検証します。仮説が否定された実験は、次に進む前に元に戻します。回帰を新たに持ち込んだ可能性がある場合は、適切であれば bisect を使います。対処に失敗しても、修正が不完全だった、またはビルドが間違っていた可能性があり、原因が否定されたとは限りません。次の実験に進む前に、実際の証拠を再評価します。複数のコンポーネントにまたがる競合する説明については、competing-hypotheses.mdを読みます。
5. 修正して検証します。 許可された修正については、repair-and-escalation.mdを読みます。実際の引き金を再現する回帰テストを作成します。修正なしでは失敗し、修正ありでは成功する必要があります。利用可能なテスト用の接続点がない場合は、報告された不具合で失敗しないテストに置き換えず、その旨を報告します。ia-verification-before-completionの下で、最新の証拠を使って元のエントリーポイントを検証します。アサーションを弱めたり、失敗を握りつぶしたり、テスト対象の入力だけを特別扱いしたりしてはいけません。近い入力で同じ不正な状態に至るケースを使って、回避できないかをセルフチェックします。その入力で変更を回避できる場合は、根本原因の調査に戻ります。セキュリティに関わる修正では、specialized-patterns.mdに従い、新たに敵対的な再攻撃を実施します。その後、同じ不具合の形を広く調べます。リポジトリ内（生成コードとベンダーコードは除外）で、修正の特徴（呼び出し、欠けていたガード、または省略されていたロック）を検索し、一致箇所を「同じバグ」「安全（理由を記載）」「不明」に分類します。一致箇所を修正するのは、仮説の対象ファイルの範囲内で、個別の red/green チェックを行える場合に限ります。残りは列挙するか、対象範囲の拡大を依頼します。検証済みの修正を最小限に整え、診断用の計測を削除します。
6. 3回の失敗サイクル後に再評価します。 編集を止め、経路を読み直し、失敗した前提を列挙して、証拠を添えてエスカレーションします。3回というサイクル数は再試行の上限であり、アーキテクチャの問題を証明するものではありません。診断のみを行うモードで、コンポーネントを絞り込めないまま3サイクルに至った場合は、現時点での調査結果と次に行う計測手順を示します。原因が不明であれば、正直にそう伝えます。重要な情報が不足している場合は、Claude Code では AskUserQuestion を、対応していれば Codex では request_user_input を、それ以外ではチャットを通じて質問します。無人で実行されるサブエージェントは、ブロッカーを親エージェントに返します。 CI の失敗、レンダリング／非同期処理の初期移行、パフォーマンス、断続的な失敗、事後分析、または繰り返し見られるパターンについては、specialized-patterns.md をお読みください。多層防御で検証する不具合については、defense-in-depth.md をお読みください。診断におけるアンチパターンや修正の失敗が繰り返し見られる場合は、詳細な修復リファレンスに従ってください。

デバッグレポートと完了

依頼された範囲について、7 つのフィールドを出力してください。

SYMPTOM:    Observed failure
ROOT CAUSE: Evidenced causal conclusion with file:line covering every symptom, or remaining uncertainty
FIX:        Verified repair; use PROPOSED FIX and validation command in diagnosis-only mode
EVIDENCE:   Causal evidence and, for repairs, actual verification results
REGRESSION: Actual regression, or proposed test/missing seam when no repair was performed
RELATED:    Same-shape sweep (N checked, N same-shape, fixed/listed, or not run and why); prior bugs, risks, architecture
STATUS:     DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT

DONE は、修復が検証済みであるか、証拠をもって依頼された診断が完了したことを意味します。テストされていない解決策を提案しただけの状態を認定するものではありません。DONE_WITH_CONCERNS は、完了した範囲と残る不確実性を示します。BLOCKED は阻害要因を示し、NEEDS_CONTEXT は不足している必須情報を示します。緩和策を講じただけでは、修復依頼は完了になりません。

修復を完了する前に、因果関係を示す証拠、実際の回帰テストの網羅性またはその限界、迂回／再攻撃の結果、診断ログの削除を確認してください。重大な本番環境の不具合については、specialized reference を使って、タイムライン、原因、影響、修正、再発防止を簡潔にまとめた事後分析を記録してください。