🦀 AIエージェントの「盲目な編集」を防ぐRust製ツール Graphenium

AIエージェントに「この関数のシグネチャを変えて」とだけ頼んだら、関係のないファイルまで巻き込んで壊れた。心当たりのある人は多いと思う。

仕組みを考えると理由は単純だ。エージェントはファイル名とimport文から依存関係を「推測」しているだけで、実際の呼び出し関係を見ているわけではない。grepで拾えた場所だけ直り、拾えなかった場所は放置される。

ファイル名からの推測、という落とし穴

AIコーディングエージェントの多くは、リポジトリを読むときに「ファイルを無差別に開く」か「ファイル名やディレクトリ構造から依存関係を推測する」かのどちらかをやっている。小さいリポジトリなら問題は出にくい。ただし数百ファイル規模になると、推測と実際の依存関係のズレが編集ミスに直結する。

Graphenium(Rust製・MIT license)は、この「推測」を「検証可能なグラフ」に置き換えるツールだ。Tree-sitterでソースを解析し、シンボル間の関係を抽出した上で、それぞれの関係に EXTRACTED(抽出)・INFERRED(推測)・AMBIGUOUS(曖昧) という信頼度ラベルを付ける。エージェントは「これは確実な依存関係」と「これは推測に過ぎない」を区別した上で編集計画を立てられる。

blast radius を編集前に見る

使い方はシンプルだ。

gm init                    # ワークスペース初期化
gm run . --no-semantic     # グラフ構築
gm query "authentication flow" --budget 2000
gm serve --graph graphenium-out/graph.json   # MCPサーバーとして起動

コマンド自体は地味だが、肝は blast_radius クエリだ。「このシンボルを変更したら、どこまで影響が波及するか」を編集前に問い合わせられる。冒頭のような「関係のない3ファイルが壊れる」事故は、実行前にこのクエリを一発通していれば防げていたはずだ。

gm serve はMCPサーバーとして立ち上がるので、Claude Code のようなエージェントからそのままツールとして呼び出せる。エージェントが「編集前に構造を確認する」フローを、プロンプトの指示ではなく仕組みとして強制できる、というのがポイントだと思う。

ローカルファーストという選択

ソースコードの解析は基本的にマシン内で完結する。セマンティック抽出(意味解析)だけ任意でオプトインできる設計になっていて、コードをどこかのAPIに送る前提にしていない。社内コードや守秘義務のあるクライアント案件のリポジトリを扱うことが多い身としては、ここは地味に重要なポイントだった。

対応言語はRust、Python、Go、JavaScript、TypeScript、Java、C、C++、C#と幅広い。AST+リゾルバー部分は安定版、セマンティックパスも安定版と書かれているが、テレメトリー機能はまだ実験段階らしい。本番導入は少し様子を見てからでもよさそうだ。

エージェントに「賢く読んでもらう」ことを期待するより、「壊す前に構造を見せる」仕組みを先に用意しておく。この発想、しばらく手元のリポジトリで試してみるつもりだ。