Archify 是一个开源的 Agent Skill：让 Claude Code、Cursor、Codex CLI 或 OpenCode 里的智能体直接读代码仓库，产出可交互、可校验的架构图 HTML。流程是先由 Agent 生成类型化 JSON IR，再交给 Archify 按确定性规则校验后渲染——校验不过就报具体错误，而不是交一张「好看但说谎」的图。项目已有 3 万+ Star、冲上 GitHub 热榜，团队里架构图总过期的同学，这是目前最直接的解法。
为什么值得关注
大多数架构图两周后就失效了：画一次主链路，代码继续演进，图慢慢变成没人敢改的历史文物。Archify 从源头解决这个问题——它不渲染手写的描述，而是让 Agent 读真实代码、产出类型化 JSON IR，再由 Archify 确定性编译成图。整个过程 fail-closed：schema、节点布局、标签或连线任一校验失败，都会返回具体错误和允许的修法，绝不输出一张「看着漂亮、实际是错的」图。它兼容四种主流 Agent、与具体模型无关，安装零配置、本地渲染。
原理：JSON IR → 确定性校验 → 渲染
Archify 把「理解」和「画图」拆开——这两个环节合在一起最容易出错。Agent 负责理解：读代码、识别组件与关系，按 Archify schema 产出 JSON IR；Archify 负责校验与渲染：结构、布局、标签、连线冲突全部过一遍，不合格直接拒绝。一段精简的 IR 长这样：
{
"type": "architecture",
"theme": "dark",
"nodes": [
{ "id": "browser", "label": "Browser", "kind": "client" },
{ "id": "api", "label": "API Gateway", "kind": "service" },
{ "id": "cache", "label": "Redis Cache", "kind": "store" },
{ "id": "db", "label": "PostgreSQL", "kind": "store" }
],
"edges": [
{ "from": "browser", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "cache", "label": "read/write" },
{ "from": "api", "to": "db", "label": "fallback" }
]
}校验通过后才渲染成单文件 HTML/SVG：节点可搜索、任意两点可追踪调用路径、可看上下游，深浅主题随意切换，导出 PNG/SVG/WebM/分享卡片。支持五类图——架构、工作流、时序、数据流、生命周期——外加三套视觉预设（Classic、Signal Flow、Blueprint）。这种「先验证再交付」的思路，跟 Agent 幻觉检测是同一个方向，两者可以搭配使用。
一条命令装好，兼容四种 Agent
Archify 以标准 Agent Skill 分发，安装就一行：
npx skills add tt-a1i/archify -g装完自动落到 Agent 已有的技能目录：Claude Code 读 ~/.claude/skills，Codex CLI 读 ~/.agents/skills，Cursor 走技能管理器。不需要 API Key、没有云端服务、不用起服务器，全部本地渲染。
第一次出图：一条 Prompt 生成运行时架构图
打开一个你想搞懂仓库，直接让 Agent：
分析这个仓库，然后用 archify 生成一张高层运行时架构图：8-12 个核心组件、一条主路径、外部依赖和信任边界，次要细节放进卡片而不是加更多连线。「限制视图」比看起来更重要：8-12 个组件 + 一条主路径 + 信任边界，能拦住 Agent 把所有文件都塞进图里——这决定了你拿到的是「有人读的图」还是「一张壁纸」。如果你已经清楚系统长什么样，想快速要张干净流程图，也可以直接描述：
用 archify 画登录链路：Browser -> Web App -> API -> JWT 校验 -> Redis 会话查询 -> PostgreSQL 兜底，缓存未命中的路径保持次要。进阶：Delta 对比做代码评审
最容易被低估的是 Delta 视图：Archify 能对比两个已校验快照，以 Before / Delta / After 的方式标出新增、删除、改动、移动和重路由的节点。架构图从此不是一次性产物，而是能参与 PR 评审——在 base 分支和 PR 分支各跑一次，直接看差异，不用把整个系统重新读一遍。如果你的发布管线里已经开始跑智能体，建议配合 AI-Native SDLC 实操手册 搭 Agent 友好的 CI 与评审流程；Agent 要跑长任务时，再补上 Agent 可恢复状态实战 这篇做状态与断点。
注意事项
- 一定要给有界视图。不限范围地「把图全画出来」，出来的图根本没法读。
- 把生成的 HTML 提交进仓库，合并时重新生成——把它当必须保持最新的文档。
- PR 评审用 Delta 视图，能精确看出两个版本之间改了什么。
- 支持的情况下把节点钉到可回溯的源文件上，让图带证据、不靠「感觉」。
Archify 不是运行时监控，无法证明图与线上完全一致——准确性仍取决于代码、Prompt 和 Agent 的分析。但要把一个陌生代码库在几分钟内变成可导航的系统地图，它目前是开源阵营里最好的选择。
FAQ
Q：Archify 支持哪些编程 Agent？
A：Claude Code、Cursor、Codex CLI 和 OpenCode，用 npx skills add tt-a1i/archify 装成标准技能，底层换任何模型都能跑。
Q：Archify 只是更好看的 Mermaid 吗？
A：不是。Mermaid 只渲染你写的文本；Archify 渲染前先校验类型化 JSON IR，输入不对就失败并说明原因，还带可搜索交互和 PR 评审用的 Before/Delta/After 对比。
Q：生成的架构图反映线上真实状态吗？
A：不会自动反映。它不是监控工具，准确性取决于读到的代码、你的 Prompt 和 Agent 的分析；在最新代码上跑、合并时重新生成即可。
