debug-methodical

Debug-Methodical — 4 フェーズでのデバッグ

obra/superpowers に触発されたスキルです。目的：「動くまで適当に修正を試す」のではなく、厳密な手法を徹底します。

**黄金律：**安定して再現できないバグは、十分に理解されていないバグです。再現する前に修正してはいけません。

4 つのフェーズ（厳守、順番どおり）

フェーズ 1：再現

**目的：**制御された環境で、バグを意図どおりに発生させます。

チェックリスト：

• 再現手順を文書化する（Given/When/Then）
• 再現が決定論的である（連続 3 回以上、同じ結果になる）
• 環境が分離されている（ローカル、コンテナ、テスト環境）
• 入力が最小限である（データ／手順をできる限り少なくする）
• 正確なバージョン／コミットを特定する

成果物：バグを明らかにして失敗する自動テスト（回帰テスト）。

危険信号：「自分のマシンでは動く」／「たまに失敗する」→ 再現が不十分なため、フェーズ 1 に戻ります。

フェーズ 2：切り分け

**目的：**単なる症状ではなく、根本原因を特定します。

手法：

• 二分探索：git bisect で問題のコミットを特定する
• コードの**二分探索：**コードの半分をコメントアウトし、繰り返す
• **プリントデバッグ：**境界（関数の入力／出力）にログを追加する
• **デバッガー：**ブレークポイント、ステップ実行、変数の監視
• 環境の比較：「動く環境」と「壊れる環境」では何が違うのか？
• **前提を疑う：**最初の仮説は正しいのか？

チェックリスト：

• 原因を特定する（正確な行／条件／入力）
• なぜそうなるのか説明する（単に何が起きるかだけではない）
• 因果関係を文書化する（A が B を引き起こし、B が C を引き起こす）
• 同じバグが引き起こす可能性のある別の現象を特定する

**危険信号：**根拠なしに「X だと思う」→ 計測を追加して、切り分けに戻ります。

フェーズ 3：修正

**目的：**変更を最小限に抑えて、根本原因を修正します。

チェックリスト：

• 適切なレベルで修正する（症状ではなく根本原因）
• 変更を最小限にする（KISS、ルール 05 を参照）
• 他の機能に副作用がない
• 「念のため」の修正や推測による修正をしない（ルール 23 Karpathy を参照）
• 適切なレイヤーで修正する（ドメイン／インフラ／UI）

危険信号：

• エラーを隠すために try/catch を追加する修正 → 原因ではなく症状に対処しています
• 既存のテストを不審な形で変更する必要がある修正
• なぜ動くのか分からないまま「動く」修正

フェーズ 4：検証

**目的：**修正が機能し、他に何も壊していないことを証明します。

チェックリスト：

• 回帰テスト（フェーズ 1）が通る
• テストスイート全体が通る
• 手動で再現しても、バグが発生しない
• 近接するシナリオ（近いエッジケース）をテストする
• パフォーマンスが低下していない
• 重大な問題の場合、ステージング環境のログ／監視を確認する

**回帰ルール：**フェーズ 1 で作成したテストは、永久にコードベースに残します。修正したバグを再発させてはいけません（/qa:regression を参照）。

重大なアンチパターン

アンチパターン	なぜ問題なのか
手当たり次第のデバッグ	10 個の変更を適当に加えても、何も学べません
症状の修正	別の形でバグが再発します
再現を省略する	修正を検証できません
検証を省略する	「動くはず」では不十分です — 証明できなければ完了ではありません
回帰テストがない	3 か月後にバグが再発します
汎用的な catch (Exception) による修正	他のバグを隠してしまいます
修正とリファクタリングを混ぜたコミット	git bisect ができなくなります

高度な手法

並行処理のバグの場合

• インターリーブを強制する（戦略的なスリープ、ストレステスト）
• スレッドダンプ／プロファイラー
• 不変条件がアトミックに保たれているか確認する

統合のバグの場合

• 正確なペイロードのスナップショット（HAR、ログ）
• curl または最小限のクライアントで再現する
• 依存関係の正確なバージョンを確認する

不安定なテストへの対応

• 100 回実行して、不安定さの発生率を測定します
• 依存要因（時間、順序、共有リソース）を特定します
• 修正チケットなしでテストに @Flaky を付けることは絶対に避けてください

Claude Craft との統合

• /qa:tdd — TDD モードでバグを修正します（最初に失敗するテストを作成）
• /qa:fix — QA バグを自動修正します
• /qa:regression — 回帰テストの登録簿です
• Skill atomic-tasks — デバッグを原子的なフェーズに分割します
• Rule 07 (testing) — バグ修正には回帰テストが必須です

リソース

• obra/superpowers
• Rule .claude/rules/07-testing.md
• Command /qa:tdd, /qa:regression

---

最終更新日： 2026-04-15 バージョン： 1.0.0