新しいチームに入った初日、20万行・3言語・5年分の負債が乗った monorepo が clone される——Cursor や Claude Code、Copilot は単ファイル修正には効くのに、午後一つで全体像を説明できる人はいない。HN や Reddit、国内の X/Zenn スレでも同じ嘆きが繰り返されるのが 2026 年の「AI 読庫」問題：チャットは幻覚する、全文を context に突っ込むと token が爆発、静的解析だけでは「このコードがビジネス上何をしているか」が読めない。Understand-Anything（MIT / Lum1104）がオープンソースで一気に話題になった理由はシンプルで、LLM に構造を当てず、Tree-sitter で骨格を固定し、マルチ Agent で意味を足し、探索・コミット・差分更新できる知識グラフに落とすからだ。
1. AI 読庫の四つの痛点
コミュニティの不満は驚くほど似ている。ざっくり四類型に分けられる。
- コンテキスト窓 ≠ 理解：monorepo の半分を貼っても、パッケージをまたぐ呼び出しを落としたり、「それっぽい」ファイルに原因を寄せたりする。
- 再利用できる「地図」がない：毎回 onboarding で「決済フローはどこから入る？」と聞き直す。知識がチャット履歴に閉じ、PR レビューもバージョン管理もできない。
- 純 RAG / 純 grep の死角：ベクトル検索は似た断片は見つけるが呼び出しチェーンの完全性は保証しない。全文検索はシンボルは拾うがアーキテクチャの層までは語れない。
- 改修前の「波及」が見えない：auth ミドルウェアを触ったら、下流の API とテストがいくつ動くか——人間の記憶やその場の prompt では体系的に答えにくい。
2. なぜオープンソースで話題になったか
2026 年 3 月の公開後、GitHub Star は短期間で数万規模（コミュニティ報道では 2 万+ Fork 級の言及も）。Better Stack や DEV などへの転載も続いた。マーケ文言ではなく、三つの空白を埋めたからだ。
- 再現可能なハイブリッド：import・呼び出し・継承などの構造エッジは Tree-sitter が決定的に出力。同じ入力なら何度走らせても辺は一致。要約・業務域・ツアーは LLM が補完——「モデルが依存関係をでっち上げる」だけを避けられる。
- 成果物がチームに渡る：
.understand-anything/knowledge-graph.jsonが Git / LFS に載る。次のメンバーはフルスキャンをスキップできる。口伝 onboarding から docs-as-code へ。 - IDE / Agent プラットフォーム横断：Claude Code ネイティブプラグインに加え、Cursor 自動検出、Copilot、Codex、Gemini CLI、OpenClaw など一行 install スクリプト——「エディタ X しか使わない」摩擦が低い。
公式スローガンも地味で好印象：Graphs that teach > graphs that impress——見栄えの花火より、システムの組み立て方を教えるグラフ。
3. 技術：Tree-sitter + マルチ Agent パイプライン
3.1 決定的な構造層
Tree-sitter がソースを concrete syntax tree に落とし、import/export、関数・クラス定義、呼び出し点、継承など検証可能な事実を抽出する。スキャン段階で importMap を先に解決し、ファイル分析 Agent が毎回依存を推論し直す無駄を減らす。ファイル指紋ベースの増分更新で、初回フルスキャン後は変更ファイルだけ——CI や post-commit hook と相性がいい。
3.2 意味層と専用 Agent
/understand は複数 Agent を編成する（名称は README 準拠、バージョンで増減あり）：
project-scanner：ファイル探索、言語・フレームワーク識別。file-analyzer：グラフのノードと辺（並列バッチ、だいたい 20–30 ファイル単位）。architecture-analyzer：API / Service / Data / UI など層の分割と色分け。tour-builder：依存順の読み進めルート——新人が順序を間違えにくい。graph-reviewer：参照整合性チェック（フル LLM review も可）。domain-analyzer（/understand-domain）：技術シンボルを業務ドメイン・フロー・ステップへ——静的ツール単体では難しく、PM も読めるビュー。
3.3 プロダクト機能
構造図以外に Dashboard ではあいまい/意味検索（「認可を扱うモジュールは？」）、/understand-diff の変更影響、Persona による詳細度、12 言語での概念説明など。/understand-knowledge は Karpathy 式 LLM Wiki の wikilink とカテゴリを力导向グラフに——コードだけでなくドキュメント型ナレッジにも効く。
4. クイックスタート：インストールから日本語グラフまで
以下は公式 README（2026 年 5 月 v2.7.x 系）ベース。マーケットや CLI が変わったら GitHub ドキュメントを正とする。
4.1 Claude Code プラグイン
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything
/understand --language ja
/understand-dashboard--language ja でノード要約と Dashboard 文言を日本語化。zh、zh-TW、ko、ru なども同様。
4.2 Cursor / その他
リポジトリ clone 後、.cursor-plugin/plugin.json で Cursor が自動検出。macOS/Linux ではワンライナーも：
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex末尾の codex を openclaw、gemini、vscode などに差し替え。よく使うコマンド：
/understand-chat— グラフベース Q&A（決済経路など）。/understand-explain path/to/file.ts— 単ファイル/関数の深掘り。/understand-onboard— onboarding ドキュメント生成。/understand --auto-update— post-commit 増分更新。/understand src/frontend— 巨大 monorepo はサブディレクトリ指定。
5. DeepWiki、Copilot、純 RAG との選び方
| 方式 | 強み | 弱み / コスト | 向く場面 |
|---|---|---|---|
| Understand-Anything | AST 級の構造辺 + 意味注釈；JSON コミット可；増分；業務域ビュー | 初回フルスキャンに LLM 時間と費用；巨大 JSON は Git LFS | プライベート repo onboarding、アーキレビュー、改修前の影響分析 |
| DeepWiki 等ホスト Wiki | ゼロインストール、公開倉庫ですぐ読める | 社内/プライベートに不向き；更新タイミングを制御できない | OSS のざっと把握 |
| IDE 内 Copilot / Chat | 改コードの閉ループが速い | 永続的な全局図がない；長スレッドはドリフト | 日常の単ファイル開発 |
| Sourcegraph / 企業コード検索 | 横断シンボル、PR 連携 | コストとガバナンス；意味の物語は専用グラフに劣る | 大規模エンジニアリング組織 |
| Aider / Continue 等 | 対話的イテレーション | コンテキストは依然 token 制限 | 中小規模のペアプロ |
2026 年の現実的な組み合わせ：1–2 日目に Understand-Anything で地図、日常は Cursor/Copilot、大きなリファクタ前に /understand-diff。Agent ランタイムを別途検討するなら OpenHuman と OpenClaw の役割分担も参照——記憶型デスクトップ Agent と多チャネルゲートウェイは別問題で、読庫グラフの代替ではない。
6. 性能とコスト：頭に入れておく数字
コミュニティも公式も同じ：初回フル分析時間は規模・言語混在・LLM プロバイダに比例。数十万行 monorepo をノートで一巡させると、だいたい数十分程度（並列度とモデル速度次第）。その後の増分 commit は変更ファイルだけでコストが下がる。
- 並列：file-analyzer はバッチ並列（README で約 5 並列の言及）。初回は性能のいいマシン向き。
- 範囲：サブディレクトリ引数で倉庫丸ごとを避ける。
- 保存：グラフ JSON が ~10MB 超なら
git-lfs推奨。 - 言語：TS/JS/Python/Go など主流スタックが最も厚い。マイナー DSL は構造辺が欠けることも——人間の補読前提。
ローカル LLM で注釈コストを下げるなら Apple Silicon + Ollama/MLX が定番——ハード選定は Ollama とクラウド GPU コスト比較を参照。パイプライン本体は設定したクラウドモデルが主（プラグイン設定準拠）。
7. 境界：無理に入れなくていいケース
Star 数より正直な限界の方が役に立つ。
- 極小 repo / 使い捨てスクリプト：グラフ構築コスト > README 直読。ファイル数個なら IDE ジャンプで足りる。
- 強リアルタイム・秒級 Q&A：フル索引前は grep の方が速い。「段階的資産」向きでホットパス向きではない。
- 意味層の陳腐化：構造辺はコードに追従するが、LLM 要約は増分未実行だと業務意図とズレる——
--auto-updateかリリース前の手動/understandが discipline。 - セキュリティ：分析でソース断片がモデル API に送られる。隔離環境では自前エンドポイントとデータ持ち出し方針のレビュー必須。
- Code Review の代替ではない：グラフは「どう繋がるか」を説明する。「この PR が正しいか」はテストと人間の目。
8. よくある誤解
- Dashboard を「かっこいいアーキ PPT」にして JSON をコミットしない——チームに渡らず、個人の一度きり体験で終わる。
- CI で毎 PR フルスキャン——指紋増分を使わず費用と時間が暴走。
- チャットだけでグラフを見ない——
/understand-chatの上限はグラフ品質次第。構造が狂うと自信満々に間違える。 /understand-domainを無視——クロスファンクションでは関数一覧より業務域ビューの方が説得力がある。
9. 結論：読庫痛点は「構造化」で縮む
Understand-Anything がオープンソースで続く話題になるのは、「AI 読庫」を一度きりの対話からバージョン管理できる理解資産へ進めたから。Tree-sitter が構造の下限を守り、マルチ Agent LLM が人間可読の意味と業務ナラティブを足し、Dashboard が複雑さをクリック可能な地図に折りたたむ。コードを書く代わりにはならないが、「新人 3 週 → 3 日」「auth を触る前に波及を見る」を再現可能にする。
macOS で Agent を常駐させる、OpenClaw を載せる、フル分析を別マシンに逃がすなら OpenClaw 安定ゲートウェイのゼロインストール と Docker Compose トラブルシュート も有用。install スクリプトは openclaw プラットフォーム対応済みで、同一開発 Mac に並ぶことも多い。
関連記事： OpenHumanとOpenClaw：レイヤーごとの役割分担、Ollamaと低コストGPU VPS・API費用の比較、OpenClawゼロインストールから安定ゲートウェイまで
10. 大規模 repo の初回フルスキャン：クラウド Mac で時間を買う
フル /understand は CPU・ディスク・LLM 並列の重い仕事。多くのチームが初回スキャンを専用の Mac mini M4 に載せる——NVMe でソースを連続読み、Node プラグインと macOS ツールチェーンが揃い、終わったら .understand-anything/ を repo に push。ローカルノートは日常の改コードと Dashboard 閲覧だけ。
vpszap クラウド Mac mini は物理機専有、約 5 分開通、SSH/VNC、複数リージョン。日/週/月/四半期の短期レンタルで長期契約なし——「今週地図を作る」 onboarding 向きで、一度きりの分析のために Mac を調達する必要がない。リージョンと M4 スペックは 6 地域クラウド Mac 遅延・M4 選定 FAQ を参照。
