为什么我给每个AI编码代理都装上了Archify：一份可验证架构图的完整理由

为什么我给每个AI编码代理都装上了Archify一份可验证架构图的完整理由【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archifyArchify 是一个面向 AI 编码代理的 Agent Skill它把代码库或一句自然语言描述变成可验证、可交互、单文件即可分享的架构图、工作流图、时序图、数据流图和状态生命周期图。装完之后你只需要对 Cursor、Claude Code、Codex CLI 说一句话代理就会产出带有完整校验回执的 HTML 图——打开浏览器就能演示导出的 PNG/SVG 可以直接贴进 README。为什么是可验证而不是画得好看大多数 AI 画图工具给你一张看起来像那么回事的图。Archify 的差别在于每张图交付前都必须通过机器校验不通过就不交付。它的渲染流程是固定的五步你用自然语言描述系统或贴一段 MermaidAI 代理推断组件之间的空间关系产出类型化 JSON IR先过 JSON Schema 校验类型化渲染器 布局规则检查节点重叠、标签越界、跨泳道冲突都会被点名生成独立 HTML支持主题切换和 4x 高清导出关键在第三步。校验失败时Archify 返回的不是一个 Node 堆栈而是一份结构化修复回执稳定的规则码、出错的精确对象、测量证据、以及当前渲染器支持的修复动作。AI 代理可以直接照着回执修 JSON 再跑一遍——这就是可验证的实际含义图上的每一条边、每一个坐标都是被检查过的断言而不是模型的自由发挥。这套契约写在 archify/SKILL.md 里普通用户不需要读它但你心里有数代理的行为是有边界的。一键安装给 AI 编码代理装上 Archify安装只有一行命令Node.js 18 即可npx skills add tt-a1i/archify -gCursor / Claude Code / Codex / OpenCode安装完 Skill 文件自动落位代理在会话里即可发现并调用只想试一下npx skills use tt-a1i/archifyarchify --agent codex无需安装装完自检node bin/archify.mjs doctor然后直接下指令这是官方推荐的有边界的问法分析这个仓库然后用 archify 生成一张高层运行时架构图。展示 8–12 个核心组件、一条主路径、外部依赖和信任边界把次要细节放进说明卡片不要加更多连线。接着在聊天里继续微调加上 Redis、把 auth 挪到左边、高亮回滚路径——代理会在类型化源码上做定向迭代而不是每次重画整张图。五种图类型一张就能讲清一类问题类型适合回答的问题起点示例Architecture组件、服务、存储、边界怎么划分archify/examples/web-app.architecture.jsonWorkflowCI/CD、审批、工具调用的顺序与分支archify/examples/agent-tool-call.workflow.jsonSequenceAPI 调用链、缓存回源、认证时序archify/examples/cache-miss-request.sequence.jsonData Flow数据从哪来、怎么变、谁在消费archify/examples/product-analytics.dataflow.jsonLifecycle状态、重试、等待与终态archify/examples/agent-run.lifecycle.json产出的不只是静态图片。打开任意生成的 HTML按P就能播放代理预先编排好的章节故事按/搜索定位节点按R追踪一条有向路径——而且所有交互都只复用图中已定义的事实绝不编造拓扑。合并前先看变更Before / Delta / After 审查视图这是我装机后使用频率最高的功能。Architecture Delta 会把两个已验证的架构快照放在一起输出精确的新增 / 移除 / 变更 / 移动 / 改道事实清单附机器回执node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json /parameter对 AI 协作开发来说这很关键代理改完代码你不用猜结构动了哪里直接看 Delta 页签里的 2 个新增、2 个移除、5 个变更——每一处都可以点选定位还能逐条播放 Review。它诚实地只陈述图里改了什么不替你做风险评估但事实部分零幻觉。为什么坚持AI 判断布局拒绝自动布局Archify 在 Roadmap 里写了一句少见的大实话Auto-layout (dagre / elk-js) is a dead end。这不是拍脑袋而是先跑了一个盲测五张真实 Mermaid 图各渲染三个版本——A 原生 Mermaid、B 同样自动布局但换上 Archify 配色、C 由 AI 做布局判断。15 张截图打乱盲评结论是A 得 4 分B 还是 4 分C 得 9 分。只换皮不换布局审美差距无法弥合。因为好看的架构图靠的不是配色而是空间叙事Auth Provider 为什么浮在 AWS 边界外S3 为什么画在 CDN 下方这些谁属于谁、谁在外面、什么该靠在一起的判断是 AI 对语义的理解自动布局引擎给不了。什么时候它不划算诚实的局限图太大30 节点的跨 region 拓扑AI 会丢掉全局结构这时候均匀网格反而不出错你描述不清楚只说画个架构图产出的图就没有信息架构它的布局质量上限就是你语义表达的上限图太小4 步审批流直接拖四个方块更快不必走完整 JSON IR 校验流程Archify 适合的是组件之间的空间关系本身就携带信息的图。写在最后装完 Archify 之后我改变了什么三个具体习惯给代理加图的任务时先加边界条件——组件数量、主路径、外部依赖产出质量立刻不一样PR 里带上 Delta 页让 reviewer 先看图变更再读 diff把校验回执当成 AI 的单元测试——9/9 检查全过才收图失败就看diagnostics定向修想自己动手从这两份文档开始就够docs/authoring-cookbook.md 是普通用户的操作手册archify/schemas/README.md 是五类图的字段参考。本地想直接试玩完整查看器打开 examples/web-app.html 即可。给 AI 装上一套必须通过校验才能交卷的画图纪律比再多一个画图工具更有价值。这就是我把 Archify 装进每个 AI 编码代理的完整理由。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考