Clarity CLI - AI coding agent の変更に review 可能な impact graph を足す

AI coding agent が「かなり書ける」と見える場面ほど、実は review が必要です。Agent は複数 file を素早く変更し、test を足し、interface を移行し、ついでに directory 構成まで整理できます。しかし人間の review では diff そのものだけでなく、その変更がどの module に届いたのか、どの path がより結合したのか、どの test や document が追従すべきなのかを見たいはずです。

今日紹介する LegacyCodeHQ/clarity-cli は、その部分を CLI tool にしようとしている project です。Go で作られており、AI-native developers と coding agents 向けの software design tool と位置づけられています。clarity watch と clarity show で code impact graph を生成し、commit 前に現在の変更がどの file や関係に影響するかを見られるようにします。GitHub page では現在およそ 40 stars、2 forks。主な言語は Go、license は AGPL-3.0、repository は 2026 年 1 月に作成され、latest commit は 2026 年 6 月、latest release は v0.19.1 です。

プロジェクト概要

項目	内容
リポジトリ	LegacyCodeHQ/clarity-cli
位置づけ	Developer と coding agent 向けの code impact graph / design review CLI
Stars	約 40
Forks	2
主な言語	Go
ライセンス	AGPL-3.0
Latest release	v0.19.1
Install	npm、Homebrew、prebuilt binary、source build

目的は summary ではなく design impact

多くの AI tool は diff を説明できます。ただし、その説明は自然言語の summary に寄りがちです。何を変えたか、なぜ変えたか、どんな risk があるか、という形です。Clarity CLI の視点はもう少し構造的です。README では、code から impact graphs を生成し、commit 前に design effects を review できるようにすると説明されています。

つまり、変更を単に要約するのではなく、file 間、変更間、test との関係を図として見せようとしています。たとえば clarity show で uncommitted changes を見たり、clarity show -c HEAD で latest commit を見たり、clarity show -c HEAD~3...HEAD で commit range を見たりできます。

この種の view は、次のような問いに向いています。

今回の変更は実際にどの area に触れたのか。
Solution の構造はどうなっているのか。
どの module が今までより近く結びついたのか。

これらは「code が動くか」より自動化が難しい問いです。Local diff を project structure の中に戻して見る必要があるからです。

`watch` は開発中の視界を作る

Clarity の二つの中心 command のうち、clarity watch は開発中の continuous feedback に向いています。Project 内で実行すると、coding の間に live impact view を保てます。Module を分けたり、interface を動かしたり、test を足したりしているとき、architecture impact を「commit 後の振り返り」から「変更中の観察」に少し前倒しできます。

これは agent workflow にも効きます。Agent は小さな step を連続して実行するのが得意ですが、現在の patch だけに視野が寄ることがあります。意味のある変更のあとに impact graph を生成できれば、人間は agent が正しい design direction に沿っているかをより早く判断できます。

もちろん、watch は品質保証ではありません。Test、type check、人間の review を置き換えるものではありません。むしろ構造を見る radar のようなものです。変更範囲が急に広がったり、触るべきでない directory が影響を受けたり、test path が追従していなかったりする signal を早めに見つける用途です。

`show` は review と agent の turn に入れやすい

clarity show は automation flow に入れやすい command です。README には次のような使い方があります。

clarity show
clarity show -c HEAD
clarity show -c HEAD~3...HEAD
clarity show -i src,tests
clarity show -w a.go,b.go

これらはそれぞれ、uncommitted changes、single commit、commit range、指定 directory、二つの file 間の path relationship を扱います。Review での価値は、「今回の変更範囲」を主観的な説明ではなく、repeatable な check material にできることです。

私が特に面白いと思うのは coding agent との組み合わせです。Clarity には clarity setup があり、agent が Clarity を使うための instruction を AGENTS.md に書き込みます。すると agent は毎回その場で指示されなくても、意味のある変更後に clarity show を実行し、その output を design review の一部にできます。

これは成熟した agent usage に近いです。Agent に「確認しました」と言わせるのではなく、人間が確認できる intermediate evidence を出させるからです。

対応 language は実プロジェクトに近い

README では、Clarity は 17 languages を support するとされています。C、C++、C#、Dart、Go、JavaScript、Java、Kotlin、Markdown、Python、Ruby、Rust、Scala、Svelte、Swift、TypeScript、Zig です。同時に、parsing quality は language によって異なるとも書かれています。

この注意書きは重要です。Code structure analysis tool は「すべての code を理解する」と言いがちですが、language ごとの import、module、test、generated file、framework convention はかなり違います。Parsing quality の差を先に明記しているほうが、むしろ信頼できます。

実際に使うなら、まず一つの repository で試すのがよいと思います。特に monorepo、generated code が多い project、path alias が複雑な project では、生成される graph が team の architecture boundary の理解と合うかを見るのが第一歩です。

Install path は cross-platform に近い

Clarity CLI の install options は比較的そろっています。README と installation document では、npm global install が紹介されています。

npm install -g @legacycodehq/clarity

macOS と Linux では Homebrew も使えます。

brew install LegacyCodeHQ/tap/clarity

さらに releases page から prebuilt binary を入手でき、source build も可能です。Source build には Go 1.21+ と CGO enabled が必要です。

git clone https://github.com/LegacyCodeHQ/clarity-cli.git
cd clarity-cli
make build-dev

npm wrapper の package.json は macOS、Linux、Windows、そして x64、arm64 を対象にしています。Agent workflow に入りたい CLI にとって、cross-platform install は重要です。Agent が動く場所は local machine、remote development machine、container、CI runner などに分かれるからです。

向いている場面

Clarity CLI は、次のような場面に向いています。

Agent または人間の一回の変更が複数 module にまたがる。
Review が code style だけでなく design boundary と coupling change を見る。
「変更の影響範囲」を commit 前の固定 check material にしたい。
Agent に変更後の reviewable な structure evidence を出させたい。
Team がすでに AGENTS.md や同様の agent operation convention を持っている。

小さな script repository には重いかもしれません。File が数個だけなら、graph より diff を直接読むほうが早いです。また、これは test の代替ではありません。Impact graph は見るべき場所を示しますが、behavior の正しさを証明するものではありません。

使うときの境界

第一に、impact graph は実際の engineering convention と一緒に読む必要があります。Tool は file と relationship を分析できますが、team 内部の module boundary、runtime constraint、過去の妥協までは必ずしも知りません。

第二に、graph を新しい形式主義にしないことです。毎回生成しても、それをもとに判断しないなら、process に一手増えるだけです。High-risk changes、cross-module changes、agent による大きな変更、review の論点がある場合に使うほうが現実的です。

第三に、AGPL-3.0 license には注意が必要です。CLI を内部利用するだけなら多くの team で扱いやすいはずですが、product、service、distribution flow に組み込むなら、open-source compliance process で確認したほうがよいです。

まとめ

LegacyCodeHQ/clarity-cli の価値は、AI coding agent を置き換えることではありません。Agent の変更に、review 可能な structure view を足すことです。「今回の変更は何に影響したのか」を一文の自然言語 summary から、repeatable に生成でき、review に置ける code impact graph に近づけます。

よい着眼点だと思います。AI が code を速く書くほど、人間にはよりよい review entry point が必要になります。Test は behavior がまだ成立するかを教え、type check は interface がつながるかを教えます。Impact graph は design layer の揺れを見せてくれます。Agent を実際の codebase 変更に使い始めている team なら、一度試す価値があります。

リポジトリ：https://github.com/LegacyCodeHQ/clarity-cli