debugging-protocol

デバッグプロトコル

価値： フィードバック――体系的な調査が理解をもたらします。 理解が正しい修正を生みます。正しい修正が再発を防ぎます。 調査を省略すると、バグを隠す症状への対処になってしまいます。

目的

修正を試みる前に根本原因の分析を徹底する、規律ある4段階のデバッグプロセスを指導します。問題が存在する理由を理解せずに修正へ飛びつくという、最もよくあるデバッグの失敗を防ぎます。

実践

鉄則：調査なしに修正しない

根本原因の調査を完了するまでは、バグを修正するためにコードを変更してはいけません。エラーを見てすぐに修正方法が分かったと思ったときこそ、間違っている可能性が最も高いタイミングです。まず調査してください。

実施すること：

• ほかのことをする前に、エラーメッセージとスタックトレースをすべて読む
• 調査の前に、バグを一貫して再現する
• 何が壊れているかだけでなく、なぜ壊れているかを理解する

実施しないこと：

• null ポインターエラーを見て、ヌルチェックを追加する（症状への対処）
• うまくいくものが見つかるまで「あれこれ試す」（行き当たりばったりのデバッグ）
• 「簡単な問題だから」と調査を省略する

フェーズ1：失敗を理解する

事実を集めます。まだ解釈はしません。

1. エラーメッセージ全体を読む――最初の1行だけでなく、すべての行を読む
2. 失敗が発生する正確なファイルと行を特定する
3. 失敗を一貫して再現する（再現しない場合は、それも重要な情報です）
4. 最近の変更を確認する：git log --oneline -10 と git diff
5. データフローを記録する：問題の値はどこから来るのか？

成果物： 何が、どこで、いつから起きているのかを明確に説明した記述。

フェーズ2：正常に動作する例を見つける

壊れているものと動作しているものを比較します。その違いがバグです。

1. 正しく動作している類似のコードを見つける
2. セットアップ、入力、状態、設定を比較する
3. 正常なケースと失敗するケースの違いを特定する
4. 依存関係を確認する：ライブラリが更新されたか？環境が変わったか？

成果物： 正常なケースと失敗するケースの具体的な違い。

フェーズ3：仮説を1つ検証する

明確で具体的な仮説を1つ立てます。変更を1つ加えて検証し、その結果から学びます。

1. 仮説を述べる：「[証拠]から、バグの原因は[X]だと考えます」
2. 検証のために変更を1つ加える
3. 結果を観察する
4. 仮説が間違っていた場合は、変更を完全に元に戻す
5. 学んだことを踏まえて、新たな仮説を立てる

複数のことを同時に変更しないでください。インポート、型、ロジックを同時に変更すると、どの変更が影響したのか分からなくなります。

成果物： 証拠によって確認または否定された仮説。

フェーズ4：修正して検証する

根本原因を理解しているため、確信を持って修正します。

1. バグを再現する失敗テストを書く（まだ存在しない場合）
2. フェーズ3で特定した根本原因を対象に修正を実装する
3. 検証する：新しいテストが成功し、既存のテストもすべて成功する
4. 症状ではなく、原因を修正したことを確認する

成果物： テストによって裏付けられ、すべてのテストが成功する修正。

エスカレーション：3回失敗したら停止する

修正を3回試してもうまくいかなければ、停止してください。問題はあなたが考えているものとは異なります。

3回目の失敗後：

1. 修正を試みるのを完全に停止する
2. 試したことと、それぞれの試みが失敗した理由を記録する
3. 自分の前提を疑う：抽象化が間違っているのか？ドメインモデルが間違っているのか？問題そのものを取り違えているのか？
4. より広い視点を求める――アーキテクチャレビュー、ドメインの専門家、またはユーザーへのエスカレーション

修正が3回失敗するのは、ほぼ常にコードの問題ではなく、設計上の問題を示しています。コードをさらに修正しても解決にはなりません。

例：

Attempt 1: Add caching (hypothesis: slow queries) -> Still slow
Attempt 2: Add index (hypothesis: missing index) -> Still slow
Attempt 3: Eager loading (hypothesis: N+1) -> Still slow
STOP. Profile the system.
Result: 90% of time in external API call. Not a database problem at all.

適用に関する注記

• スタンドアロンモード：推奨事項です。鉄則の遵守は各自に委ねられます。
• パイプラインモード：ゲートとして機能します。TDDゲートを通過して修正コミットを受け入れるには、デバッグの証拠が必要です。

厳守事項：

• 鉄則（修正前に調査する）：[H]
• 3回失敗した場合のエスカレーション：[RP]

制約

• 鉄則：調査を省きたいという誘惑は、修正方法が明白に思えるときに最も強くなります。だからこそ、そのようなときに調査が最も重要です。間違った「明白な」修正は、調査にかかったはずの時間以上に時間を無駄にするからです。このバグは調査不要な例外だと考えているなら、鉄則に反しています。
• 3回まで：仮説が3回続けて失敗したなら、問題はあなたが考えているものとは異なります。「止める」とは、修正を止めて調査に戻ることです。作業全体を止めるという意味ではありません。前提を見直し、調査範囲を広げ、関連するシステムを確認してください。それでも根本原因を特定できない場合は、エスカレーションしてください。
• 失敗した仮説を元に戻す：「完全に元に戻す」とは、仮説を検証する前の状態にコードベースを正確に戻すことです。「ほぼ元に戻したが、いくつかの改善は残した」ではありません。「メインファイルは元に戻したが、デバッグログは残した」でもありません。失敗した仮説に基づく変更は、すべて元に戻してください。

検証

このスキルに沿ってデバッグした後、以下を確認してください。

• コードを変更する前に、フェーズ1の調査を完了した
• エラーメッセージ全体を読んだ（最初の行だけではない）
• バグを一貫して再現できた
• 比較対象となる、正常に動作する例を見つけた
• 修正を試みる前に、明確な仮説を示した
• 仮説の検証ごとに、変更を1つだけ加えた
• 新たな仮説を試す前に、失敗した仮説の変更を元に戻した
• 修正を実装する前に、失敗するテストを書いた、またはそのテストがあることを確認した
• 修正後にすべてのテストがパスすることを確認した
• エスカレーションせずに、修正の試行を3回以上行わなかった

いずれかの基準を満たしていない場合は、該当するフェーズを再確認してください。

依存関係

このスキルは単独で動作し、必須の依存関係はありません。以下と連携します。

• tdd： TDD中にテストが予期せず失敗した場合、このスキルに従ってコードを変更する前に調査します
• user-input-protocol： デバッグ中に判断が曖昧な場面に達した場合、推測せずに一時停止してユーザーに尋ねます
• domain-modeling： 3回修正に失敗した場合、根本原因はドメインモデリングの問題である可能性があります。ドメインレビューにエスカレーションしてください

依存関係が不足していますか？次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill tdd