# Survey Codebase

> Use when an Issue was triaged L and the affected areas of the codebase must be enumerated exhaustively before clarify-expectation splits it — when "did we check everywhere?" must be answerable, not just claimed

- Skill: `yannsugi/survey-codebase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yannsugi/survey-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yannsugi/survey-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yannsugi (https://skillmd.com/u/yannsugi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yannsugi/survey-codebase

---


# survey-codebase

L 判定の Issue に対する網羅的調査。最大分割の前提条件。
思想は `${CLAUDE_PLUGIN_ROOT}/DESIGN.md` の「解明フェーズの規律」(トリアージ L の項)と「通底する原則」(システムマップ)。

**核**: 網羅の定義を先に固定し、自己申告を検証可能にする。産物は影響マップであって、原因の推理ではない。

## 入力契約

読んでよいもの: 対象 Issue 本文とトリアージ結果、`docs/system-map.md`(あれば起点にする)、コードベース全域、`${CLAUDE_PLUGIN_ROOT}/DESIGN.md`。
読んではいけないもの: 他 Issue の実現案・PR。Issue 本文にある原因の推測(読んでも、それを追う調査にしない)。

## 手順

1. **マトリクスを先に作る** 領域(FE / BE / IaC / データ)× 観点(参照 / 変更 / 暗黙の依存)の12セル。調査を始める前に全セルを「未着手」で置く。repo に無い領域も行を消さず「確認済み(該当なし)」で埋める(無いことも網羅の一部)
   - 参照: この Issue の入口・データを読んでいる場所
   - 変更: 書き換えている場所
   - 暗黙の依存: 設定・環境変数・スケジュール・命名規約・ドキュメントの手順など、コードの参照関係に現れない結びつき
2. **起点を決める** `docs/system-map.md` があれば該当項目から差分確認(全量探索は初回のみ)。無ければ初回として全量探索
3. **領域ごとに探索する** 該当領域が2つ以上あり、かつ領域ごとにディレクトリが分かれている(目安: 合計200ファイル超)なら、領域ごとにサブエージェントを並列に出して集約する。各エージェントには担当領域の3セルだけを渡す。小さければ単独で全量を読む
4. **セルを消し込む** 各セルを次のいずれかにする。「確認済み」には何を見て確認したかを必ず添える(ファイルパスまたは検索語)
   - 確認済み(該当あり): 見た場所と、該当箇所の一覧
   - 確認済み(該当なし): 見た場所
   - 未確認: 理由(アクセスできない・時間切れ・判断不能)
5. **影響マップを書く** 該当ありのセルから、影響箇所を「場所 / 何が影響するか / 確信度(高・中・低)」で列挙。確信度は Issue の入口・データとその場所のつながりの確かさ(高=直接扱っている、中=経由・間接、低=関係しうる)。原因である可能性の高さではない。同じ事実が複数箇所に定義されている(二重管理)箇所は明示する
6. **未確認セルを⚠候補として渡す** clarify-expectation が期待の⚠に浮上させ、ゲート①で人間の目に入るようにする
7. **システムマップへ還元する** `docs/system-map.md` を更新(無ければ作る)。書くのは場所・関係・鮮度だけ。要約や調査結果の転記はしない
8. **出力** マトリクス・影響マップ・未確認一覧を成果物として利用者に提示する。`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 相対パス