Understand Anythingでコードベースをナレッジグラフ化する
Understand Anythingは、コードベースやドキュメントを解析して、ファイル、関数、クラス、依存関係、業務フローを探索できるナレッジグラフに変換するAI開発支援リポジトリです。Claude Code、Codex、Cursor、Copilot、Gemini CLIなどのAIコーディング環境に組み込み、コード理解、オンボーディング、差分影響分析、仕様回答の補助に使う構成になっています。
どんなリポジトリか
Egonex-AI/Understand-Anything は、コードベース、ナレッジベース、ドキュメントを「探索・検索・質問できるグラフ」に変換するためのオープンソースプロジェクトです。単なるREADME生成ではなく、構造情報と意味情報を `knowledge-graph.json` にまとめ、ダッシュボードやチャット、差分分析から参照できるようにします。
リポジトリ内には、`understand-anything-plugin/skills/` 配下に `understand`、`understand-dashboard`、`understand-chat`、`understand-diff`、`understand-domain`、`understand-knowledge` などのスキル定義があります。`understand-anything-plugin/agents/` 配下には、プロジェクト走査、ファイル解析、アーキテクチャ分析、ツアー生成、グラフ検証、ドメイン分析、記事分析のためのエージェント定義があります。
この記事では、2026年6月17日時点の公開リポジトリ構成を前提に、Understand Anythingの役割、仕組み、導入時の考え方、仕様回答ツールと組み合わせる場合のアーキテクチャ例を整理します。
リポジトリ構成の見どころ
公開リポジトリ: https://github.com/Egonex-AI/Understand-Anything
README: Quick Start、マルチプラットフォーム対応、Tree-sitter + LLM構成、グラフ共有運用が説明されています。
`understand-anything-plugin/skills/`: AIコーディング環境から呼び出すコマンド相当のスキル定義がまとまっています。
`understand-anything-plugin/agents/`: 解析パイプラインを分担する専門エージェントのプロンプト定義が置かれています。
`packages/core` と `packages/dashboard`: 解析コアと可視化ダッシュボードを分けた構成です。
`package.json`: `tree-sitter-*`、`web-tree-sitter`、Vite、React、グラフ可視化関連ライブラリを使う構成です。
これは何をするツールか
一言でいうと、Understand Anythingは「AIコーディングの前処理として、コードベースを探索可能な中間表現に変換するツール」です。READMEでは、ファイル、関数、クラス、依存関係を抽出して `.understand-anything/knowledge-graph.json` に保存し、そのグラフをダッシュボードやチャット、差分分析に使う流れが説明されています。
通常のドキュメント生成と違うのは、成果物が文章だけではなく、ノードとエッジを持つグラフである点です。ノードはファイル、関数、クラス、設定、ドキュメント、エンドポイント、スキーマなどを表し、エッジは `imports`、`calls`、`contains`、`depends_on`、`documents`、`routes` などの関係を表します。
基本パイプライン
主要機能と使いどころ
Understand Anythingの機能は、コードベース理解のための「地図」を作る部分と、その地図を使って開発作業を助ける部分に分けて考えると分かりやすいです。
| 機能 | 何をするか | 使いどころ |
|---|---|---|
| `/understand` | プロジェクトを走査し、ファイル、関数、クラス、依存関係、レイヤー、ツアーを含む `knowledge-graph.json` を生成します。 | 初回オンボーディング、巨大リポジトリの構造把握、AIエージェント用の前処理。 |
| `/understand-dashboard` | 生成済みグラフをWebダッシュボードで表示し、ノード、エッジ、レイヤー、コード説明を探索できるようにします。 | 人間が全体像をつかむ、関係性を辿る、レビュー前に影響範囲を眺める。 |
| `/understand-chat` | グラフ内のノード、要約、タグ、エッジを検索し、コードベースに関する質問へ回答します。 | 「認証はどこで処理しているか」「この機能の入口はどこか」といった探索。 |
| `/understand-diff` | 現在の変更ファイルに対応するノードと、1-hopでつながる影響候補を抽出し、差分オーバーレイを作ります。 | PRレビュー、影響範囲の初期確認、テスト観点の洗い出し。 |
| `/understand-domain` | 既存グラフまたは軽量スキャンから、ドメイン、業務フロー、プロセスステップを抽出します。 | 仕様理解、業務プロセスとコードの対応づけ、非エンジニアとの説明材料。 |
| `/understand-knowledge` | Karpathy-pattern LLM wikiのようなナレッジベースを解析し、記事、トピック、エンティティ、主張のグラフを作ります。 | 技術メモ、設計ドキュメント、仕様wikiをコード理解と同じ探索体験に寄せる。 |
| グラフ共有 | `.understand-anything/` の一部をリポジトリに含め、チームで同じコード理解メタデータを共有できます。 | オンボーディング、レビュー、リリース前の構造確認、AI支援の共通コンテキスト化。 |
中身の設計
`/understand` のスキル定義を見ると、処理は大まかに、事前確認、ignore設定、スキャン、バッチ分割、ファイル解析、グラフ組み立て、レイヤー分析、ツアー生成、検証、保存という段階に分かれています。単に全ファイルをLLMに投げるのではなく、静的解析で構造を取り、LLMには意味づけを担当させる構成です。
Tree-sitter側は、構文木からimport/export、関数・クラス、呼び出し、継承のような構造情報を取り出す役割です。ここは同じ入力なら同じ結果になりやすく、増分更新や差分分析の土台になります。
LLM側は、ファイルの目的、アーキテクチャレイヤー、タグ、自然言語要約、業務フロー、オンボーディング用のガイドツアーなど、ASTだけでは判断しづらい意味づけを担当します。ここは便利な一方で、モデルやプロンプト、入力コードの品質に依存します。
エージェント定義としては、`project-scanner`、`file-analyzer`、`architecture-analyzer`、`tour-builder`、`graph-reviewer`、`domain-analyzer`、`article-analyzer` に加え、`assemble-reviewer` や `knowledge-graph-guide` も含まれています。READMEに出てくる主要な役割を、プラグイン本体のプロンプト定義として管理している構成です。
できることを実務目線で整理する
最も分かりやすい用途は、新しく参加した開発者が巨大なリポジトリの全体像をつかむことです。どのファイルが入口で、どのレイヤーに何があり、どのコンポーネントが依存されているのかを、グラフとツアーで追えます。
次に、AIエージェントに渡すコンテキストの圧縮です。AIに「このリポジトリを理解して」と毎回ソースを広く読ませるのではなく、事前に構造化した `knowledge-graph.json` を読み、関係のあるノードとエッジだけを取り出せるようにします。これはトークン節約だけでなく、AIの探索漏れを減らす効果が期待できます。
さらに、レビューや差分影響分析にも向いています。`understand-diff` は変更ファイルに対応するノードを探し、その周辺の1-hop関係やレイヤーを見ます。完璧な影響分析というより、「見るべき周辺を自動で候補出しする」用途に近いです。
仕様回答ツールと組み合わせるアーキテクチャ例
このツールを単体の可視化ツールとして見るだけでは少しもったいないです。仕様書、ADR、問い合わせ履歴、API定義、DB定義を答える社内Q&Aツールと組み合わせると、「仕様で言っていること」と「コードで実装されていること」をつなぐレイヤーになります。
仕様回答ツールと組み合わせる構成例
例1: 「この仕様はどこで実装されているか」
仕様回答ツールが「予約キャンセル」「支払い確定」「権限チェック」などのドメイン語を受け取り、まず仕様DBから該当仕様を取り出します。次に、Understand Anythingのグラフから同じタグや要約を持つノード、関連するendpoint、service、functionを探します。回答では、仕様の根拠とコード上の実装候補を分けて表示します。
例2: 「このPRはどの仕様に影響するか」
`understand-diff` の結果から変更ノードと影響ノードを取得し、それらに紐づく仕様、ADR、APIエンドポイント、DBテーブルを逆引きします。レビュー画面では、変更ファイル一覧だけでなく、関連する業務フローと確認すべき受け入れ条件を提示できます。
例3: 「この障害の原因候補はどこか」
ログやトレースからendpointやジョブ名を特定し、そのノードをグラフ上の起点にします。そこから呼び出し先、設定、依存サービス、DBテーブルを辿り、仕様回答ツールがRunbookや過去障害を併せて提示します。コード理解と運用知識を同じ回答面で扱えるようになります。
導入するなら小さく検証する
導入手順としては、まず非機密の小さなリポジトリで `/understand`、`/understand-dashboard`、`/understand-chat`、`/understand-diff` を試すのがよいです。いきなり巨大な本番リポジトリに入れるより、グラフの読みやすさ、ノード粒度、LLMが作る要約の癖、処理時間を見た方が判断しやすくなります。
チーム導入では、`.understand-anything/knowledge-graph.json` をコミットするかどうかも設計ポイントです。READMEでは `intermediate/` と `diff-overlay.json` を除いて共有する運用が提案されています。共有すればオンボーディングやレビューで使いやすい一方、コード構造や要約がリポジトリに残るため、公開範囲と権限管理を確認する必要があります。
注意点
| 観点 | 注意点 | 対策 |
|---|---|---|
| インストール | READMEには `curl ... | bash` 形式の導入が案内されています。 | 社内利用ではスクリプト内容確認、固定コミット、社内ミラー、署名検証、許可済みインストーラ化を挟む。 |
| コード送信 | LLMが意味解析に関わるため、どのツール、どのモデル、どの経路にコードが渡るかを確認する必要があります。 | AIコーディング環境のデータ取り扱いポリシー、社内規程、対象リポジトリの機密区分に合わせて検証する。 |
| 精度 | 静的解析は動的呼び出し、DI、メタプログラミング、フレームワーク規約を完全には拾えない場合があります。 | 重要フローは人間レビュー、テスト、トレース、仕様書と突き合わせる。グラフは判断材料として扱う。 |
| 鮮度 | グラフが古くなると、AIの回答も古い構造に引っ張られます。 | post-commit hook、CIでの再生成、リリース前更新など、更新タイミングを運用に組み込む。 |
| レビュー負荷 | 生成された要約やドメイン分類がもっともらしく見えても、誤分類の可能性があります。 | 初回は重要ドメインだけサンプリングレビューし、採用基準を決める。 |
評価チェックリスト
- 対象リポジトリで、生成されたノード数・エッジ数・レイヤーが人間の理解と大きくズレていないか。
- 重要な業務フローを質問したとき、該当ファイル・関数・仕様に辿り着けるか。
- PR差分で、見るべき周辺コンポーネントが候補として出るか。
- LLMに送られる情報と、保存される `.understand-anything/` の内容が社内ルールに合うか。
- CIまたはローカル運用で、グラフの更新が負担にならない処理時間に収まるか。
- 仕様回答ツールとつなぐ場合、回答に「仕様の根拠」と「コード上の根拠」を分けて表示できるか。
まとめ
Understand Anythingは、AIコーディング環境に「コードベース理解の中間表現」を足すためのツールです。Tree-sitterで構造を取り、LLMで意味づけし、ナレッジグラフ、ダッシュボード、チャット、差分分析、ドメイン分析に展開する設計は、公開READMEと実際のプラグイン構成から確認できます。
期待値としては、「AIがコードを完全理解する魔法」ではなく、「AIと人間が巨大なリポジトリを探索するための地図」と捉えるのが現実的です。仕様回答ツール、PRレビュー支援、オンボーディング、運用調査と組み合わせると、コード・仕様・差分・運用知識を横断する開発基盤の部品として使えます。
