codemap について
codemapは、codemap CLIでリポジトリを探索する開発者向けのスキルです。セマンティック検索、シンボル検索、依存関係分析に加え、インデックス状態の確認と絞り込んだクエリを重視し、MCPサーバー経由の利用方法も説明します。
主な機能
- 01ベクトルとBM25によるコード検索
- 02関数・クラス・型シンボルの検索
- 03ファイル概要と依存関係の表示
- 04重要度・結合度・循環依存の分析
- 05インデックス状態確認と変更監視
活用シーン
- 01意図に沿って実装箇所を検索
- 02ファイルの依存先と依存元を追跡
- 03リポジトリのアーキテクチャ健全性を確認
MCP 対応
codemapは`codemap serve`でMCPサーバーとして動作し、コード検索などのツールをエージェントに公開できます。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/codemapを入力して読み込まれたか確認します。
詳細
必ず守るルール：
- 結果を利用する前に、
codemap --versionとcodemap statusを確認してください。 - プロジェクトに codemap の設定がない場合は、
codemap initの実行前に確認してください。 - 質問に答えられる、最も範囲の狭い codemap コマンドを優先してください。
- 構造化された結果を解釈する必要がある場合は、機械可読な出力を優先してください。
- codemap を有効にするためだけに、Claude やプロジェクトの設定を自動編集しないでください。
codemap
入力
$request：検索または分析の目的
目的
次のような場合に、プレーンテキスト検索よりも精度の高い結果で、アーキテクチャやコードの探索に関する質問に答えるため、codemap CLI を使用します。
- 意図が文字列の完全一致ではなく、意味に基づく場合
- シンボルの検索が重要な場合
- 依存関係の方向が重要な場合
- ファイルの重要度や結合度が重要な場合
ステップ 0：利用可能かどうかとインデックスの状態を確認する
次を確認します。
codemap --versioncodemap status
codemap が見つからない場合は、npm install -g @ulpi/codemap でインストールするようユーザーに伝え、そこで停止してください。自動的にインストールしないでください。
リポジトリが設定されていない場合：
codemap initによってプロジェクト設定が作成されることを説明します。codemap initを実行する前に確認してください。- 設定後、
codemap indexを実行します。
リポジトリの設定は済んでいるものの、古くなっている場合は、codemap index で再インデックス化します。
成功基準：現在のリポジトリに対して、codemap インデックスが正しく機能していること。
ステップ 1：適切なコマンドを選ぶ
コマンドリファレンス
| コマンド | 説明 | 主なフラグ |
|---|---|---|
codemap search <query> | ベクトル検索と BM25 を組み合わせたコード検索 | -l N、--json |
codemap symbols <query> | 名前から関数、クラス、型を検索 | -l N、--json |
codemap summary <file> | シンボルとサイズを含むファイルの概要 | --json |
codemap deps <file> | このファイルが使用する依存先（インポート先） | --json |
codemap dependents <file> | このファイルを使用する依存元（インポート元） | --json |
codemap rank [file] | PageRank による重要度スコア | -l N、--json |
codemap coupling | 求心性／遠心性結合度と不安定度 | --module <path>、-l N、--json |
codemap cycles | 循環依存関係を検出 | --json |
codemap graph-stats | 依存関係グラフの集計統計 | --json |
codemap index | プロジェクトを検索用にインデックス化 | --full |
codemap status | インデックスの統計情報を表示 | --json |
codemap watch | ファイル変更時にインデックスをライブ更新 | --debounce <ms> |
codemap read <file> | ソース全体（または行範囲）を読み取る | --start、--end |
codemap serve | stdio 経由で MCP サーバーを起動 |
用途別のコマンド
| 目的 | コマンド |
|---|---|
| X を実行するコードを検索する | codemap search "X" |
| X という名前の関数／クラスを検索する | codemap symbols "X" |
| このファイルが依存しているものを調べる | codemap deps <file> |
| このファイルに依存しているものを調べる | codemap dependents <file> |
| 最も重要なファイルを調べる | codemap rank |
| 循環依存関係を調べる | codemap cycles |
| ファイルの概要を確認する | codemap summary <file> |
| アーキテクチャの健全性を確認する | codemap coupling |
| プロジェクトの統計情報を確認する | codemap graph-stats |
説明文ではなく構造化された出力が必要な場合は、--json を優先してください。
成功基準：取得しすぎることなく、コマンドが実際の質問に合致していること。
ステップ 2：必要最小限の codemap クエリを実行する
まずは範囲を絞ります。
- 結果数を制限する
- ファイルやモジュールがわかっている場合は指定する
- 一度に分析する観点は 1 つにする
最初の結果が明らかに不十分な場合に限り、対象を広げます。
ルール：
- 「念のため」に codemap の全コマンドを実行しないでください。
- 正確な
grepのほうが簡単な場合は、codemap を使わないでください。 - 探索後にファイルの内容が必要になった場合は、結果に含まれる具体的なファイルパスに対して
Readを使用してください。
成功基準：探索には codemap を使用し、Read は関連する特定のファイルにのみ使用して回答すること。
ステップ 3：判断しやすい形式で結果を報告する
以下を要約します。
- 使用したコマンド
- そのコマンドが適切だった理由
- 最も関連性の高い結果
- 開く価値のある関連ファイル
有力な結果がない場合は、確かな結果があるかのように装わず、その旨を明示します。
成功基準：ユーザーが codemap の生出力を解析せずに、結果に基づいて行動できます。
MCP の代替手段
Codemap は MCP サーバーとしても実行できるため、AI エージェントは Bash を使わずにツールへ直接アクセスできます。
claude mcp add codemap codemap serve
これにより、mcp__codemap__search_code、mcp__codemap__search_symbols などのツールが公開されます。このファイルの CLI スキルでは Bash コマンドを使用します。MCP ではエージェントがネイティブなツール呼び出しを行えます。どちらも利用できます。エージェントのセットアップに合った方を使用してください。
ガードレール
- 権限を追加するために設定ファイルを自動変更しないでください。
- 新しい設定を作成する場合は、ユーザーの承認なしに
codemap initを実行しないでください。 - 古いインデックスや空のインデックスを信頼できるものとして扱わないでください。
- テキスト検索で十分な場合に、単純な完全一致ツールを codemap に置き換えないでください。
- これは汎用的な探索スキルです。
disable-model-invocationを追加しないでください。
出力の要件
次の内容を報告します。
- codemap の利用可否とインデックスの状態
- 選択したコマンド
- 最も関連性の高いヒットまたはグラフの結果
- さらに詳しく読む必要がある場合に、次に開くファイル
- インデックスがない、結果が弱いなどの制約