bug-hunt

バグハントスキル

クイックリファレンス： 4 フェーズの調査（根本原因 → パターン → 仮説 → 修正）。出力先：.agents/research/YYYY-MM-DD-bug-*.md

このワークフローを必ず実行してください。説明するだけではいけません。

根本原因を見つけて完全な修正を設計するための体系的な調査、または問題が起きる前に隠れたバグを見つけるための先行監査です。

必要条件：

• 書き込み可能な .agents/ 出力ディレクトリ。存在しない場合は明示的に作成してください
• フォローアップの課題を作成する場合は、課題追跡用の bd CLI（beads）

モード

モード	呼び出し方法	使用する状況
調査	/bug-hunt <symptom>	既知のバグまたは障害がある場合
監査	/bug-hunt --audit <scope>	隠れたバグを先行して洗い出す場合

調査モードでは、以下の 4 フェーズ構成を使用します。監査モードでは、体系的な読み取りと分類を行います。監査モードを参照してください。

---

4 フェーズ構成（調査モード）

フェーズ	焦点	出力
1. 根本原因	実際のバグの場所を特定する	file:line、コミット
2. パターン	動作する実例と比較する	特定した差異
3. 仮説	仮説を 1 つ立てて検証する	各項目の合否
4. 実装	症状ではなく根本原因を修正する	検証済みの修正

失敗カテゴリの分類と 3 回失敗のルールについては、skills/bug-hunt/references/failure-categories.md を読んでください。

複数回の調査が必要な監査やリリース前の一斉調査では、skills/bug-hunt/references/audit-fix-rescan-cycle.md（複数回の調査手法）を参照し、終了時期の判断には skills/bug-hunt/references/convergence-criteria.md を使用してください。

新鮮な視点での再調査が必要な先行調査では、references/multi-pass-bug-hunting.md も読み込んでください。

コマンドの停止、デッドロック、リトライの集中、サブプロセスのブロック、またはハングが発生している場合は、コードを変更する前に references/deadlock-and-hang-triage.md を読み込んでください。

対象プロセスが稼働中、ハング中、またはデバッガーでの観察時にのみ再現する場合は、アタッチする前、または ptrace/sysctl の設定を変更する前に references/debugger-attach-triage.md を読み込んでください。

実行手順

/bug-hunt <symptom> が指定された場合：

---

ステップ 0：過去のバグに関するコンテキストを読み込む

調査の前に、このコードベースの該当領域に関する過去の知見を確認します。

if command -v ao &>/dev/null; then
    ao lookup --query "<symptom-keywords> bug patterns" --limit 3 2>/dev/null || true
fi

取得した知見を適用する： 知見が返された場合は、それぞれが現在のバグに当てはまるか確認してください。当てはまる知見（例：同じ領域で過去に発生したバグ、既知の壊れやすいパターン）は、調査の手掛かりとして含め、ファイル名を記載してください。次を記録します：ao metrics cite "<path>" --type applied 2>/dev/null || true

過去のバグ報告、修正パターン、既知の壊れやすい領域を活用すると、調査時間を短縮できます。

---

フェーズ 1：根本原因の調査

ステップ 1.1：バグを確認する

まず、問題を再現します。

• 期待される動作は何ですか？
• 実際の動作は何ですか？
• 一貫して再現できますか？

エラーメッセージを注意深く読んでください。 読み飛ばしたり、ざっと目を通すだけにしたりしてはいけません。

バグを再現できない場合は、先に情報を集めてください。

ステップ 1.2：症状の発生箇所を特定する

バグが現れる場所を見つけます。

# Search for error messages
grep -r "<error-text>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

# Search for function/variable names
grep -r "<relevant-name>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

ステップ 1.3：Git の履歴を調査する

バグがいつ、どのように導入されたかを特定します。

# When was the file last changed?
git log --oneline -10 -- <file>

# What changed recently?
git diff HEAD~10 -- <file>

# Who changed it and why?
git blame <file> | grep -A2 -B2 "<suspicious-line>"

# Search for related commits
git log --oneline --grep="<keyword>" | head -10

ステップ 1.4：実行経路を追跡する

TASK TOOL（subagent_type: "Explore"）を使用して実行経路を追跡します。

• バグが現れるエントリーポイントを見つける
• 逆方向に追跡し、不正なデータや状態の発生元を見つける
• 経路上のすべての関数と、それらに加えられた最近の変更を特定する
• 次の内容を返す：実行経路、根本原因の可能性が高い箇所、原因となった変更

ステップ 1.5：根本原因を特定する

追跡結果に基づいて、次を特定します。

• 何が誤っているか（実際のバグ）
• どこにあるか（file:line）
• いつ導入されたか（コミット）
• なぜ起きるか（ロジックの誤り）

---

フェーズ 2：パターン分析

ステップ 2.1：動作する実例を見つける

コードベース内で、同様の機能が正しく動作する例を検索します。

# Find similar patterns
grep -r "<working-pattern>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

ステップ 2.2：リファレンスと比較する

以下の間にあるすべての差異を特定します。

• 壊れているコード
• 動作するリファレンス

差異をそれぞれ記録します。

---

フェーズ 3：仮説とテスト

ステップ 3.1：仮説を 1 つ立てる

仮説を明確に述べます。

「Y が原因で、X が間違っていると思います」

**一度に立てる仮説は 1 つだけです。**複数の推測を組み合わせないでください。

ステップ 3.2：最小限の変更でテストする

仮説をテストするために、可能な限り最小限の変更を行います。

• 成功した場合 → フェーズ 4 に進みます
• 失敗した場合 → 失敗を記録し、新しい仮説を立てます

ステップ 3.3：失敗回数を確認する

skills/bug-hunt/references/failure-categories.md に従って失敗回数を確認します。カウント対象となる失敗が 3 回に達したら、アーキテクチャレビューにエスカレーションします。

---

フェーズ 4：実装

ステップ 4.1：修正を設計する

コードを書く前に、修正を設計します。

• 何を変更する必要がありますか？
• エッジケースにはどのようなものがありますか？
• この修正によって、ほかの何かが壊れませんか？
• 更新が必要なテストはありますか？

ステップ 4.2：失敗するテストを作成する（可能な場合）

修正前に、バグを示すテストを作成します。

ステップ 4.3：修正を 1 つ実装する

症状ではなく、根本原因を修正します。

ステップ 4.4：修正を検証する

失敗していたテストを実行します。今度は成功するはずです。

バグが複雑度の高い関数にある場合は、再発を防ぐため、修正後に /refactor を検討してください。

---

監査モード

--audit を指定して実行すると、bug-hunt は先回りしてコードを精査します。症状は必要ありません。まだ報告されていないバグを探します。

/bug-hunt --audit cli/internal/goals/     # audit a package
/bug-hunt --audit src/auth/               # audit a directory
/bug-hunt --audit .                        # audit recent changes in repo

監査ステップ 1：対象範囲

対象範囲の引数から、対象ファイルを特定します。

# Find source files in scope
find <scope> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50

対象範囲が . または広範囲（50 ファイル超）の場合は、最近変更されたファイルに絞り込みます。

git log --since="2 weeks ago" --name-only --pretty=format: -- <scope> | sort -u | head -30

監査ステップ 2：体系的に読み込む

対象範囲内のすべてのファイルを、1 行ずつ読みます。ファイルごとに、次の点を確認します。

カテゴリ	確認する項目
リソースリーク	閉じられていないハンドル、孤立したプロセス、クリーンアップ／defer の欠落
文字列の安全性	UTF-8 のバイト単位での切り詰め、サニタイズされていない入力
デッドコード	到達不能な分岐、未使用の定数、シャドーイングされた変数
ハードコードされた値	パス、URL、ほかの環境では動作しないリポジトリ固有の前提
エッジケース	空の入力、nil／ゼロ値、境界条件
並行処理	保護されていない共有状態、ゴルーチンのリーク、シグナルハンドラーの欠落
エラー処理	握りつぶされたエラー、コンテキストの欠落、誤ったエラー型

**重要な心得：**1 行ずつ読みます。流し読みしないでください。5 件のバグを発見し、仮説の失敗が 0 件だった実証済みの手法は、ヒューリスティックなスキャンではなく、慎重に読むことに基づいています。

大規模な対象範囲では、TASK TOOL（subagent_type: "Explore"）を使い、ファイルを複数のエージェントに分割します。

監査ステップ 3：発見事項を分類する

発見事項ごとに、重大度を割り当てます。

重大度	基準	例
HIGH	データ損失、セキュリティ、リソースリーク、プロセスの孤立	ゾンビプロセス、SQL インジェクション、ファイルハンドルのリーク
MEDIUM	誤った出力、不適切なデフォルト値、気づかれないデータ破損	UTF-8 の切り詰め、ハードコードされたパス、誤ったエラーコード
LOW	デッドコード、見た目の問題、軽微な不整合	到達不能な分岐、未使用のインポート、スタイル違反

パフォーマンスのバグ（遅いクエリ、メモリリーク、N+1）は、詳細な分析のため /perf にエスカレーションします。

監査ステップ 4：監査レポートを作成する

監査レポートの形式については、skills/bug-hunt/references/audit-report-template.md を読んでください。

.agents/research/YYYY-MM-DD-bug-<scope-slug>.md に書き込みます。

概要表を添えてユーザーに報告します。

| # | Bug | Severity | File | Fix |
|---|-----|----------|------|-----|
| 1 | <description> | HIGH | <file:line> | <proposed fix> |

失敗回数（仮説テストで確認できなかった回数）を記載します。失敗が 0 回なら、監査は問題なしです。

バグ発見のテストピラミッドのモード（BF1～BF5）

--audit を実行する際は、バグ発見に役立つテストカバレッジが不足していないか確認します。

BF4 — カオス／ネガティブテスト（バグ発見能力が最も高い）： 外部呼び出し（API、データベース、ファイルシステム）を行うすべてのファイルについて、以下を確認します。

• タイムアウトを注入するテストがある
• 接続失敗をテストするものがある
• 権限拒否をテストするものがある
• 破損した入力をテストするものがある

いずれかの境界で失敗注入が行われていない場合は、指摘事項として報告します（重大度：高）。

BF5 — スクリプトの機能テスト： 外部ツール（oc、kubectl、helm）を呼び出すすべての .sh スクリプトについて、以下を確認します。

• スタブベースの機能テストがある
• JSON 出力スキーマが検証されている
• 正常系と異常系の両方のスタブパスがテストされている

スクリプトに機能テストがない場合は、指摘事項として報告します（重大度：中）。

BF1 — プロパティベーステスト： データ変換（解析／レンダリング／シリアライズ）ごとに、以下を確認します。

• ランダム化した入力を使うプロパティテストがある

参考： BF レベルの定義と各言語のツールについては、/standards のテストピラミッド標準を参照してください。

---

Step 5: バグレポートを作成する

バグレポートのテンプレートについては、skills/bug-hunt/references/bug-report-template.md を参照してください。

Step 6: ユーザーに報告する

ユーザーに以下を伝えます。

1. 根本原因を特定したかどうか
2. バグの場所（ファイル：行）
3. 修正案
4. バグレポートの場所
5. 発生した失敗の件数と種類
6. 次のステップ：修正を実装するか、さらに情報を集めるか

主なルール

• まず再現する — バグが存在することを確認します
• Git の履歴を調べる — 変更の経緯を把握します
• 体系的に追跡する — 実行経路をたどります
• 根本原因を特定する — 症状だけにとどめません
• 修正前に設計する — 解決策を検討します
• 調査結果を記録する — バグレポートを作成します

簡易チェック

よくあるバグのパターン：

• オフバイワンエラー
• Null／undefined の処理
• 競合状態
• 型の不一致
• エラー処理の欠落
• 状態がリセットされない
• キャッシュの問題

例

テスト失敗の調査

ユーザーの依頼： /bug-hunt "tests failing on CI but pass locally"

実行内容：

1. エージェントが CI のログとローカルのテスト出力を確認して、バグを検証します
2. エージェントが Git の履歴を調べ、テストファイルへの最近の変更を特定します
3. エージェントが実行経路をたどり、環境固有の違いを特定します
4. エージェントが環境変数の不足について仮説を立てます
5. エージェントがその変数を未設定にして、ローカルで失敗するテストを作成します
6. エージェントが既定値を追加して修正します
7. バグレポートが .agents/research/2026-02-13-bug-test-failure.md に作成されます

結果： CI の設定に ENV 変数が不足していたことが根本原因として特定されました。修正が適用され、検証済みです。

リグレッションの原因究明

ユーザーの依頼： /bug-hunt "feature X broke after yesterday's deployment"

実行内容：

1. エージェントが現在の状態で問題を再現します
2. エージェントが git log --since="2 days ago" を使って最近のコミットを調べます
3. エージェントが git bisect を使って、問題を引き起こしたコミットを特定します
4. エージェントが問題のあるコードと、コードベース内の正常な実装例を比較します
5. エージェントが導入された型の不一致について仮説を立てます
6. エージェントが最小限の修正を実装し、既存のテストで検証します
7. バグレポートにコミット sha、根本原因、修正内容を記録します

結果： リグレッションの原因はコミット abc1234 と特定されました。検証ロジックの型変換エラーが根本原因から修正されました。

予防的なコード監査

ユーザーの依頼： /bug-hunt --audit cli/internal/goals/

実行内容：

1. エージェントが対象を goals パッケージ内のすべての .go ファイルに絞ります
2. エージェントが各ファイルを1行ずつ読み、リソースリーク、文字列の安全性、デッドコードなどを確認します
3. エージェントが5件のバグを発見します：ゾンビプロセスグループ（高）、UTF-8 の切り詰め（中）、ハードコードされたパス（中）、段落区切りの消失（低）、到達不能な分岐（低）
4. すべての指摘事項を初回の確認で検証 — 仮説の失敗は0件
5. 監査レポートが .agents/research/2026-02-24-bug-goals-go.md に作成されます

結果： 重大度、ファイル：行、修正案を含む具体的なバグが5件見つかりました。デバッグなしで実装に着手できます。

トラブルシューティング

問題	原因	解決策
バグを再現できない	環境に関する情報が不十分、または断続的に発生する問題	具体的な手順、環境変数、入力データをユーザーに尋ねます。競合状態やタイミングの問題がないか確認します。
Git の履歴調査でコミットが多すぎる	検索範囲が広い、または変更頻度の高いファイル	--since フラグで期間を絞り、git blame で特定の関数に注目し、関連キーワードを含むコミットメッセージを検索します。
仮説の検証中に3回の失敗上限に達した	誤った仮説が複数ある、または根本原因が複雑	アーキテクチャレビューにエスカレーションします。失敗がカウント対象かどうかを判断するため、failure-categories.md を読みます。ドメインの専門家に意見を求めることも検討します。
バグ報告に重要な情報が不足している	調査が不完全、または手順が省略されている	4つのフェーズがすべて完了していることを確認します。ファイル名と行番号を特定して根本原因を明らかにします。該当コミットの git blame が実行されたことを確認します。

参考ドキュメント

• references/bug-hunt.feature — 実行可能な仕様：4フェーズの根本原因調査、fix-the-cause-not-symptom、--audit による一括調査、引用付き成果物（soc-qk4b）

• references/audit-report-template.md

• references/bug-report-template.md

• references/failure-categories.md

• references/audit-fix-rescan-cycle.md

• references/convergence-criteria.md

• references/multi-pass-bug-hunting.md

• references/deadlock-and-hang-triage.md

• references/debugger-attach-triage.md

関連項目

• refactor — 複雑でバグが発生しやすいコードを安全にリファクタリングします
• perf — パフォーマンスに関するバグのプロファイリングを行います