🔒 完全ローカル / 🆓 無料・MIT / あなたのコードは1バイトも外に出ません。

⏱️ 3行で言うと（ネタバレ）

AIに巨大リポジトリを全部読ませるのをやめて、“コードの地図”だけ渡すようにしました。
結果、プロジェクトの概要把握にかかるトークンが 145,978 → 289（実測・約1/500）。
やることは、VSCode拡張 comP と MCPサーバ MAGATAMA を入れるだけ。10分で試せます。

「ほんとに?」「1/500とか盛ってない?」——その疑問、この記事で全部つぶします。
エンタメ半分で、気軽に読んでください😌

😩 こんな経験、ありませんか?

Cursor・Copilot・Claude……AIエージェント、もう手放せませんよね。
でもでかいリポジトリを相手にした瞬間、これ、ありません?

🧱「全体像つかんで」→ ファイルを片っ端から読み始めて、一瞬でコンテキスト上限
💸 ちょっと仕様を見たいだけなのに、関係ないファイルまで読まれてトークン（=料金）が溶ける
💥 依存関係を無視した修正案で、別の機能がぶっ壊れる

原因、めちゃくちゃシンプルです。
AIに「この見知らぬ巨大な街（=ソースコード）、全部の道を自分の足で歩いて調べてこい」と丸投げしているから。

知らない街で、全通りを端から端まで歩く人はいません。普通は地図を見ますよね?
——なら、AIにも最初に地図を渡せばいい。 それだけの話です。

それを実現するOSSセットを作りました。『comP』（測量士）と 『MAGATAMA／勾玉』（案内人）です。

ソフト	役割	正体
comP	コードを歩き回って地図を作る測量士	VSCode拡張（24言語を自動解析）
MAGATAMA	地図を読んでAIに“必要な区画だけ”渡す案内人	MCPサーバ

[comP] コードを解析 → 地図(.comp/index.db)を作る
        ▼
[MAGATAMA] 地図から「いま必要な区画」だけ抜き出してAIへ
        ▼
Claude / Cursor / Copilot 「全ソース読まずに構造を理解！」

ポイントは、AIが実装の中身を読まず、関数・クラス・依存関係という“街の構造”だけを受け取ること。
ここからは、あなたが今思っている疑問に順番に答えていきます。

❓ 疑問1：「地図を渡すだけで、ほんとにそんな変わるの?」

変わります。口で言っても怪しいので、**このMAGATAMA自身のソース（64ファイル）**で測りました。
タスクは「プロジェクトの概要を把握する」。結果がこれ👇

やり方	たとえると	トークン数
😱 全ソース直読み（従来）	全通りを足で歩く	145,978
⚡ 地図で概要だけ見る	行き先をチラ見	289

145,978 → 289。 桁が3つ落ちました。
全ソースを読ませていた頃のコスト感から見ると、もう別世界です。しかも速い。

❓ 疑問2：「いや、1/500って正直“盛ってる”でしょ?」

……鋭いですね。**正直に白状します。半分その通りです。**😅

この「1/500」は、“行き先だけチラ見”したときの数字。
地図って、実は2通りの使い方があるんです。ここをごまかさず分けて説明します。

使い方A：行き先だけサッと確認（チラ見）

「このプロジェクト何? どこから読む?」みたいな概要把握。
AIは地図の“見出し”だけ見ればいいので、爆速・激安＝ 289トークン。

使い方B：地図を頭に叩き込んで「よく知った街」にする（暗記）

引っ越したばかりの街でも、一度ちゃんと地図で全体を覚えてしまえば、もう迷いませんよね。
あれと同じで、全シンボルをまるごとAIに渡し、リポジトリの“住人レベル”に詳しくさせる使い方です。
当然チラ見より重い。でも——測ってみたらこうでした👇

やり方	たとえると	トークン数	全読み比
😱 全ソース直読み	全通りを足で歩く	145,978	基準
🧠 使い方B：街全体を暗記	地図を頭に入れる	50,515	約 1/3
⚡ 使い方A：行き先チラ見	サッと確認	289	約 1/500

※ トークン数は tiktoken (cl100k_base) を使った近似値です。とはいえ 289 と 145,978 は
桁が3つ違うので、多少の測定誤差では結論はびくともしません。

つまり——
「1/500」はチラ見のときの数字。本気で“街を丸暗記”させても、全読みの1/3で済む。
盛ってるどころか、どっちに転んでもお得なんです。これが地図のすごいところ。

❓ 疑問3：「トークン削ったら、答えがバカになるんじゃ?」

逆です。ノイズが減るぶん、むしろ的確になります。
↓は実際にMAGATAMA自身でやらせた回答（実測）。

🤖 AIの回答：
「MAGATAMAは、コードを知識グラフ化してAIに最小トークンで文脈を渡すMCPサーバです。
magatama-core（エンジン）＋ magatama-mcp（MCP+CLI）の2パッケージ構成で、Clean Architecture を採用。
まず読むなら、comP Bridge の中核 comp_usecase.py からどうぞ。」

ソースの中身を1行も読まずに、「どこから読み始めるべきか」まで一発で当ててきます。
これ、新人のオンボーディングや、引き継いだレガシーの初日に効きすぎます。

❓ 疑問4：「便利そう。でも導入、だるいんでしょ?」

3ステップで終わります。コーヒー淹れてる間に。☕

Step 1. VSCode拡張『comP』で地図を作る

拡張機能検索で comP を検索し、五芒星のアイコンを目印にインストール。
あとは対象プロジェクトを開くだけで、裏で .comp/index.db（地図）が育ちます。初回だけ時間がかかり、以降は増分更新。

Step 2. 『MAGATAMA』をインストール（Python 3.11+）

pip install magatama
magatama info   # ツール数 36 が出ればOK

Step 3. AIツールにMCP登録

Cursor / Claude Desktop などの設定にこれを足すだけ。

{
  "mcpServers": {
    "magatama": { "command": "magatama", "args": ["serve"] }
  }
}

あとはAIを再起動して、チャットにこう投げるだけ👇

get_external_graph_info(path="あなたのプロジェクトパス") で地図を確認して。
問題なければ read_external_graph で取り込んで、このプロジェクトを概観して。

🎯 おまけ：地図があると、ここまでできる

「ここ直したら、どこが壊れる?」を一瞬で

巨大コードを触るときの最大の不安、影響範囲。analyze_impact が代わりに調べます。

あなた：「save_graph を探して、変更したときの影響範囲を教えて」
🤖：「対象は _handle_save_graph (mcp_server.py:442)。saveコマンドと parse --output から呼ばれています。この2経路のテストを確認してください」

→ grepで目視して追う作業が消えます。安心してリファクタできる。

内蔵「47フレームワーク」の作法を横断検索

MAGATAMAは先達OSS YATA（八咫） をベースに、
47種類（457K+エンティティ）の主要FW（React/Vue/Django/FastAPI/Rails…）の知識を最初から内蔵。

あなた：「hybrid_search で "FastAPI dependency injection" を、公式の作法とうちのコードを横断検索して」
🤖：「公式は Depends() を関数引数に宣言。あなたのコードはまだDI未使用。導入候補は routes 層です」

→「今の正解の書き方」を、あなたのプロジェクトの文脈に最適化して返してくれます。

🎁 まとめ

💰 安い：概要把握は約1/500、街まるごと暗記でも約1/3トークン
⚡ 速い：AIが何百ファイルも読む待ち時間が消える
🌍 広い：24言語 × 47フレームワークを横断（36 MCPツール）
🔒 安全：完全ローカル。コードは1バイトも外に出ない
🆓 無料：MITライセンスのOSS

AIコーディングのキモは、結局「いかに“必要な文脈だけ”をスマートに渡すか」。
見知らぬ街も、良い地図があれば数日で“地元”になる。AIにも、その地図を渡してあげてください。

最後に質問です。
あなたのリポジトリ、AIに何トークンかけて読ませていますか?

一度、地図を渡して測ってみてください。きっと驚きます。
試して「おっ」と思ったら、GitHubで ⭐スター を押してもらえると、開発の大きな励みになります🙏

👉 comP: https://github.com/tsucky230/comP
👉 MAGATAMA: https://github.com/tsucky230/MAGATAMA

感想・バグ報告・PR、なんでも大歓迎です。最後まで読んでいただき、ありがとうございました！