Bug Hunt Skill | Agent Skills

Bug Hunt

概要

Gitのstagedまたはunstaged差分に最低1件の実害バグが存在するという既知の前提から開始し、変更コードを敵対的に検証してバグを特定する。

目的は指摘数を増やすことではない。変更前には成立していた契約を変更後が破る入力・状態・順序・環境を見つけ、実コード・実行結果・明確な論証のいずれかで立証することである。

トリガー条件

ユーザーが対象のstaged/unstaged差分には実害バグが必ずあると明示し、その欠陥の特定を依頼した場合だけ使用する。「必ず1件バグがある」「バグの間違い探し」など、バグの存在を前提とする表現が該当する。バグの存在が未確認なら、差分の厳密な探索を望む依頼でも通常レビュー (deep-review) を使う。通常レビュー中にバグが確認された場合は、その時点で証拠を報告する。

非対象

バグの存在を明示していない、見逃し調査や差分を壊す条件の探索
コーディング規約、命名、整形だけの指摘
性能改善だけを目的とする調査
既知の障害の根本原因分析。これは systematic-debugging を使う
修正実装。バグ特定後、ユーザーが修正まで求めた場合のみ別工程として行う

成功条件

完了には以下をすべて満たす必要がある。

stagedまたはunstagedの対象差分を確定している
明示された「最低1件」の前提について証拠を検証し、見つからない場合も捏造せず調査範囲と限界を報告している
バグが発生する具体的な入力、状態、操作順序、または環境条件を示している
変更行との因果関係を示している
再現テスト、実行ログ、既存契約との矛盾、または同等に強い証拠がある
誤検知候補を最終結果へ混ぜていない

「怪しい」「可能性がある」「念のため」は成功に数えない。

実害バグの定義

以下のいずれかを満たすものを実害バグとする。

正常入力で誤った値、表示、永続化、レスポンスを返す
例外、クラッシュ、無限ループ、デッドロック、ハングを起こす
認可、認証、機密性、完全性を破る
データ欠損、重複、破壊、不整合を起こす
後方互換性、公開契約、型契約、DB制約を破る
有効な境界値、並行実行、再試行、部分失敗を誤処理する
既存の必須ユースケースを成立しなくする

以下は単独では実害バグに含めない。

命名、整形、コメント、好みの設計
根拠のない将来リスク
到達不能な理論上の懸念
仕様上許容される挙動
差分と無関係な既存バグ

鉄則

差分を読む前に結論を作らない。
対象のリスクに応じて探索軸を切り替え、証拠が得られない場合は探索の限界を明示する。
証拠のない候補をバグとして報告しない。
テストが通ることを正しさの証明とみなさない。テストの欠落条件を探す。
変更行だけでなく、その呼び出し元・呼び出し先・型・スキーマ・テストを読む。
修正案を先に考えない。先に壊れる条件を確定する。
無関係なファイルを変更しない。調査用変更は完了前に戻す。

入力範囲の確定

最初にGitリポジトリと変更範囲を確認する。

git rev-parse --show-toplevel
git status --short
git diff --name-status
git diff --cached --name-status

対象は以下の和集合とする。

unstaged: git diff
staged: git diff --cached

未追跡ファイルも対象に含める。git status --short で ?? のファイルを確認し、内容を直接読む。

差分が空の場合は、バグ探索を開始せず「対象差分なし」と報告する。Git管理外のファイルを勝手に対象へ拡張しない。

手順

Phase 1: 変更意図と契約の復元

差分をファイル単位で読む前に、変更全体の意図を1-3文で仮置きする。

git diff --find-renames --find-copies
git diff --cached --find-renames --find-copies

各変更について次を特定する。

変更前に成立していた振る舞い
変更後に成立させたい振る舞い
入出力、例外、状態遷移、永続化、副作用の契約
呼び出し側が暗黙に依存する前提
既存テストが守っている条件と守っていない条件

仕様書、型定義、interface、schema、migration、API定義、既存テストを一次ソースとして読む。コミットメッセージや変数名だけで意図を決めない。

Phase 2: 差分の危険面を列挙

対象ファイルごとに、references/review-lenses.md の観点を使って「壊れ得る条件」を列挙する。

差分に該当する観点から検証可能な仮説を選ぶ。該当しない観点を件数のために埋めない。

値: null、空、0、負数、最大値、Unicode、時刻、丸め
状態: 初回、再実行、途中失敗、既存データ、競合、順序逆転
契約: 型、API、DB、例外、戻り値、認可、後方互換性
接続: 呼び出し元/先、別レイヤー、設定、環境差、外部サービス

仮説は検証可能な形式にする。

変更Xにより、条件Yのとき、契約Zが破られ、観測結果Wになる。

Phase 3: 独立探索

並行性、データフロー、契約・セキュリティなど、独立した専門調査で検出力が上がる時だけ subagentへ分ける。人数と観点は差分のリスク、利用可能なtool contract、調査の重複を考慮して決める。親が十分に読める場合やdelegationが使えない場合は親が確認する。

調査者へは対象差分と前提、担当観点、証拠・反証条件、修正禁止を明示する。他の調査結果を鵜呑みにせず、親が変更行、発生条件、観測結果を一次ソースで再確認する。有効な候補がなければ「なし」と報告し、無理に捏造しない。

Phase 4: 候補の実証

候補を強い順に検証する。優先順位は以下。

既存テストを狭く実行して再現
一時的な最小再現テストを追加してREDを確認
実行コマンド、REPL、最小入力で再現
型検査、lint、静的解析で契約違反を確認
実コードと一次契約の論理的矛盾を提示

テストコマンドはリポジトリ内の一次情報から特定する。

AGENTS.md / CLAUDE.md
README* / CONTRIBUTING*
package manifest
CI設定
Makefile / task runner

依存追加、外部書き込み、DB破壊、ネットワーク副作用、特権操作は実行しない。必要なら、静的証拠までで止めて制約を明示する。

一時的に作成したテスト、ログ、fixture、編集は、証拠を記録後に必ず元へ戻す。ユーザーの既存差分は戻さない。

Phase 5: 反証レビュー

有力候補ごとに、別agentまたは独立した再確認パスで反証を試みる。

確認項目:

仕様上意図された挙動ではないか
呼び出し元で事前条件が保証されていないか
到達不能な分岐ではないか
既存コード由来で、今回の差分が原因ではないのではないか
テストfixture固有の偽陽性ではないか
言語・FW・DBの実際の挙動を誤認していないか

反証に耐えた候補だけを確定バグへ昇格する。

Phase 6: 見つからない場合

確定バグが0件なら、未確認の前提や到達可能な範囲を見直し、異なる観点の追加調査に実益があるか判断する。調査が尽きた場合は「前提に反して確定できなかった」と記し、調査済み範囲、未検証の制約と未確定候補を区別して報告する。明示された最低1件の前提を満たしたかのように報告してはならない。

バグ確度ゲート

差分因果、発生可能性、実害、証拠、反証の結果を根拠として示す。出力形式の確度欄は残すが、恣意的な合計点だけで再現済みの実害バグを棄却しない。推測しかないものは点数にかかわらず確定バグとして報告しない。

出力形式

最初に確定バグを重要度順で示す。前置きや一般論を先に置かない。

## 確定バグ

### [重大度] 一行要約
- 対象: `path/to/file.ext:line`
- 差分: staged | unstaged | untracked
- 発生条件: [具体的な入力・状態・順序・環境]
- 実際の結果: [観測される誤動作]
- 期待結果: [守るべき契約]
- 原因: [変更行から結果までの因果]
- 証拠: [失敗テスト、コマンド出力、ログ、契約との矛盾]
- 確度: [根拠に基づく0-10]/10

## 検証内容
- 実行: `...`
- 結果: ...
- 未実行: ... (理由)

## 調査範囲
- staged: ...
- unstaged: ...
- untracked: ...
- 参照した周辺コード: ...

重大度:

CRITICAL: セキュリティ侵害、不可逆な大規模データ破壊
HIGH: 主要機能停止、データ破壊、広範な誤処理
MEDIUM: 有効な条件で機能不全、部分的なデータ不整合
LOW: 限定条件での実害ある不具合

アンチパターン

lint警告や命名問題をバグとして水増しする
「必ずある」という前提から、証拠なしに候補を確定する
差分だけを眺め、周辺契約を読まない
テスト成功をもって探索を終了する
最初に見つけた怪しい箇所へ固執する
複数agentへ同じ曖昧な指示を渡し、同じ結論を複製する
agentの報告を親が検証せず採用する
修正を加えてから、何が壊れていたか逆算する
調査用コードを残す
差分外の既存バグを成果として報告する

Agent Skills: Bug Hunt

Install this agent skill to your local

Skill Files