フェーズ 2: 調査

目的

実装に必要な情報を網羅的に収集し、既存コードの構造・依存関係・制約を把握する。車輪の再発明を防ぎ、既存のパターンとの一貫性を確保する。

開始条件

• 承認済みの docs/workflow/requirements.md に目的・範囲・受入条件がある
• 対象コード、関連資料、利用中バージョンを読み取りできる

入力成果物

• docs/workflow/requirements.md
• 対象リポジトリ、プロジェクト規約、依存定義、公式ドキュメント

実行手順

1. 受入条件ごとに調査する問いを作る
2. 既存実装、呼び出し元、テスト、設定を根拠付きで追跡する
3. 外部仕様を利用中バージョンの公式資料で確認する
4. 選択肢、制約、影響範囲、未解決リスクを統合する

期待成果物

• docs/workflow/research.md
• 問いごとの結論、根拠、影響範囲、既存パターン、残る仮定

終了条件

• 既存実装・影響ファイル・依存・制約が根拠付きで記録されている
• 計画を止める不明点がなく、残るリスクと仮定が明示されている

失敗時の戻り先

• 調査範囲を決められない場合は要件理解へ戻る
• 根拠不足なら問いと情報源を見直し、このフェーズを続ける
• 情報へアクセスできない場合は仮定・影響・判断者を明記して解消を依頼する

Before / After

Before: 従来のやり方

• 手動でファイルを開いてコードを理解
• 関連するドキュメントを探して個別に読む
• 影響範囲の見落としで後から手戻り
• 「こんな機能が既にあった」と実装後に発覚

After: ツール活用後

• AIエージェントがコードベース全体を瞬時にマッピング
• 依存関係・影響範囲が自動で可視化
• 外部ドキュメントの検索と要約が自動化
• GitHub リポジトリ検索で既存の実装例を即座に発見

レベル別アプローチ

Beginner

Level 1 プレイブック

入力例

入力: docs/workflow/requirements.md
問い: 順序とツール情報の正規データはどこか。

コマンド / プロンプト

claude

要件書を読み、コードは変更せずに調査してください。受入条件ごとに
関連ファイル、現在のデータ源、依存、既存テスト、制約、リスクを
根拠のパス付きで docs/workflow/research.md に保存してください。

生成物例

# 調査報告
## 順序
- 正規候補: workflow frontmatter の order
- 重複箇所: 一覧、詳細、マップ
## ツール情報
- 正規候補: keyTools
- 所属検証: src/lib/tool-catalog.ts

検証

test -s docs/workflow/research.md
rg -n '根拠|影響範囲|未解決リスク' docs/workflow/research.md

出口判定

• 各結論に根拠があり、影響範囲を説明できる
• 計画を止める不明点が残っていない

Claude Code の基本ツールでコードベースを調査する。

# ファイル検索
Claude Code > src/ ディレクトリの構造を教えて
              Glob ツールで src/**/*.ts を検索

# コード内容検索
Claude Code > 認証関連のコードを全て見つけて
              Grep ツールで "auth" を検索

# LSP によるコードインテリジェンス
Claude Code > この関数の定義場所を教えて
              LSP ツールで goto definition を実行

# Web 検索でドキュメント確認
Claude Code > React 19 の Server Components の仕様を調べて
              WebSearch ツールで最新ドキュメントを検索

手順:

1. Glob でディレクトリ構造を把握
2. Grep で関連コードを検索
3. Read で重要ファイルの内容を確認
4. WebSearch で外部ドキュメントを参照

Intermediate

Superpowers の systematic-debugging の調査フェーズと OMC の explore エージェントを活用。

# OMC: explore エージェント（高速なコードベース検索）
> このコードベースで認証がどう実装されているか調べて
# explore エージェント（haiku）が高速にマッピング

# OMC: external-context（外部ドキュメントの読み込み）
/oh-my-claudecode:external-context
> Next.js App Router のドキュメントを読み込んで

# Superpowers: systematic-debugging の調査手法
# Root Cause Investigation の証拠収集パターンを調査に応用
# エラー読み取り → 再現 → 変更確認 → データフロートレース

# OMC: document-specialist エージェント
> Supabase の RLS ポリシーの書き方を調べて
# リポジトリの docs を優先し、見つからなければ Web にフォールバック

手順:

1. OMC explore エージェントでコードベース全体を高速マッピング
2. OMC document-specialist でフレームワーク/API のドキュメントを検索
3. Superpowers の調査パターンで体系的に証拠を収集
4. Context7 MCP で最新のライブラリドキュメントを取得

Advanced

OMC の並列調査と ECC の search-first で多角的にリサーチ。

# ECC: search-first（リサーチファースト開発）
/search-first
> この機能を実装する前に、既存の解決策を調査して
# GitHub リポジトリ検索 → パッケージレジストリ確認 → ドキュメント参照

# OMC: ultrawork（最大並列で調査）
ulw 調査タスクを並列実行して:
1. 認証フローの既存実装を確認
2. データベーススキーマの依存関係をマッピング
3. 外部APIの仕様を確認
4. テストカバレッジの現状を分析

# ECC: documentation-lookup スキル
> Stripe API の Payment Intent の仕様を調べて

# OMC: sciomc（データ分析・統計的推論）
/oh-my-claudecode:sciomc
> パフォーマンスメトリクスからボトルネックを特定して

手順:

1. ECC search-first で既存の解決策を横断検索
2. OMC ultrawork で複数の調査タスクを並列実行
3. OMC scientist エージェントでデータ分析
4. Context7 MCP でライブラリの最新ドキュメントを取得
5. 調査結果を OMC notepad / project memory に永続化

ベストプラクティス

1. 実装前に既存コードを確認する -- ECC の search-first は「実装前に既存の解決策を調べる」をワークフロー化している。手動でのコード検索を省略しない
2. 調査結果をメモリに永続化 -- OMC notepad の priority セクションに重要な調査結果を記録する。セッション終了後も参照可能
3. 並列で効率化 -- 独立した調査タスクは OMC ultrawork か Superpowers dispatching-parallel-agents で並列実行する
4. 公式ドキュメントを優先 -- OMC document-specialist は「リポジトリの docs を優先し、Web にフォールバック」する順序を自動化している
5. LSP を活用 -- Claude Code の LSP 統合で、定義ジャンプ・参照検索・診断を活用し、手動でのファイル検索を減らす

よくある罠

調査不足で実装開始

「大体わかった」で実装を始めると、既存のパターンとの不整合や、既にある機能の再実装が発生する。ECC の /search-first はこれを防止するためのもの。

外部ドキュメントのバージョン不一致

WebSearch で見つけたドキュメントが古いバージョンの可能性がある。Context7 MCP や OMC document-specialist は最新ドキュメントの取得を自動化する。

調査結果がセッション間で失われる

調査で得た知見を CLAUDE.md や project memory に保存しないと、次回のセッションで同じ調査を繰り返すことになる。OMC notepad や ECC continuous-learning で永続化する。

影響範囲の見落とし

Grep でキーワード検索だけでは、間接的な依存関係を見落とす。LSP の find references や goto definition で、呼び出し元まで含めて影響範囲を確認する。

並列調査の結果統合を忘れる

OMC ultrawork で並列調査を実行した後、結果の統合・矛盾の解消を忘れがち。調査完了後には必ず結果の統合レビューを行う。