夜雨聆风很多团队的架构文档有一个共同问题：不是没有图，而是图很快就过期；不是没人会画，而是没人愿意维护。
今天推荐两个互补的架构文档生成 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. 让 Agent 先分析代码库 2. 识别系统边界、外部依赖、主要容器、数据存储、消息流 3. 生成 docs/architecture/c4-context.md4. 生成 docs/architecture/c4-containers.md5. 必要时再生成 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 搭配起来，已经很接近这个状态了。
