LayerMap

LayerMap

English · 中文

LayerMap は、関数を呼び出している箇所と、その関数を変更したときに影響を受ける箇所を、HTTP ルートに至るまで、1 回の呼び出しでコーディングエージェントに知らせます。 リクエスト数を最大 15 回に制限した場合、エージェントは LayerMap を使うと影響を受けるエンドポイントの 97.9% を特定できたのに対し、使わない場合は 58.8% でした。制限なしの場合、0.1.5 の再実行では Claude Code のコストが 33% 減少しました（ベンチマーク）。

名前から tree-sitter で推測するのではなく、各言語のコンパイラーまたは型チェッカーで解決します。 TypeScript、JavaScript、Go、Python、Java では、インターフェース、基底クラス、テンプレート、デコレーターを介した呼び出しも、コンパイラーが解決するのと同じようにリンクされます。

_{Miniflux での実際の Claude Code セッションを再生したものです。1 回のマップ呼び出しですべてのエンドポイントを見つけ、その後エージェントがソースコードで確認します。}

コーディングエージェント向けの、コードベースの階層マップです。LayerMap は Claude Code、Codex、CodeBuddy Code、Pi、DeepSeek Harness などの MCP クライアントに読み取り専用ツールを提供し、通常なら何十回もの検索を通じてエージェントが調べる内容を、1 回の呼び出しで回答します。

• これを呼び出しているのはどこで、変更すると何に影響しますか？ 呼び出し元を最大 8 階層までたどり、起点となる HTTP ルート、ハンドラー、ジョブ、コマンドを特定します。
• これは何を呼び出していますか？ 呼び出し先を最大 8 階層までたどります。
• ここには何がありますか？ モジュール、各ファイルの宣言、シンボルのすべての使用箇所を確認できます。
• 編集によって何に影響しましたか？ 未コミットの変更が到達するルート、ジョブ、コマンドと、それらに関連する既存のテストを確認できます。

TypeScript、JavaScript、Go、Python、Java を各言語固有のコンパイラーでマッピングするため、インターフェース、基底クラス、テンプレート、デコレーターを介した呼び出しも、コンパイラーと同じように解決されます。テキスト検索では見つからない呼び出しも含まれます。WeChat ミニプログラムでは、各ページやコンポーネントのテンプレート（.wxml）を、それがバインドするメソッドや表示するコンポーネントにもリンクします。また、コンポーネントが発行する各イベントを、それをバインドするページのハンドラーにもリンクするため、呼び出し元をページまでたどれます。

例

Miniflux では、Storage.MarkFeedAsRead を 1 回呼び出すだけで、リクエストが到達する 4 つの経路を、それぞれのルートとともに特定できます。

DECLARATION internal/storage/entry.go: Storage.MarkFeedAsRead m656-680 exported
  ← called by internal/api/feed.go: handler.markFeedAsRead m140-155 @149
  ← called by internal/fever/handler.go: handler.handleWriteFeeds m492-519 @508
  ← called by internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338 @1311
  ← called by internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30 @24
[1] internal/api/feed.go: handler.markFeedAsRead m140-155
  ← used as value by internal/api/api.go: Serve f25-84 @61 "PUT /v1/feeds/{feedID}/mark-all-as-read"
[1] internal/googlereader/handler.go: handler.markAllAsReadHandler m1261-1338
  ← used as value by internal/googlereader/handler.go: Serve f44-64 @62 "POST /reader/api/0/mark-all-as-read"
[1] internal/ui/feed_mark_as_read.go: handler.markFeedAsRead m14-30
  ← used as value by internal/ui/ui.go: Serve f18-180 @77 "POST /feed/{feedID}/mark-all-as-read"
… (the Fever API, then on down to main.go: main)

m と f はそれぞれ、メソッドと関数を行番号付きで示します。@ は呼び出しの行番号で、引用符内のルートは登録されているルート、つまり HTTP メソッドと完全なパスです。このパスには、サブルーターが追加する /v1 プレフィックスも含まれます。Java、Python、TypeScript では、@GetMapping("/{id}") route "GET /api/tasks/{id}" のように、ルートがハンドラー自体に表示されます。

結果

「変更によって影響を受ける HTTP エンドポイントはどれですか？」という影響範囲に関する質問を、公開されている Go、Python、Java のプロジェクトで評価しました。各言語独自のツールチェーンと照合した正解セットに対し、盲検で採点しています。

	LayerMap あり	なし
検出したエンドポイント数、リクエスト上限 15 回（gpt-5.5、6 タスク × 3 回実行）	97.9%	58.8%
Claude Code / Codex がプロンプトなしで使用（プラグインをインストール、2 ラウンド）	12 件中 12 件 / 12 件中 12 件	—
検出したエンドポイント数、リクエスト上限なし（Claude Code / Codex、0.1.5）	100% / 100%	99.0% / 100%
Claude Code のコスト、リクエスト上限なし（0.1.5 の再実行、最初のラウンドでは −32%）	−33%
Codex の入力トークン数、リクエスト上限なし（現在のデフォルト設定）	+14%
所要時間、リクエスト上限なし（Claude Code / Codex）	+25% / +20%
変更チェックで列挙された失敗テスト数（Go / Python、失敗するようにした関数）	100% / 94–98%	—
波及タスク：他の機能のテストを通過したまま完了した実行数（Codex / Claude Code、4 タスク × ありは 6 回、なしは 3 回）	24 回中 23 回 / 24 回中 11 回	12 回中 3 回 / 12 回中 4 回
影響分析が不要な日常的なタスク：正しく完了した数 / 所要時間（Claude Code と Codex、8 タスク × 2 回実行）	32 件中 32 件 / +12–31%	32 件中 32 件

厳しい予算のもとでは、マップによって影響を受けるコードをはるかに多く見つけられ、トークン数は約 24% 増加します。上限がなければ、どちらのエージェントもマップの有無にかかわらず、ほぼすべてを見つけます。Claude Code のコストはマップにより 3 分の 1 減少します。Codex は現在のデフォルト設定ですでに効率よく検索するため、マップを使ってもトークン数は減りません。推論の労力を最大に設定した最初のラウンドでは、55% 削減されました。マップを使うとエージェントはより広範囲を調べるため、時間がかかります。明らかな変更によって別の機能が壊れるリクエストでは、変更チェックのおかげで Codex は依頼された機能の範囲を守れました。Claude Code は変更した別機能のテストを把握していましたが、意図的により広範囲の変更を続けることが多く、明確な違いは見られませんでした。小規模なローカルタスクではマップによる変化はありませんでしたが、時間とコストは約 5 分の 1 増加しました。これらは LayerMap の作者が作成したタスクを使った、小規模なサンプルでの結果です。レポートには、設定、公開されたタスク、制約事項が記載されています。

LayerMap の違い

ほかのツールもエージェントにこれらの情報の一部を提供します。LayerMap は、コンパイラーの精度と、チェーン全体のトレースを 1 つのローカルマップにまとめています。

	Tree-sitter コードグラフ（codegraph、GitNexus、…）	言語サーバーと IDE（Claude Code の LSP ツール、Serena、JetBrains）	埋め込み検索（Claude Context、Augment）	LayerMap
呼び出しの関連付け方法	名前、インポート、フレームワークのルールで照合し、多くの場合、信頼度スコアを付与	コンパイラー独自の解決方法	関連付けなし。類似するコードを取得	各言語のコンパイラーまたは型チェッカーで解決
呼び出し元からルートやハンドラーまでの追跡	複数のツールで対応、深さはさまざま	リクエストごとに 1 レベル（JetBrains はデフォルトで 5 レベル）	—	1 回の呼び出しで最大 8 レベル
マップとして保持	はい。ファイルの変更を監視	いいえ。稼働中のサーバーがその都度回答	コードチャンクのインデックス	はい。呼び出しのたびに最新の状態に更新
マシン上で実行	はい。一部は匿名のテレメトリーを送信	はい	通常はクラウドの埋め込みを使用	はい。情報の送信なし

次のようなニーズには、別のツールのほうが適しています。

• Tree-sitter のグラフが 30 以上の言語に対応しているため、より多くの言語を使いたい場合
• 言語サーバーによる名前変更やリファクタリングが必要な場合
• 埋め込み検索による意味ベースの検索が必要な場合
• Sourcegraph を使って、多数のリポジトリを横断して検索したい場合

インストール

Claude Code

/plugin marketplace add coffeecoproject/layermap
/plugin install layermap@layermap

Codex

codex plugin marketplace add coffeecoproject/layermap
codex plugin add layermap@layermap

CodeBuddy Code

codebuddy plugin marketplace add coffeecoproject/layermap
codebuddy plugin install layermap@layermap

Pi

pi install npm:layermap

DeepSeek Harness

npx layermap setup dsh

これにより、すべての dsh プロファイルに LayerMap が追加されます。各セッションでは、dsh の起動時にいたプロジェクトがマッピングされます。npx layermap remove dsh を実行すると元に戻せます。

どのエージェントでも、Git リポジトリ内で新しいセッションを開始し、いつもどおり質問してください。マップが役立つときは、LayerMap がエージェントに知らせます。複数のリポジトリを含むフォルダーでセッションを開始した場合や、別のリポジトリに移動した場合も問題ありません。各マップツールの呼び出しでは、パス名が示すリポジトリがマッピングされます。セッションで初めて LayerMap のバージョンを起動すると、npm は固定された layermap パッケージを LayerMap のキャッシュにインストールします。以降のセッションでは、オフラインでもキャッシュから起動します。

Claude Code は、プロジェクト内でマップツールを実行する前に、毎回確認を求めます。「今後確認しない」を選ぶか、npx layermap allow claude を実行すると、プラグインの読み取り専用ツールをどこでも許可できます。

編集後。 エージェントがコードを変更すると、project_check_changes はその変更の影響を一覧表示します。変更された関数に到達するルート、ジョブ、コマンド、マップからは見えないもの、変更に関連する既存のテストが示されます。変更されたコードが複数の領域（パッケージまたはモジュール）で使われている場合は、それぞれの領域とそのテストを示します。また、差分によって書き換えられた既存のテストも示すため、ある機能を意図した変更が他の機能をひそかに変えてしまうことを防げます。環境変数と設定キーは名前だけで関連付けられており、コンパイラーはそれを認識しません。そのため、差分でファイルから名前が削除されると、古い名前をまだ読み取っているファイルや設定しているファイルがチェックに表示されます。同様に、変更がルートのハンドラーに到達する場合やルートの名前を変更する場合は、そのパスをリクエストするコードやテンプレートが示されます。フロントエンドの fetch、生成された API クライアント、リダイレクト、リンクなどが該当します。変更によってプロジェクト概要内の 2 つのモジュール間にインポートが追加される場合は、そのインポートが示され、両者が相互に依存するようになった場合はその旨も示されます。その依存の方向がプロジェクトのレイヤー構成に合っているかどうかは、エージェントが判断します。変更によって追加される宣言が、プロジェクト内の既存コードとほとんど同じ内容を読み取る場合は、両方が示されるため、エージェントはコピーではなく既存コードを使えます。古いコードを新しいコードで置き換える場合など、変更によって宣言への最後の呼び出しがなくなると、その宣言が示されるため、エージェントは変更後に残ったコードを削除できます。テストの作成や実行は行いません。Claude Code と CodeBuddy Code では、編集ツールまたはシェルコマンドを通じてコードを編集した各リポジトリについて、まだチェックしていない場合、エージェントが終了する前にこのチェックを実行するようプラグインが一度だけ促します。シェルコマンドの場合は、対象として名前が指定されたコードファイルが編集対象として数えられます（同じ作業ツリーで別のセッションが行った変更は対象外です）。Pi 拡張機能も、エージェント自身による編集後に同じ処理を行います。無効にするには LAYERMAP_STOP_CHECK=0 を設定します。Codex と DeepSeek Harness には、チェックを実行するよう指示されています。

プラグインを使わない場合： npx layermap setup claude または npx layermap setup codex を実行してください。セットアップでは、次の 3 つが行われます。

• サーバーを登録します。
• 読み取り専用ツールをプロンプトなしで実行できるようにします。
• エージェントの指示ファイルに、マーク付きの文を 1 つ追加します。

セットアップは 1 台のマシン用です。チーム全体で使う場合は、各メンバーにプラグインをインストールしてもらってください。npx layermap remove … で元に戻せます。他の MCP クライアントでは、リポジトリ内で npx -y layermap mcp を stdio サーバーとして実行してください。

要件：

• Node.js 22.22 以降。
• macOS または Linux（x64 または arm64）。Windows（x64 または arm64）は実験段階です。
• Git リポジトリ。
• Java プロジェクトの場合、JDK 21 以降。

仕組み

リポジトリでの最初の呼び出し時にマップを作成します。小規模なプロジェクトなら数秒、大規模なプロジェクトなら数分かかります。以降の呼び出しでは変更された部分だけを再解析するため、マップは常に作業ツリーの状態と一致します。

マップはユーザーのキャッシュ（~/Library/Caches/layermap、~/.cache/layermap、または LAYERMAP_CACHE）に保存され、リポジトリには保存されません。LayerMap はすべてお使いのマシン上で動作し、外部にデータを送信しません（プライバシー、セキュリティ）。

ツール	用途
project_explore_map	ディレクトリ、ファイル、または宣言の呼び出し元と呼び出し先を調べます（direction は INCOMING または OUTGOING、depth は最大 8）。
project_search_map	宣言名、パス、ドキュメント内の語句から宣言を検索します。
project_find_references	現在のソースからコンパイルされた、宣言のすべての使用箇所を調べます。
project_check_changes	未コミットの変更（または base 以降の変更）が影響するものを確認します。変更・削除された宣言、それらが到達するルート、ジョブ、コマンド、変更されたコードを共有する領域、削除された環境変数や設定キーのうち他のファイルが引き続き使用しているもの、影響を受けるルートを要求するコードやテンプレート、モジュール間に新たに生じた依存関係とそれによって閉じる循環、既存のコードを繰り返している新しいコード、手動で確認すべき項目、および関連テストが対象です。tests を指定すると、これらのテストファイルがルート経由で呼び出したり要求したりしていない変更コードと、その上位のエントリーポイントも対象になります。

同じ機能をコマンドラインから利用できます。

npx layermap explore src/api/users.ts --name createUser --direction INCOMING --depth 8
npx layermap search "invoice total"
npx layermap refs src/billing/tax.ts calculateTax
npx layermap check --base main
npx layermap check test/billing.test.ts   # also: what of the change this test does not run

FAQ

最初のマップ作成にはどのくらいかかりますか？ 最近の Mac の場合：

• Miniflux（Go ファイル 400 個）：約 3 秒。
• Polar のサーバー（Python ファイル 1,900 個）：約 1 分。
• Conductor（Java ファイル 1,500 個、TypeScript ファイル 1,300 個）：2 分未満。

何を検出できませんか？ コンパイラーが静的に解決できない呼び出しです。依存性注入、認識されないフレームワークのルーティング、リフレクション、計算によって決まる名前などが該当します。ツールはトレースがどこで止まるかを示します。関係が見つからないからといって、その関係が存在しないとは限りません。

Windows は使えますか？ 実験的な対応です。LayerMap のテストは Windows でパスしますが、実際の Windows マシンで Claude Code や Codex と組み合わせて試されたことはまだありません。まずご自身のプロジェクトでテストし、問題があれば報告してください。Claude Code プラグインのフックには Git for Windows が必要です（Git Bash で実行されるため）。Git for Windows がない場合でもマップツールは動作しますが、セッション開始時の通知とタスク終了時のチェックは実行されません。

Claude Code の印字モード（claude -p）ではどうなりますか？ Claude Code 2.1 の時点では、印字モードはインストール済みプラグインが提供するサーバーを起動しないため、プラグインのフックは動作しますが、マップツールは利用できません。サーバーを自分で渡してください。

claude -p "..." --mcp-config '{"mcpServers":{"layermap":{"command":"npx","args":["-y","layermap","mcp"]}}}'

削除するにはどうすればよいですか？

• Claude Code：/plugin uninstall layermap@layermap。
• Codex：codex plugin remove layermap@layermap。
• CodeBuddy Code：codebuddy plugin uninstall layermap@layermap。
• Pi：pi remove npm:layermap。
• その後、キャッシュディレクトリを削除します。

開発

pnpm、Go 1.24、JDK 21 以降が必要です。ツールチェーンが不足している言語は解析されません。

pnpm install を実行します。初回インストール時に、pnpm はビルドスクリプトの実行を許可する依存関係を尋ねます。SQLite パッケージにはビルド済みバイナリが含まれているため、esbuild のみを許可してください。

pnpm approve-builds esbuild '!@photostructure/sqlite'

続いて pnpm test、pnpm typecheck、または pnpm lint を実行します。

pnpm package は npm パッケージをビルドします。

ライセンス

Apache-2.0。LICENSE と NOTICE を参照してください。