codemap

Codemap

Codemap は、あらゆるコードベースのアーキテクチャに関する情報をすぐに提供します。意図を分類し、リスクを検出し、関連するスキルを照合して、作業対象を追跡します。すべてフックによって自動的に行われます。

Codemap は、プロジェクトごとの設定も適切な状態に保つ必要があります。リポジトリで初めて使うときや、出力が明らかにノイズの多いときは、詳しく分析する前に .codemap/config.json を調整してください。そうすることで、以降の呼び出しでアセット優先ではなくコード優先の結果が得られます。

コマンド

codemap .                       # Project structure and top files
codemap --deps                  # Dependency flow (imports/functions/hubs)
codemap --diff                  # Changes vs main branch
codemap --diff --ref <branch>   # Changes vs specific branch
codemap --importers <file>      # Who imports this file? Is it a hub?
codemap handoff .               # Build + save handoff artifact
codemap handoff --latest .      # Read latest saved handoff
codemap handoff --json .        # Machine-readable handoff payload
codemap skill list              # Show available skills with descriptions
codemap skill show <name>       # Get full skill instructions
codemap skill init              # Create custom skill template
codemap config show             # Show current project config
codemap context                 # Universal JSON context envelope
codemap context --for "prompt"  # With pre-classified intent + matched skills
codemap context --compact       # Minimal for token-constrained agents
codemap serve --port 9471       # HTTP API for non-MCP integrations

初回セットアップ

リポジトリで Codemap の詳しい分析を始める前に、次の手順を実行してください。

1. .codemap/config.json を確認します。
2. ファイルが存在しない場合、明らかにひな形のままの場合、または使用している技術スタックに対して明らかにノイズが多い場合は、codemap skill show config-setup を実行して手順に従います。
3. 設定を書き込む、または改善したあと、codemap . と codemap --deps を再実行します。

設定はリポジトリの記憶として扱ってください。一度調整すれば、以降の Codemap の呼び出しにも自動的に反映されます。

設定のセットアップや調整が必要な兆候：

• .codemap/config.json が存在しない
• 実際のプロジェクトに合わせた調整がなく、自動検出された汎用的な only の値だけが設定されている
• 大規模な非コードディレクトリがツリー出力の大部分を占めている
• 技術スタック固有のノイズがソース構造を覆い隠している（.xcassets、スクリーンショット、PDF、トレーニングデータ、フィクスチャ、生成ファイル、モデル、ベンダーディレクトリ）
• リポジトリの技術スタックが明らかなのに、設定に反映されていない

使用するタイミング

次の場合は必ず codemap . を実行します：

• 新しいタスクや機能に取りかかるとき
• ユーザーから「X はどこにありますか？」や「Y を処理するファイルはどれですか？」と聞かれたとき
• プロジェクトの構造や整理方法について聞かれたとき
• 変更を加える前にコードベースを理解する必要があるとき

次の場合は必ず codemap --deps を実行します：

• ユーザーから「X はどのように動きますか？」や「Y を使っているのは何ですか？」と聞かれたとき
• コードのリファクタリングや移動をするとき
• インポートや依存関係を追跡する必要があるとき
• ハブファイル（最も多くインポートされているファイル）を見つけるとき

次の場合は必ず codemap --diff を実行します：

• ユーザーから「何が変わりましたか？」や「何を変更しましたか？」と聞かれたとき
• コミット前に変更をレビューするとき
• ブランチで行った作業を要約するとき

次の場合は必ず codemap --importers <file> を実行します：

• ファイルを編集する前に、そのファイルがハブかどうか確認するとき
• 変更の影響範囲を把握する必要があるとき
• リファクタリングするか、そのままにするか判断するとき

次の場合は codemap skill show <name> を実行します：

• prompt-submit フックに、`` 内に照合されたスキルが表示されたとき
• 特定のタスク（ハブの編集、リファクタリング、テスト）についてガイダンスが必要なとき
• リスクレベルが中または高のとき

次の場合は codemap skill show config-setup を実行します：

• リポジトリに .codemap/config.json がないとき
• 設定が実際のプロジェクトポリシーではなく、最低限の初期設定に見えるとき
• 大規模な非コードディレクトリによって Codemap の出力が散らかっているとき
• このリポジトリに特化した、より適切な判断を Codemap にさせたいとき

次の場合は codemap context を実行します：

• Codemap の情報を別のツールにパイプで渡すとき
• プロジェクトの状態を構造化された JSON で要約する必要があるとき
• コードを認識したコンテキストを利用する自動化を構築するとき

次の場合は codemap handoff を実行します：

• エージェント（Claude、Codex、Cursor）を切り替えるとき
• 休憩後に作業を再開するとき
• ユーザーから「次のエージェントに伝えておくべきことは何ですか？」と聞かれたとき

フックの出力

prompt-submit フックはすべてのメッセージで実行され、次の情報を提供します：

Skills matched: hub-safety, refactor — run `codemap skill show <name>` for guidance

• 意図のカテゴリ：リファクタリング、バグ修正、機能開発、調査、テスト、ドキュメント
• リスクレベル：低（ハブなし）、中（ハブ 1 個）、高（ハブ 2 個以上、またはインポーター 8 個以上）
• スキルはプル型です：表示されるのは名前だけです。本文全体を見るには codemap skill show を実行します

組み込みスキル

スキル	取得するタイミング
config-setup	.codemap/config.json がない、ひな形のまま、またはノイズが多い場合
hub-safety	ほかのファイルから 3 回以上インポートされているファイルを編集するとき
refactor	コードの構成変更、名前変更、移動をするとき
test-first	テストや TDD ワークフローを作成するとき
explore	コードの仕組みを理解するとき
handoff	AI エージェントを切り替えるとき

出力の解釈

ツリービュー（codemap .）

• 星（⭐）は、ソースファイルのサイズ上位 5 件を示します
• サブディレクトリが 1 つだけのディレクトリは、フラット化して表示されます

依存関係フロー（codemap --deps）

• 外部依存関係を言語別にグループ化
• ファイル間のつながりを示す内部インポートチェーン
• HUBS セクションに、最も多くインポートされているファイル（インポート元が3つ以上）を表示

差分モード（codemap --diff）

• (new) = 未追跡、✎ = 変更済み、(+N -M) = 変更された行数
• 警告アイコンはハブファイル（影響度が高いファイル）を示します

インポート元（codemap --importers <file>）

• このファイルをインポートしているすべてのファイルを表示
• ハブの状態を示します（インポート元が3つ以上 = 影響度が高い）

コンテキストエンベロープ（codemap context）

• プロジェクトのメタデータ、意図、作業セット、一致したスキル、ハンドオフ参照を含む JSON
• --compact を指定すると、スキルを除外し、作業セットを制限してトークンを節約します

MCP ツール

codemap MCP サーバーが設定されている場合、次のツールを利用できます。

ツール	用途
get_structure	プロジェクトツリー
get_dependencies	依存関係フローとハブ
get_diff	影響度を含む変更ファイル
find_file	ファイル名で検索
get_importers	ファイルのインポート元
get_hubs	すべてのハブファイルを一覧表示
get_file_context	1つのファイルの完全なコンテキスト
get_handoff	ハンドオフ成果物の作成／読み取り
get_working_set	このセッションで編集したファイル
list_skills	利用可能なスキル（メタデータ）
get_skill	スキルの完全な指示
get_activity	最近のコーディングアクティビティ
start_watch / stop_watch	デーモンの制御
status	MCP 接続の確認
list_projects	プロジェクトの検出

HTTP API

codemap serve の実行中は、次のエンドポイントを利用できます。

エンドポイント	戻り値
GET /api/context?intent=...	コンテキストエンベロープ
GET /api/skills	すべてのスキルのメタデータ
GET /api/skills/<name>	スキルの完全な内容
GET /api/working-set	現在の作業セット
GET /api/health	サーバーの稼働状況