乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 架构文档别再靠手画了:推荐两个我很喜欢的 AI 架构图 Skill

架构文档别再靠手画了:推荐两个我很喜欢的 AI 架构图 Skill

当前时间： 2026-06-04 11:29:53 更新时间： 2026-06-04 分类：软件教程 评论(0)

架构文档别再靠手画了:推荐两个我很喜欢的 AI 架构图 Skill

很多团队的架构文档有一个共同问题：不是没有图，而是图很快就过期；不是没人会画，而是没人愿意维护。

今天推荐两个互补的架构文档生成 skill：

  • • c4-architecture
  • • Cocoon-AI/architecture-diagram-generator

它们解决的是同一个问题的两个侧面：一个负责把架构讲清楚，一个负责把架构画漂亮。

一、先说结论：两个都值得装

c4-architecture 更适合做“长期维护的架构文档”。

它基于 C4 模型，用 Mermaid 生成 Context、Container、Component、Deployment、Dynamic 等不同层级的架构图，默认输出到 docs/architecture/。它的强项不是炫技，而是结构清晰、可版本化、适合进仓库。

architecture-diagram-generator 更适合做“对外展示的架构图”。

它会生成一个深色主题的 HTML/SVG 架构图，视觉效果更精致，还内置 Copy、PNG、PDF 导出能力。它适合放进周报、方案评审、客户材料、融资 deck、技术分享 PPT。

一句话：

  • • 想让团队理解系统边界，用 c4-architecture
  • • 想让别人一眼看懂并愿意转发，用 architecture-diagram-generator
  • • 想把架构文档做成体系，两个一起用

二、为什么 C4 仍然是架构文档的好底座

很多架构图失败，不是因为画得丑，而是因为抽象层级混乱。

比如一张图里同时出现：

  • • 用户
  • • React 页面
  • • 某个函数
  • • Kafka
  • • AWS VPC
  • • Redis key
  • • 某个 cron job

这些东西都是真的，但放在同一张图里，读者会失去方向。

C4 模型的价值就在这里：它强迫你按层级表达系统。

常见四层是：

  • • Context：系统和外部用户、外部系统的关系
  • • Container：应用、服务、数据库、消息队列等可部署单元
  • • Component：某个服务内部的重要模块
  • • Deployment：生产环境里的基础设施部署关系

c4-architecture 里一个非常实用的判断是：多数团队其实只需要 Context + Container 两张图。这句话很重要。

因为架构文档最怕“为了完整而完整”。组件图、部署图、动态流程图都很有用，但前提是它们真的能帮助读者做决策。

我的建议是：

  • • 新项目：先生成 Context + Container
  • • 微服务项目：补关键业务链路的 Dynamic 图
  • • 平台型项目：补 Deployment 图
  • • 复杂服务内部：只给核心领域补 Component 图

不要从“我要画几张图”开始，而要从“谁要读这份文档”开始。

三、c4-architecture 的最佳使用方式

我会把它当成“架构文档生成器”，而不是“架构图生成器”。

推荐工作流：

  1. 1. 让 Agent 先分析代码库
  2. 2. 识别系统边界、外部依赖、主要容器、数据存储、消息流
  3. 3. 生成 docs/architecture/c4-context.md
  4. 4. 生成 docs/architecture/c4-containers.md
  5. 5. 必要时再生成 c4-dynamic-{flow}.md

可以直接这样提问：

使用 c4-architecture skill 分析这个代码库，生成架构文档。优先输出 C4 Context 和 C4 Container 两张图。请说明系统边界、外部依赖、主要服务、数据库、消息队列和关键数据流。输出到 docs/architecture/。

如果是微服务，可以加一句：

如果发现服务间异步通信，请不要只画一个 Kafka 大盒子。请把关键 topic / queue 作为独立容器表达，并标注发布和订阅关系。

这个要求很关键。很多架构图把 Kafka、RabbitMQ、Redis Stream 画成一个“消息中间件”盒子，看似简洁，实际丢掉了系统行为。真正有价值的是：谁发布什么事件，谁消费什么事件，这才是后续排查问题和讨论演进的基础。

四、什么样的 C4 图才算好图

可以用这几个标准检查：

第一，每个元素都有明确身份。不要写“服务 A”“数据库 B”，而要写“Order Service / Spring Boot / 处理订单生命周期”。

第二，箭头必须是动作。不要只写 “uses”，要写 “Submits order”“Reads inventory”“Publishes order.created”。

第三，技术标签要服务理解。比如 HTTPS/JSON、gRPC、JDBC、Kafka topic，这些信息能帮助读者理解调用方式和故障边界。

第四，一张图不要超过 20 个元素。超过之后就拆图。架构图不是数据库 ER 图，也不是资产清单。

第五，避免双向箭头。双向箭头通常意味着“我还没想清楚”。如果真的是双向交互，也拆成两个有方向、有语义的关系。

五、再说 Cocoon 的 Architecture Diagram Generator

如果说 C4 图解决“结构化表达”，那 Cocoon 这个 skill 解决的是“呈现质量”。

它生成的是一个自包含 HTML 文件，内部用 SVG 画图，带深色技术风格、语义配色和导出工具。前端、后端、数据库、云服务、安全组件都有不同颜色，整体观感比普通 Mermaid 图更适合展示。

它特别适合这些场景：

  • • 技术方案评审首页图
  • • 客户演示材料
  • • 创业项目技术架构介绍
  • • README 里的项目总览图
  • • 周会、复盘、路演里的架构页
  • • 把复杂系统讲给非研发同学听

它的使用门槛也低：你不一定要有完整代码库，只要有一段架构描述，就能生成图。

例如：

Use your architecture diagram skill to create an architecture diagram from this description:- React web app and mobile clients- API Gateway routes traffic to User Service, Order Service, Product Service- User Service uses PostgreSQL- Product Service uses Elasticsearch- Order Service publishes order.created events to Kafka- Inventory Service consumes order.created and publishes stock.reserved- Services run on Kubernetes- CloudFront serves static assets- Auth uses OAuth 2.0 / JWT

生成后，你可以继续让它改：

把认证链路用安全颜色高亮。把 Kafka topic 放在服务之间，不要和服务框重叠。增加一个 AWS Region 边界。导出图适合放进技术方案 PPT。

这就是它的优势：不是一次性生成，而是可以通过对话持续调图。

六、两个 Skill 合起来，效果最好

我推荐的组合打法是：

先用 c4-architecture 生成“可信的架构事实”。

它负责回答：

  • • 系统边界是什么？
  • • 谁是外部用户？
  • • 谁是外部系统？
  • • 哪些是可部署单元？
  • • 数据存在哪里？
  • • 服务之间如何通信？
  • • 哪些链路是同步，哪些是异步？

然后用 architecture-diagram-generator 生成“适合传播的视觉版本”。

它负责回答：

  • • 这张图是否一眼可读？
  • • 是否适合放到 PPT？
  • • 是否适合给老板、客户、产品、运营看？
  • • 是否能导出 PNG/PDF？
  • • 是否比普通 Mermaid 更有展示质感？

简单说：

C4 图进仓库，HTML/SVG 图进沟通材料。

这是我认为最实用的分工。

七、一个可落地的团队规范

可以在团队里定一个很轻量的规则：

每次有以下变更，PR 必须更新架构文档：

  • • 新增服务
  • • 新增数据库或存储
  • • 新增外部依赖
  • • 新增消息队列 topic
  • • 关键调用链变化
  • • 部署拓扑变化
  • • 认证、鉴权、安全边界变化

文档结构可以这样放：

docs/  architecture/    c4-context.md    c4-containers.md    c4-dynamic-order-flow.md    c4-deployment.mddiagrams/  system-overview.html  system-overview.png

其中：

  • • docs/architecture/*.md 用 c4-architecture 维护
  • • diagrams/*.html/png 用 Cocoon 的 diagram generator 维护
  • • README 里只放最核心的一张总览图
  • • 复杂说明链接到 docs/architecture/

这样既不会让 README 爆炸，也不会让架构信息散落在各种聊天记录和 PPT 里。

八、最后的建议

AI 生成架构图的关键，不是“让它画一张图”。

真正有效的方式是：先让 AI 帮你建立架构事实，再让 AI 帮你选择表达层级，最后才是视觉呈现。

c4-architecture 的价值在于严谨。它让架构文档更像工程资产。

architecture-diagram-generator 的价值在于传播。它让架构图更像沟通资产。

一个负责准确，一个负责好看。一个适合长期维护，一个适合快速展示。

架构文档最理想的状态，不是画完以后放在那里，而是随着系统演进一起生长。这两个 skill 搭配起来，已经很接近这个状态了。