codebase-exploration

コードベースの探索

目的

体系的なコードベースの探索と調査に特化しています。高度な検索手法、パターン認識、コード分析を活用して、見慣れないコードをすばやく理解し、特定の実装を見つけ、アーキテクチャのパターンを把握し、コードの場所に関する質問に回答します。

使用する場面

• 初めて見慣れないコードベースを探索する
• 特定の機能がどこに実装されているかを見つけたい
• コードベース全体から特定のパターンの例を探したい
• コンポーネント間の連携を理解したい
• 特定の API やパターンの使用箇所をすべて特定したい
• アーキテクチャ上の構成を把握したい
• プロジェクト内の類似コードを見つけたい
• 「X はどこにありますか？」「Y があるファイルはどれですか？」「Z を行うコードを見つけて」といった質問

クイックスタート

このスキルを呼び出す場面：

• 初めて見慣れないコードベースを探索する
• 特定の機能がどこに実装されているかを見つけたい
• コードベース全体から特定のパターンの例を探したい
• コンポーネント間の連携を理解したい
• 「X はどこにありますか？」「Y があるファイルはどれですか？」「Z を行うコードを見つけて」といった質問

呼び出さない場面：

• 既知のバグをデバッグする場合（debugger-skill を使用）
• コードをリファクタリングする場合（refactoring-specialist-skill を使用）
• コード品質をレビューする場合（code-reviewer-skill を使用）
• コードをゼロから新たに書く場合（適切な開発者向けスキルを使用）

詳細度のレベル

クイック（速く、概要を把握）

• ファイル構成の概要
• 高レベルのパターンマッチング
• ディレクトリ構成
• 主なエントリーポイント
• 約30秒

中程度（深さのバランスが取れた調査）

• ファイルの詳細な調査
• ファイルをまたいだパターンの発見
• アーキテクチャのマッピング
• 一般的なパターンの分析
• 約2～3分

非常に詳細（深く掘り下げる調査）

• 網羅的なコード分析
• 複雑なパターンマッチング
• 依存関係の追跡
• エッジケースの発見
• 約5～10分

判断のフレームワーク

検索戦略の選択

質問の種類	検索戦略
「ユーザー認証はどこにありますか？」	auth 関連のキーワードとログインパターンを検索
「データの流れはどのようになっていますか？」	モデル、サービス、コントローラーのパターンを特定
「X API を処理するファイルはどれですか？」	エンドポイントとルート定義を検索
「データベースクエリをすべて見つけて」	ORM のパターンや SQL のキーワードを検索
「エラー処理の場所を特定して」	try-catch やエラークラスを検索

ツールの選択

ツール	最適な用途	例
grep/rg	テキストパターンのマッチング	rg "function handleAuth"
find/fd	ファイル名やパスのマッチング	fd -e ts auth
ast-grep	コード構造のマッチング	ast-grep --pattern "class $NAME"
LSP ツール	シンボルや参照の検索	lsp_find_references
git log	履歴の把握	git log --name-only

質問の種類に応じたアプローチ

「X はどこに実装されていますか？」

1. 名前で X を検索する：rg "X|x"
2. 関連語を検索する：rg "related|terms"
3. ありそうな場所を確認する：ls src/X/
4. テストを検索する：rg "X" tests/

「Y はどのように動作しますか？」

1. Y の定義を見つける
2. Y の使用箇所を見つける
3. 処理の流れを追う
4. 依存関係を理解する

「Z を使用しているファイルはどれですか？」

1. Z のインポートを検索する
2. LSP の参照検索を使用する
3. Z のメソッドが呼び出されている箇所を検索する

主な機能

検索戦略

パターンベースの検索

• 命名規則から見つける
• コードパターンから特定する
• アーキテクチャ上の目印から見つける
• ファイル構成から特定する

コンテキストを考慮した検索

• コード間の関係を理解する
• 依存関係をマッピングする
• 実行フローを追跡する
• 関連コンポーネントを見つける

複数の切り口による調査

• 機能から検索する
• 構造から検索する
• 命名から検索する
• パターンから検索する

探索ワークフロー

ステップ 1：方向性を定める

• 何を探していますか？
• なぜそれが必要ですか？
• どの程度の詳細さが必要ですか？
• どの詳細度レベルが適切ですか？

ステップ 2：構成を把握する

• トップレベルの構成を特定する
• 重要な目印（エントリーポイント、設定ファイル）を見つける
• ディレクトリの命名パターンを確認する

ステップ 3：検索を実行する

• 適切なツールを選ぶ
• 複数の切り口から検索する
• 調査結果を記録する

ステップ 4：分析と統合

• 関連性を見つけます
• パターンを特定します
• 調査結果に優先順位を付けます

ベストプラクティス

広く調べてから絞り込む

1. 最初に：全体像を把握します（tree -L 2、ls -la src/）
2. 次に：パターンを特定します（fd -e ts、rg -c "class|function"）
3. 最後に：特定の領域に絞り込みます

複数の検索方法を使う

• 名前で検索：fd auth
• 内容で検索：rg "authentication"
• 構造で検索：ast-grep --pattern "class $NAME"
• シンボルで検索：lsp_workspace_symbols

手がかりをたどる

1. インポートを確認して依存関係を見つけます
2. LSP を使って参照を検索します
3. ファイルの場所からアーキテクチャの手がかりを探します
4. 背景を把握するために Git の履歴を確認します

作業しながら記録する

# Authentication Flow
1. Entry: src/middleware/auth.ts
2. Token validation: src/services/jwt.service.ts  
3. User lookup: src/repositories/user.repository.ts
4. Guards: src/guards/auth.guard.ts

アンチパターン

• 文脈なしに検索しない：まず、何を探しているのかを理解します
• ファイル構造を無視しない：常にディレクトリ構成を確認します
• 単一の検索方法に頼らない：複数の方法を使います
• テストを忘れない：実際の使用例を確認するため、テストファイルを検索します
• 設定ファイルを見落とさない：早い段階で設定を確認します

関連スキル

• 調査でバグが見つかった場合は、[[debugger-skill]] を使います
• 発見したパターンを評価するには、[[architect-reviewer-skill]] を使います
• 見つかったコードを改善するには、[[refactoring-specialist-skill]] を使います
• 複雑なアーキテクチャ上の問題には、[[technical-advisory-skill]] を使います

追加リソース

• 詳細な技術資料：REFERENCE.md を参照してください
• コード例とパターン：EXAMPLES.md を参照してください