Codebase exploration

コードベース探索・理解

目的

• 「全部理解してから着手する」は不可能かつ不要。目的に応じた範囲を素早く深く理解する
• 暗黙の規約・設計上の前提を帰納的に抽出し、既存スタイルと一貫した変更を行えるようにする
• 調査結果を記録し、次の調査者(将来の自分を含む)の時間を節約する

使うタイミング

• 初めて触るリポジトリに着手するとき
• 機能追加・バグ修正の前に構造と規約を把握したいとき
• 変更が広範な影響を持つ可能性があり、事前に影響範囲を調べたいとき
• コードレビューで変更の文脈を理解したいとき

進め方

1. 目的を定義する — 「何のために読むか」を一文で書く。目的なしに読み始めると端から全ファイルを読む罠に落ちる
2. ドキュメントから始める(ただし鵜呑みにしない) — README・CLAUDE.md・docs/ を読む。コードとの乖離を前提に、仮説として受け取る
3. ディレクトリ構成とパッケージ定義を読む — package.json / go.mod / Cargo.toml 等で技術スタック・依存ライブラリを把握。ディレクトリ名から層の分け方を読む
4. エントリポイントを辿る — main.*・ルーティング定義・CLIコマンドの登録箇所を探し、アプリの全体像を掴む
5. データモデルを確認する — DBスキーマ・主要エンティティ・型定義を読む。アプリの語彙(ドメイン用語)はここに凝縮されている
6. 代表的な1機能を縦に追う — リクエスト受付→バリデーション→ビジネスロジック→DB→レスポンスの流れを1本通しで追う
7. 動かして確認する — セットアップしてテストを実行する。テストは最も正直なドキュメント。ログ・デバッガで実際の実行パスを確認する
8. 規約を帰納する — 類似した実装を3つ探し、命名・層の分け方・エラー処理・テストの書き方の共通パターンを抽出する。1つだけ見ると例外かもしれない
9. git履歴を参照する — 最近頻繁に変更されているファイルは重要か問題児。git blame で「なぜこうなったか」のコミットを辿る
10. 調査メモを記録する — わかったこととわからないことリストを両方管理する([[session-handoff]])

変更前の影響調査

機能追加・修正・リファクタリングの前に必ず実施する。

1. 呼び出し元を全件検索する — 変更対象の関数・型・定数・設定キーを grep / LSP の「参照を検索」で網羅的に列挙する
2. 公開インタフェースか内部実装かを区別する — 公開APIや共有ユーティリティ・型の変更は波及範囲が広い。内部の private 関数は影響が狭い
3. テストの有無を確認する — 対象コードにテストがない場合は、変更前に特性テスト(現状の振る舞いを固定するテスト)を書く([[refactoring]])
4. 依存方向を確認する — 変更先が他のモジュール・サービスに依存されていないか、インタフェース契約を壊さないかを確認する
5. 影響ファイル一覧を成果物に含める — 調査メモの「影響範囲」セクションに列挙し、レビュアーと共有する

成果物テンプレート

# コードベース調査メモ

作成日: YYYY-MM-DD
調査目的: （例: ユーザー通知機能の追加前に通知周辺の構造を把握する）

## 技術スタック

- 言語/FW: 
- 主要ライブラリ: 
- DB: 
- テストFW: 

## ディレクトリ構成の要点

src/ api/ # ルーティング・ハンドラ domain/ # ビジネスロジック・エンティティ infra/ # DB・外部API接続 ...

## 主要データモデル

- User: id, email, role, created_at
- Order: id, user_id, status, items[]
- （ドメイン用語として重要な型を列挙）

## 追った機能フロー

例: 注文作成 POST /orders
1. api/orders.go → バリデーション
2. domain/order_service.go → 在庫チェック・価格計算
3. infra/order_repo.go → DBへINSERT
4. イベント発行 → 通知サービスへ非同期送信

## 抽出した規約

- 命名: エンティティはドメイン層、リポジトリは infra 層で定義
- エラー処理: domain はドメインエラー型を返す。api 層でHTTPステータスにマップ
- テスト: ユニットテストは *_test.go、モックは testify/mock
- その他: 

## 影響範囲（変更前調査）

変更対象: `domain/user.go` の `UpdateEmail()`
呼び出し元:
- api/users.go:L42
- domain/auth_service.go:L89
- tests/user_test.go:L15

## リスク箇所・注意点

- OrderService が UserService に直接依存しており循環依存に近い
- 設定ファイルが複数環境で共有されている（変更時に全環境へ影響）

## わからないことリスト

- [ ] NotificationService が同期か非同期か不明
- [ ] staging 環境での email 送信がどこで抑制されているか未確認
- [ ] マイグレーションの実行タイミング（デプロイ前/後）

チェックリスト

• 調査目的を一文で定義した
• ドキュメントを「仮説」として読み、コードで検証した
• データモデル(スキーマ・主要エンティティ)を確認した
• 1機能をリクエストからレスポンスまで縦に追った
• 類似実装を3つ見て規約を帰納した
• テストを実行して動作を確認した
• git履歴で変更頻度の高いファイルを確認した
• 変更前に呼び出し元を全件検索した
• テストがない対象には特性テストを書いた
• 「わかったこと」と「わからないことリスト」を両方記録した
• 調査メモをCLAUDE.mdまたはREADMEに還元した

アンチパターン

• 端から全ファイルを読む: 目的なしに読み始めると無限に読み続ける。目的→スコープを先に決める
• READMEを鵜呑みにする: 陳腐化していることが多い。コードで検証するまでは仮説扱い
• 動かさずに読むだけ: 静的読解は誤読しやすい。テストを実行し、ログで実際の経路を確認する
• 調査結果をメモしない: 数日後に再調査する羽目になる。10分のメモで1時間を節約できる
• 1例だけ見て規約と思い込む: 例外かもしれない。3例見て共通パターンを抽出する
• 影響範囲を感覚で見積もる: grep せずに「ここしか使われていないだろう」と決め込むと見落とす
• 「わからないこと」を放置する: 曖昧なまま実装すると手戻りが大きい。リストに上げて早期に解消する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	タスク例
司令塔(メインモデル)	調査目的の定義・調査範囲の判断・サブエージェントへの指示書作成・調査結果の統合と矛盾解消・調査メモの最終化
Opus相当	アーキテクチャ上の問題・設計意図の推察・複雑な依存関係の整理・リスク箇所の深堀り分析
Sonnet相当	コードベース調査の主力実働(ディレクトリ構成把握・機能フロー追跡・規約抽出・影響範囲調査)
Haiku相当	ファイル検索・grep・依存グラフの収集・呼び出し元の列挙・git log/blame の実行

観点別ファンアウトの例

調査範囲が広い場合は以下の4観点でサブエージェントを並列起動し、司令塔が統合する。

# 司令塔が以下を並列起動する
Agent(API層担当, Sonnet相当):
  「src/api/ 配下のルーティング定義・ハンドラ・バリデーション・エラーマップを調査し、
  エンドポイント一覧と共通パターンを報告せよ。」

Agent(データ層担当, Sonnet相当):
  「DBスキーマ・マイグレーションファイル・リポジトリ層の実装を調査し、
  主要エンティティとCRUDパターンを報告せよ。」

Agent(テスト担当, Haiku相当):
  「テストファイルの構成・テストヘルパー・モックの使い方を調査し、
  テストの書き方の規約を報告せよ。」

Agent(設定・インフラ担当, Haiku相当):
  「環境変数・設定ファイル・docker-compose・CI設定を調査し、
  実行環境の構成と環境差異を報告せよ。」

# 全エージェント完了後、司令塔が統合
- 各層の規約・命名規則を横断的に確認し矛盾を解消する
- 「わからないことリスト」を集約し、優先度をつける
- 成果物テンプレートに従い調査メモを完成させる

関連スキル

• [[orchestration]] — 並列調査のファンアウト共通原則
• [[session-handoff]] — 調査メモの引き継ぎ・セッション間の知識継続
• [[documentation]] — 調査結果をCLAUDE.md・READMEに還元する
• [[refactoring]] — 変更前の特性テスト作成・技術的負債の把握
• [[debugging]] — バグ修正目的の調査で発見した問題箇所の深堀り
• [[code-review]] — レビュー文脈での変更意図の把握
• [[architecture-design]] — 把握した構造の設計上の評価
• [[implementation]] — 調査を経た上での機能追加・修正の実施