🔒 完全ローカル / 🆓 無料・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、なんでも大歓迎です。最後まで読んでいただき、ありがとうございました！