debugging

デバッグ

クイックスタート

1. 正確な再現手順、影響範囲、最近の変更を記録します
2. コンポーネントやファイルを切り分け、障害に至る経路を追跡します
3. 正確なエラーを調査し、公式ドキュメントを確認します
4. 失敗するパターンと正常に動作するパターンを比較し、検証可能な仮説を立てます
5. 最小限のテストで検証し、すべての該当箇所に最小限の修正を適用して、動作を確認します

このスキルを使用する場面

次の場合はデバッグを使用します：

• バグの原因が明らかでない、または以前「修正」されたものの再発した
• エラーメッセージが不明瞭、または誤解を招く
• 試した複数の修正が失敗した
• 問題がコードベース内の複数箇所に影響する可能性がある
• 適切に解決するために根本原因の理解が不可欠である

次の場合はこのスキルを使用しません：

• 明らかな修正方法がある単純な構文エラー
• 些細なタイプミスやインポート漏れ
• 解決策が明確で、影響範囲が限定された既知のバグ

避けるべき主なアンチパターン

AI によるデバッグで記録された失敗を踏まえ、次のことを明示的に避けてください：

1. 循環論法：失敗した理由を把握せずに、同じ修正を二度提案しないでください
2. 早まった成功宣言：修正が実際に実装され、動作することを必ず確認してください
3. パターンの失念：セッションを通じて、確立されたコードパターンを常に意識してください
4. コンテキストの過負荷：50% ルールを適用し、コンテキストが 50% に達したら会話を再開してください
5. 症状の追跡：根本原因を理解せずにエラーメッセージだけを修正することは避けてください
6. 理解する前の実装：既存のパターンを調べる前にコード変更に取りかからないでください

理解する（10 項目のチェックリスト）

• 理解する：正確な再現手順、影響範囲、最近の変更を記録します
• 絞り込む：コンポーネントやファイルを切り分け、障害に至る経路を追跡します
• 調べる：正確なエラーを調査します（WebSearch → Parallel Search、Context7:get-library-docs）
• 確認する：コードベース内の既知の正常なパターンと比較します
• 推論する：SequentialThinking:process_thought と 5 Whys を使って根本原因にたどり着きます
• 統合する：予測を伴う反証可能な仮説を記述します
• テストする：ログやテストを追加して仕組みを確認します
• 適用する：パターンに従い、すべての該当箇所に根本原因への最小限の修正を適用します
• 記録する：知見、警告、決定事項を記録します
• ドキュメント化する：必要に応じてコメント、ドキュメント、テストを更新します

TodoWrite による進捗管理

TodoWrite を使って、UNDERSTAND チェックリストに沿ったデバッグの進捗を管理します：

1. 開始時：該当する各ステップの ToDo を作成します：

   ☐ U - Capture exact repro and scope
   ☐ N - Isolate failing component
   ☐ D - Research error message
   ☐ E - Compare with working patterns
   ☐ R - Root cause analysis (5 Whys)
   ☐ S - Write falsifiable hypothesis
   ☐ T - Verify with minimal test
   ☐ A - Apply fix across all occurrences
   ☐ N - Record insights
   ☐ D - Update docs/tests
   

2. デバッグ中：作業を進めながら、ステップを in_progress → completed に更新します

3. 行き詰まったとき：TodoWrite を使うと、どのステップがブロックされているかが分かります。ステップを飛ばしていないか、同じところを回っていないかを見極めるのに役立ちます

4. ステップを省略できるのは次の場合のみ：バグが単純で、チェックリストが過剰となる場合（上記の「次の場合はこのスキルを使用しません」を参照）

ツールの判断フロー

• 正確なテキストや記号が分かっている？ → grep
• 概念的・意味的な位置を知りたい？ → codebase_search
• ファイル全体のコンテキストが必要？ → read_file
• 慣れていないエラーや動作がある？ → Context7:get-library-docs、次に WebSearch → Parallel Search
• 複雑で複数の仮説を伴う分析が必要？ → SequentialThinking:process_thought

コンテキスト管理

• 推論の質が低下しないよう、コンテキスト使用量が約 50% に達したら再開します
• 再開する前に、事実、仮説、否定した可能性、次のステップを要約します
• その要約だけを使って新しいチャットを開始し、作業を続けます

判断フレームワーク

IF 同じ修正を二度提案した → 停止し、SequentialThinking:process_thought を使用します IF エラーが不明瞭である → WebSearch → Parallel Search で調査し、ドキュメントで確認します IF その領域に慣れていない → codebase_search で調べ、推測しないでください IF 修正が簡単すぎるように思える → 症状ではなく根本原因に対処していることを確認します IF コンテキストが散らかっている → 要約を作成し、50% の時点で再開します IF 複数の仮説がある → それぞれを明示的に評価します（裏付ける証拠／反証する証拠） IF 類似コードが動作している → codebase_search/read_file で該当箇所を見つけて差分を確認します IF 成功を宣言する → 変更した行を示し、修正前は失敗し修正後は成功することをテストします IF 修正が複数ファイルにまたがる → 該当箇所をすべて検索し、修正します IF ライブラリの動作を前提としている → Context7:get-library-docs で確認します

完了前の品質チェック

バグの修正を宣言する前に、次の点を確認してください。

• 根本原因を特定し、文書化している
• 症状ではなく原因に対処する修正になっている
• すべての該当箇所を修正している（プロジェクト全体を検索済み）
• 既存のコードパターンに従っている
• 元の症状が解消されている
• リグレッションが発生していない
• 関連する条件下でテストやログにより検証している
• ドキュメントやテストを更新している（コメント、ドキュメント、リグレッションテスト）

参考資料

• reference/root-cause-framework.md
• reference/antipatterns.md