| name | investigation-rules |
| description | 調査レポート作成のルール。否定的結論のエビデンス要件、残課題の記載フォーマット、ハルシネーション防止のための裏取り原則を扱う。DB調査に限らずコードベース調査・仕様調査一般に適用。 |
| when_to_use | 調査・デバッグ・不具合レポートを作成するとき。「ない」「該当なし」等の否定的結論を出すときは必ず参照。Triggers: '調査', 'デバッグ', '不具合レポート', '原因調査', 'investigation', 'root cause', 'カラムがない', '該当コードがない', 'データがない' |
調査レポート作成ルール
不具合調査・データ調査・仕様調査でレポートを作成する際のルール。コード読解だけに頼らず、必ず実行結果・出力・実データで裏取りする。
否定的結論にはエビデンス必須
「カラムがない」「データがない」「関数が呼ばれていない」「該当コードがない」等の 否定的な結論 を書く場合、必ず実行結果をエビデンスとして添付すること。
なぜこのルールが必要か
AIは「もっともらしいが間違った推論」をしがちで、コード読解だけで「ない」と断定して誤判断を招きやすい。事例として、外部テーブルの一部カラムだけを見て「該当カラムなし」と結論づけたが、実際には別名のカラムにデータが存在していた、という判断ミスが典型。
具体的な裏取り方法
| 主張の種類 | 必須エビデンス |
|---|
| DB: カラムが存在しない | SHOW COLUMNS FROM table_name / DESCRIBE の結果 |
| DB: データが存在しない | SELECT COUNT(*) FROM table WHERE ... の結果 |
| DB: テーブルが存在しない | SHOW TABLES LIKE '%keyword%' の結果 |
| コード: 関数/シンボルが存在しない | grep -rn 'name' . / LSP検索 / Serena find_symbol の結果 |
| コード: 呼び出し箇所がない | find_referencing_symbols / grep の結果 |
| 設定: 値が存在しない | 設定ファイルのdiff / env / config コマンド出力 |
| ログ: エラーが出ていない | grep / 検索ツールのクエリと結果期間 |
レポートへの記載例
### 残課題
| 課題 | 概要 | エビデンス | 優先度 |
|------|------|-----------|--------|
| 外部API の retry 未実装 | Xクライアントで retry ハンドリングが無い | `grep -rn "retry\|Retry" src/client/x/` → 0件 | 中 |
| status=deleted の件数 | 論理削除レコードが残存 | `SELECT COUNT(*) FROM ... WHERE status='deleted'` → 2,341件 | 低 |
やってはいけないこと
- コードを読んだだけで「このカラムは存在しない」と断定する
- 1つのテーブル/ファイルだけ見て「データに問題はない」と結論づける
- 外部テーブルの一部のカラムだけ見て「他にはない」と判断する（全カラムを確認する）
- エビデンスなしで残課題の優先度を「低」にする（誤判断の典型）
外部データ調査の原則
外部API/外部テーブル/サードパーティデータソースを調査する際は、全体構造を必ず確認する。
SHOW COLUMNS FROM external_source_table;
SELECT column_name, COUNT(*) FROM table GROUP BY column_name;
外部データは外部システム由来でカラム名・値域が予測しづらいため、コードから逆引きするだけでは見落とす。
ハルシネーション防止チェックリスト
推論で埋めず、必ず以下を実行して裏取りする:
| チェック項目 | 方法 |
|---|
| カラム/フィールドが存在するか | SHOW COLUMNS / スキーマ定義ファイルを開く |
| データが存在するか | SELECT COUNT(*) WHERE ... / サンプルレコード取得 |
| 型が一致するか | DB定義とアプリコード両方を確認（Eloquent $casts、dataclass型等） |
| FK/制約が存在するか | マイグレーション履歴を追跡（追加→削除→再追加の変遷を確認） |
| 論理削除ポリシーは何か | SoftDeletes / deleted_at の有無を確認 |
| 環境差異がないか | dev/staging/prod で同じクエリを実行して比較 |
調査結果の書き方テンプレート
## 症状
何がどう間違っているか（定量的に、エビデンス付きで）
## 調査経緯
1. 仮説1: xxx → クエリ/コマンドで確認 → 否定/肯定
2. 仮説2: yyy → ...
## 根本原因
コードレベルでどこが問題か（ファイル名:行番号で特定）
## エビデンス
SQL/コマンド実行結果をそのまま貼る
## 修正方針
どのフェーズで何を直すか（多層防御の観点）
## 検証手順
修正後にどう確認するか（回帰テスト含む）
SQLクエリ結果・コマンド出力をそのまま貼り、「コードを読んだ推測」と「実行して確認した事実」を明確に区別する。
関連スキル
/ndf:problem-solving — 根本原因分析と多層防御の原則
