debug-mantra

デバッグの心得

デバッグセッションで守るべき4つの手順です。最初にそのまま唱えてから、順番に実践してください。

これを最初の応答の冒頭で、そのまま唱えてください

心得：

1. 最初に再現性を確認します。 問題を確実に再現できますか？
2. 失敗する経路を把握します。 まずデバッガーを使い、次にソースを追跡して設定項目を列挙し、それからコード内に計測処理を入れます。
3. 仮説に疑問を持ちます。 仮説を覆すものは何ですか？
4. 実行結果はすべて手がかりです。 すべてを相互に照合します。

それから作業を始めてください。

---

1. 確実に再現する

何よりも先に、実行可能な再現手順を用意してください。

• 確実に再現できる場合 → 失敗するテスト、curl スクリプト、CLI の実行コマンド、リプレイ用ハーネスなど、正確な手順、入力、環境を、実行可能な成果物として記録します。
• 再現が不安定な場合 → まだデバッグできる段階ではありません。まず再現率を上げます。トリガーを繰り返す、並列化する、負荷を加える、タイミングの範囲を狭める、スリープを挿入するなどの方法を試します。再現率50％ならデバッグできますが、1％ではできません。
• まったく再現できない場合 → ここで止めます。再現できないことを明確に伝えます。環境へのアクセス、取得済みの成果物（HAR、ログダンプ、コアダンプ）、または計測処理を入れる許可をユーザーに求めます。仮説を立てて先に進んではいけません。

目標は、高速（1～5秒）で決定的な合否シグナルです。時刻を固定し、乱数生成器にシード値を設定し、ネットワークを凍結し、ファイルシステムを分離します。

2. 失敗する経路を把握する

再現できたら、コードがどこで壊れ、何があれば壊れなくなるのかを特定します。差分を調べることで、原因の範囲を絞り込めます。以下の順に試し、前の方法で失敗した場合にのみ次へ進んでください。

1. デバッガーをアタッチします。 環境が対応している場合は、デバッガーをアタッチして失敗箇所までステップ実行します。ブレークポイント1つはログ10件より効果的です。設定項目を変更する前に、これを行ってください。
2. ソースの追跡と設定項目の列挙。 デバッガーが使えない場合（または問題に到達できない場合）は、コードの経路を最初から最後まで追い、結果に影響を与える設定項目をすべて列挙します。
   • 設定フラグ、環境変数、機能トグル
   • 分岐条件、入力の形式
   • タイミング、並行性、ビルドオプション それぞれの項目が、差分検証で切り替える候補の軸になります。一度に1つだけ切り替えてください。
3. コード内に計測処理を入れます。 外部の設定項目では失敗を変えられない場合は、コードの内部を調べます。失敗箇所として疑われる位置に printf やログ出力を追加し、関連する内部状態をダンプします。後で簡単に一括削除できるよう、各調査用出力に一意のプレフィックス（例：[DBG-a4f2]）を付けます。トレースから、実際の挙動がモデルと異なる箇所を明らかにします。

3. 仮説を反証する

根本原因の候補が見つかったら、検証する前に厳しく吟味します。

• その仮説は、症状を最初から最後まで本当に説明できますか？ 順を追って確認してください。
• 最も簡潔な証明は何ですか？ 最も明確な反証は何ですか？
• まず反証を試します。仮説が否定されなければ、それは実際の原因です。否定されれば、幻の原因を追いかけずに済みます。
• 仮説は1つだけでなく、優先順位を付けて3～5個立てます。仮説が1つだけだと、最初にもっともらしい考えに固執してしまいます。

4. 実行結果はすべて手がかりです

このセッションで行った実験すべての記録簿を更新し続けます。各項目には、何を変更したか、何が起きたか、何が裏付けられ、何が否定されたかを記録します。

• 新しい仮説が浮かんだら、記録簿を確認します。直近の観察結果だけでなく、過去のすべての観察結果と矛盾しませんか？
• 過去の実行結果に矛盾するものがあれば、仮説が誤っているか不完全です。見直すか、破棄してください。
• 迷ったら、結果によって確実に判断できる単一の実験を設計します。次にそれを実行し、近接する実験を手当たり次第に繰り返すのはやめましょう。
• 実行するたびに記録簿を更新してください。セッションを通じて記憶を保つためのものです。

---

運用ルール

• デバッグセッションごとに、最初の応答でマントラのブロックを1回だけ唱えます。セッションの途中で再度唱えてはいけません。
• 一言一句そのまま唱えます。言い換えたり、短縮したり、行を省略したりしてはいけません。
• ユーザーが「マントラは省略して」と言った場合は、マントラを唱えず、4つのステップを黙って適用します。
• 4つのステップを順番に適用します。
  • #1を満たす（信頼できる再現手順がある）前に、修正案を提案してはいけません。
  • #2で失敗経路を絞り込む前に、仮説の検証を始めてはいけません。
  • #3で仮説を反証しようとする前に、仮説を確定してはいけません。
  • #4で過去のすべての手がかりと照合して確認するまで、仮説が正しいと断言してはいけません。
• 信頼できる再現手順がないのに修正案を提案しようとしていることに気づいたら、いったん止めてステップ1に戻ります。
• マントラはセッションを通してあなた自身が守る制約であり、ユーザーに伝えるアドバイスではありません。