Clarity CLI - 给 AI coding agent 一张可复查的代码影响图
AI coding agent 最容易显得“很会写代码”的时刻，往往也是最需要复查的时刻。它可以快速改动多个文件、补测试、迁移接口，甚至顺手重排目录。问题是，人类 review 时不只关心 diff 本身，还关心这次改动到底碰到了哪些模块、哪些路径变得更耦合、哪些测试或文档应该跟着变化。
今天推荐的 LegacyCodeHQ/clarity-cli 试图把这件事做成命令行工具。它用 Go 编写，定位是面向 AI-native developers 和 coding agents 的软件设计工具，通过 clarity watch 和 clarity show 生成代码影响图，让开发者在提交前看到当前变更会影响哪些文件和关系。GitHub 页面当前显示项目约 40 stars、2 forks，主要语言为 Go，许可证为 AGPL-3.0，仓库创建于 2026 年 1 月，最近提交在 2026 年 6 月，最新 release 为 v0.19.1。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | LegacyCodeHQ/clarity-cli |
| 定位 | 面向开发者和 coding agent 的代码影响图与设计审查 CLI |
| Stars | 约 40 |
| Forks | 2 |
| 主要语言 | Go |
| 许可 | AGPL-3.0 |
| 最新 release | v0.19.1 |
| 安装方式 | npm、Homebrew、预编译二进制、源码构建 |
它关心的是设计影响，而不是再生成一份摘要
现在很多 AI 工具都能解释 diff，但解释通常停留在自然语言层面：改了什么、为什么改、可能有什么风险。Clarity CLI 的角度更结构化。README 写得很直接：它会从代码生成 impact graphs，让你在 commit 前 review design effects。
这意味着它不是单纯把变更摘要化，而是尝试把文件之间、变更之间、测试之间的关系画出来。比如你可以用 clarity show 查看未提交变更，也可以用 clarity show -c HEAD 看最近一次提交，或者用 clarity show -c HEAD~3...HEAD 看一段提交范围。
这类视图适合回答三个很具体的问题：
- 这次变更实际触碰了哪些区域？
- 解法的结构是什么样子？
- 哪些模块现在被拉到了一起？
这些问题往往比“代码能不能跑”更难自动化，因为它们需要把局部 diff 放回项目结构里看。
watch 给开发过程一个实时视角
Clarity 的两个核心命令里，clarity watch 更偏开发中的持续反馈。你在项目里运行它之后，可以在编码过程中保持一个 live impact view。对正在拆分模块、移动接口、补测试的人来说，这有点像把架构影响从“提交后复盘”提前到“改动过程中观察”。
这件事对 agent workflow 也有意义。agent 很擅长连续执行小步骤，但它很容易在上下文里只盯住当前 patch。如果每一轮关键改动之后都能生成一张影响图，人类就能更快判断它是否在沿着正确的设计方向前进。
当然，watch 不是质量保证。它不会替代测试、类型检查或人工 review。它更像一个结构雷达：当改动范围突然扩大、某个不该被影响的目录被牵动、测试路径没有跟上时，它能让这些信号更早出现。
show 更适合放进 review 和 agent 回合
clarity show 是更适合自动化流程的命令。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这几种模式分别覆盖未提交变更、单个提交、提交范围、指定目录，以及两个文件之间的路径关系。对 review 来说，价值在于把“这次改动的范围”从主观描述变成可重复生成的检查材料。
我更看重的是它和 coding agent 的配合方式。Clarity 提供 clarity setup，会把 agent 使用 Clarity 的说明写进 AGENTS.md。这样一来，agent 不需要每次都被临时提醒，它可以在有意义的改动后运行 clarity show，并把输出作为设计复查的一部分。
这符合一个更成熟的 agent 使用方式：不是让 agent 自己宣称“我已经检查过”，而是让它产生可被人类复核的中间证据。
支持语言覆盖了不少真实项目
README 当前列出 Clarity 支持 17 种语言，包含 C、C++、C#、Dart、Go、JavaScript、Java、Kotlin、Markdown、Python、Ruby、Rust、Scala、Svelte、Swift、TypeScript 和 Zig。它也提醒解析质量会因语言而异。
这条提醒很重要。代码结构分析工具很容易被宣传成“理解所有代码”，但不同语言的 import、模块、测试、生成文件和框架约定差异很大。把解析质量的差异提前写出来，反而更可信。
对实际使用来说，我会先在单个仓库里试它，而不是马上把它放进所有项目。尤其是 monorepo、生成代码很多、路径别名复杂的项目，第一步应该是看它生成的图和团队对架构边界的理解是否一致。
安装路径对跨平台使用比较友好
Clarity CLI 的安装方式比较完整。README 和安装文档都提到可以用 npm 全局安装：
npm install -g @legacycodehq/claritymacOS 和 Linux 用户也可以使用 Homebrew：
brew install LegacyCodeHQ/tap/clarity此外，项目在 releases 页面提供预编译二进制，也可以从源码构建。源码构建需要 Go 1.21+ 和 CGO enabled：
git clone https://github.com/LegacyCodeHQ/clarity-cli.git
cd clarity-cli
make build-devnpm wrapper 的 package.json 声明支持 macOS、Linux、Windows，以及 x64、arm64 架构。对一个希望进入 agent workflow 的 CLI 来说，跨平台安装不是小事，因为 agent 实际运行的机器可能是本机、远端开发机、容器或 CI runner。
适合哪些场景
Clarity CLI 更适合这些场景：
- agent 或人类一次改动会跨多个模块。
- review 关注的不只是代码风格，而是设计边界和耦合变化。
- 想把“影响范围”作为提交前的固定检查材料。
- 希望 agent 在改动后提供可复查的结构证据。
- 团队已经有
AGENTS.md或类似的 agent 操作约定。
它不一定适合很小的脚本仓库。只有几个文件时，图反而可能比直接看 diff 更重。它也不是测试替代品；影响图能提醒你应该看哪里，但不能证明行为正确。
使用时要留意的边界
第一，影响图要和真实工程约定一起看。工具能分析文件和关系，但未必知道团队内部的模块边界、运行时约束和历史妥协。
第二，不要让图变成新的形式主义。如果每次变更都生成图，但没有人据此做判断，它就只是在流程里多加一步。更好的做法是把它用于高风险改动、跨模块改动、agent 大改动和 review 争议点。
第三，AGPL-3.0 许可证需要留意。如果只是内部使用 CLI，通常问题不大；如果要把它嵌入产品、服务或分发流程，就应该按团队的开源合规流程确认。
总结
LegacyCodeHQ/clarity-cli 的价值不在于替代 AI coding agent，而在于给 agent 的改动加上一层可复查的结构视图。它把“这次改动影响了什么”从一句自然语言说明，推进到可以重复生成、可以放进 review 的代码影响图。
我喜欢它切中的点：AI 写代码越快，人类越需要更好的审查入口。测试告诉我们行为是否还成立，类型检查告诉我们接口是否连得上，而影响图可以帮助我们看见设计层面的波动。对已经开始让 agent 参与真实代码库修改的团队来说，这类工具值得试一试。