yannsugi survey-codebase
L 判定の Issue に対する網羅的調査。最大分割の前提条件。
思想は ${CLAUDE_PLUGIN_ROOT}/DESIGN.md の「解明フェーズの規律」(トリアージ L の項)と「通底する原則」(システムマップ)。
核: 網羅の定義を先に固定し、自己申告を検証可能にする。産物は影響マップであって、原因の推理ではない。
入力契約
読んでよいもの: 対象 Issue 本文とトリアージ結果、docs/system-map.md(あれば起点にする)、コードベース全域、${CLAUDE_PLUGIN_ROOT}/DESIGN.md。
読んではいけないもの: 他 Issue の実現案・PR。Issue 本文にある原因の推測(読んでも、それを追う調査にしない)。
手順
- マトリクスを先に作る 領域(FE / BE / IaC / データ)× 観点(参照 / 変更 / 暗黙の依存)の12セル。調査を始める前に全セルを「未着手」で置く。repo に無い領域も行を消さず「確認済み(該当なし)」で埋める(無いことも網羅の一部)
- 参照: この Issue の入口・データを読んでいる場所
- 変更: 書き換えている場所
- 暗黙の依存: 設定・環境変数・スケジュール・命名規約・ドキュメントの手順など、コードの参照関係に現れない結びつき
- 起点を決める
docs/system-map.mdがあれば該当項目から差分確認(全量探索は初回のみ)。無ければ初回として全量探索 - 領域ごとに探索する 該当領域が2つ以上あり、かつ領域ごとにディレクトリが分かれている(目安: 合計200ファイル超)なら、領域ごとにサブエージェントを並列に出して集約する。各エージェントには担当領域の3セルだけを渡す。小さければ単独で全量を読む
- セルを消し込む 各セルを次のいずれかにする。「確認済み」には何を見て確認したかを必ず添える(ファイルパスまたは検索語)
- 確認済み(該当あり): 見た場所と、該当箇所の一覧
- 確認済み(該当なし): 見た場所
- 未確認: 理由(アクセスできない・時間切れ・判断不能)
- 影響マップを書く 該当ありのセルから、影響箇所を「場所 / 何が影響するか / 確信度(高・中・低)」で列挙。確信度は Issue の入口・データとその場所のつながりの確かさ(高=直接扱っている、中=経由・間接、低=関係しうる)。原因である可能性の高さではない。同じ事実が複数箇所に定義されている(二重管理)箇所は明示する
- 未確認セルを⚠候補として渡す clarify-expectation が期待の⚠に浮上させ、ゲート①で人間の目に入るようにする
- システムマップへ還元する
docs/system-map.mdを更新(無ければ作る)。書くのは場所・関係・鮮度だけ。要約や調査結果の転記はしない - 出力 マトリクス・影響マップ・未確認一覧を成果物として利用者に提示する。
gh issue comment <n>での投稿とマップのコミットは、利用者が明示的に指示した場合にのみ実行する
試走でローカルファイル <name>.md を対象にする場合は、同じディレクトリの <name>.survey.md に書き、手順8の投稿とコミットは行わない。マップの出力先は呼び出し側の指定があればそれを優先し、無ければ対象 dir の docs/system-map.md。成果物の置き場所は指示どおりでよいが、本文中で参照するパスは repo 相対にする。
システムマップの書式
# system-map
<!-- 索引であって本文ではない。要約を書かない。鮮度が古い項目は「未確認」に降格する -->
| 項目 | 場所 | 関係 | 最終確認 (Issue / 日付) | 状態 |
|---|---|---|---|---|
| ベンダー権限定義 | scripts/create-vendors.sh, README.md#M2 | 二重管理 | #12 / 2026-09-14 | 確認済み |
出力書式
## 網羅的調査
### マトリクス
| 領域 \ 観点 | 参照 | 変更 | 暗黙の依存 |
|---|---|---|---|
| FE | 該当なし(src/ に UI 無し) | … | … |
### 影響マップ
| 場所 | 何が影響するか | 確信度 |
### 未確認(⚠候補)
- …
よくある失敗
- マトリクスを最後に埋める → 網羅の定義が後付けになる。先に12セル置く
- 「H1 最有力仮説」「切り分け順」「次の一手」を書く → 原因の推理は実現案の仕事。影響の場所だけ書く
- 「全ファイル読んだ」と書いてセルが無い → 自己申告。セルごとに見た場所を残す
- マップに調査結果の要約を書く → マップは索引。場所と関係と鮮度のみ
- 出力にローカルの絶対パスを書く → repo 相対パス