技能使用指南

c4-architecture（C4架构文档生成）Skill 是什么？

一文讲清 c4-architecture（C4架构文档生成）Skill：按 C4 模型自动生成 Mermaid 系统上下文图、容器图、组件图、部署图与动态图，并规范写入 docs/architecture 目录。含安装思路、使用步骤、竞品对比与典型场景，帮团队把架构文档变成可进 Git、可评审的活文档，立即上手试试。

C4架构文档生成Skillc4-architecture
8 个章节 约 17 分钟阅读 AI 智能生成

C4架构文档生成Skill：把系统架构画成 Mermaid 图，让文档自动生成

核心结论速览

  • 这是一个把「C4 模型」和「Mermaid 图表」结合起来的 AI 技能，专门负责把软件系统画成分层架构图并写成 Markdown 文档。
  • 它支持 C4 的五类视图：系统上下文图（C4Context）、容器图（C4Container）、组件图（C4Component）、部署图（C4Deployment）以及动态请求流图（C4Dynamic）。
  • 它内置了完整的元素语法、布局与样式配置知识，还附带最佳实践、常见反模式、微服务与事件驱动建模指南，能有效避免"画得像但画错了"。
  • 输出有规范：架构文档统一写入 docs/architecture/，并按 c4-context.md、c4-containers.md 等约定命名，团队协作时不会再出现"文档散落一地"。
  • 适用范围明确：上下文图 + 容器图对大多数开发团队已经足够，只有在真正产生价值时才建议往下画组件图。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 C4架构文档生成Skill
技能英文名 c4-architecture
技能ID 12299
核心能力 使用 C4 模型的 Mermaid 图生成软件架构文档

它解决什么问题？

在真实项目里，架构图往往是最容易"欠债"的文档：系统上线了，图还停留在两年前的 PPT 里；新同事入职只能靠口头讲解"我们有几个服务、谁调谁"；评审会上有人说"这个服务属于哪个系统"，没人能当场说清。手动画图又很痛苦——打开绘图工具、拖框、连线、调对齐，画完还得贴进文档，改一次全都得重来。

C4架构文档生成Skill 做的事情很直接：由 AI 读懂你的系统（或听你描述），按 C4 模型的标准分层，直接输出可渲染的 Mermaid 代码，并写成带解释性上下文的 Markdown 文档。因为 Mermaid 是纯文本，架构图从此可以进 Git、可以 review、可以 diff，改起来就像改代码一样。

它的触发场景也很清晰，当你说出"架构图"“C4图”“系统上下文”“容器图”“组件图”“部署图”“文档架构”"可视化架构"等词时，就是它该出场的时候。

一键安装的思路与步骤

安装方面，该技能以技能包形式提供（包含技能主文件与 references/ 参考文档，如 c4-syntax.md、common-mistakes.md、advanced-patterns.md）。通用流程如下，具体命令、入口与版本要求请以官方说明为准：

  1. 确认前提：你已经有一个支持 AI 技能（Skill）机制的客户端或开发环境，并具备把技能添加到工作区的权限；如果你希望技能能直接分析代码库，还需要让它能访问对应仓库目录。
  2. 获取技能：通过官方技能市场、技能仓库或官方提供的安装入口，搜索技能英文名 c4-architecture（或技能ID 12299）并添加。
  3. 完成安装：按官方说明执行安装动作（可能是点击安装按钮，也可能是官方提供的安装命令，以官方说明为准），并确认技能的 references/ 目录一并就位——这些参考文件决定了语法与反模式知识的完整度。
  4. 验证是否生效：新建一个会话，直接说"帮我画一个系统上下文图，系统叫订单中心"，观察它是否输出 C4Context 开头的 Mermaid 代码块并附带解释。如果只得到普通文字回复，说明技能未加载成功，可检查安装状态或重新启用。

这种"安装一次、长期复用"的方式，正是 AI 技能提升开发效率的关键：把方法论固化进技能，而不是每次对话都重新教 AI 一遍 C4 规则。

2. 该技能的主要功能和特点

  • 五类 C4 视图全覆盖：从最外层的系统上下文，到容器、组件、部署，再到带编号的请求流动态图，一个技能覆盖架构表达的完整梯度。
  • 输出可直接渲染的 Mermaid 代码：不是生成一张不能编辑的图片，而是生成可进版本库的文本图表，天然适配 Markdown、GitLab/GitHub 渲染与代码评审流程。
  • 有明确的分层判断逻辑：技能内置"上下文 + 容器图对大多数开发团队足够"的关键原则，只在真正增加价值时才建议创建组件图，避免过度建模。
  • 掌握完整元素语法：Person、System、System_Ext、SystemDb、SystemQueue、Container、ContainerDb、ContainerQueue、Component、各类 Boundary、Rel 及其方向变体、Deployment_Node，都能按需正确使用。
  • 内置样式与布局控制：通过 UpdateLayoutConfig 调整每行形状与边界数量，通过 UpdateElementStyle、UpdateRelStyle 调整颜色与标签偏移，解决"关系标签重叠"这类真实痛点。
  • 自带最佳实践与反模式清单：单向箭头、动作动词标注、技术标签、单图少于 20 个元素、每文件一张图、有意义的别名、标题必须存在等规则会被主动遵守；同时避免"混淆容器与组件"“把共享库当容器”"把 Kafka 画成一个框而不是按主题拆分"等典型错误。
  • 覆盖微服务与事件驱动建模：单团队拥有时把微服务建模为容器，多团队拥有时提升为软件系统；事件驱动架构中按主题/队列建模而不是画一个大消息中间件。
  • 按受众裁剪细节：高管只看系统上下文，产品经理看上下文 + 容器，架构师看上下文 + 容器 + 关键组件，DevOps 看容器 + 部署，输出不浪费也不缺失。
  • 有固定的产出规范：统一写入 docs/architecture/，按 c4-context.md、c4-containers.md、c4-components-{feature}.md、c4-deployment.md、c4-dynamic-{flow}.md 命名。

和普通绘图工具比，它强在"懂模型"：绘图工具只提供画布，而它提供的是分层方法论 + 语法正确性 + 文档结构。

3. 如何使用该技能？

第 1 步：说明范围与受众

先告诉它这次文档给谁看、要覆盖到哪一层。例如：

我要给新入职的开发和运维做一份架构文档，系统是一个 Vue PWA 健身记录应用，数据存在浏览器 IndexedDB 里，请先出系统上下文图和容器图。

受众决定了级别：高管只出上下文图，DevOps 建议加部署图。

第 2 步：让它分析代码库（可选但推荐）

如果技能能访问仓库，可以直接说"分析这个仓库，识别出容器和它们之间的关系"。它会先探索系统、识别组件与容器，再生成图表，比纯口述准确得多。

第 3 步：确认图表级别

按需求选择级别：C4Context（必需）、C4Container（必需）、C4Component（仅当增加价值）、C4Deployment（用于生产系统）、C4Dynamic（用于复杂工作流）。技能会按这张判断表给出建议。

第 4 步：获取 Mermaid 图表代码

你得到的是一段可直接渲染的代码，例如容器图：

C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

第 5 步：微调样式与布局

如果截图里标签挤在一起，可以让它用偏移量修复：

UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

元素太多看不清，就调整每行数量：

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

第 6 步：写入文档文件

让它把图表连同解释性上下文写入 docs/architecture/ 下对应文件，例如系统上下文写入 c4-context.md、容器写入 c4-containers.md、登录流程写入 c4-dynamic-sign-in.md。每个文件只放一张图，保持单一抽象级别。

第 7 步：复查清单

检查每张图是否满足：元素都有名称、类型、技术（如适用）与描述；箭头全是单向；箭头标注用了动作动词（“读取自”“发布到”）而非笼统的"使用"；技术标签存在（如 “JSON/HTTPS”、“JDBC”）；单图元素少于 20 个；图有标题。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
C4架构文档生成Skill AI 驱动的 C4 架构文档生成 按 C4 分层生成 Mermaid 上下文/容器/组件/部署/动态图，并写入规范文档目录 需支持技能机制的 AI 环境，安装一次即可；以官方说明为准 需要持续维护、可进版本库的架构文档 优势：分层方法论 + 语法正确 + 反模式护栏 + 文本可 diff；不足：产出为 Mermaid 表达能力范围内的图，复杂视觉定制不如专业绘图软件
通用绘图工具（如各类拖拽式画图软件） 手工可视化 自由拖拽、任意样式、导出图片 无技术门槛，但需要人工设计 汇报 PPT、一次性示意图 优势：视觉自由度高；不足：无法版本化对比、改一次重画一次、容易画出不规范的"伪 C4"
通用 AI 对话直接画图 通用生成 能生成 Mermaid 或描述性图表 门槛最低 临时看个大概 优势：随问随得；不足：缺乏 C4 级别判断、元素语法易错、无统一命名与目录规范、易出现容器与组件混淆
C4 建模专用工具（以官方说明为准） 结构化建模 严格的分层元素模型与校验 需要学习工具自身概念与授权 架构治理严格的组织 优势：模型严谨、可校验；不足：学习成本高、产出格式绑定工具、与代码仓库的协作链路较长

选型建议：如果团队已经在用 Markdown + Git 管理文档，C4架构文档生成Skill 的契合度最高；如果只是给一次会议配图，通用绘图工具或通用 AI 对话更省事。

5. 该技能的典型应用场景与实际体验情况

场景一：新系统立项，需要一份"人人看得懂"的架构总览

角色：技术负责人 / 架构师。痛点：向业务方和高管解释"我们到底建了几个系统、依赖哪些外部服务"时，缺乏一张权威的边界图。使用方式：先让它生成级别 1 的系统上下文图，把系统、外部人物、外部系统与浏览器等依赖画清，再补一张容器图给技术团队。实际体验：上下文图几乎是"必出且必有用"的一张，界定系统范围的效果最明显；注意事项是别急着往组件层钻，容易一上来就过度建模。

场景二：老项目交接，把散落的架构知识固化成文档

角色：接手维护的开发者。痛点：代码能跑但没人说得清模块关系。使用方式：让技能分析代码库，识别容器、数据库、服务与依赖关系，输出 c4-containers.md 并附解释性上下文。实际体验：对"容器层"识别通常最顺畅，因为容器是可部署单元、边界清晰；需要注意技能会主动避免把共享库误建模成容器，这一点比自己手画可靠；如果系统特别大，按"每图少于 20 个元素"原则拆成多张图，比硬塞进一张更清楚。

场景三：微服务与事件驱动架构的评审材料

角色：后端工程师 / 平台团队。痛点：画微服务图时最常见的争议是"一个服务算系统还是算容器"，以及"Kafka 画一个框还是按主题拆"。使用方式：按团队归属决定——单一团队拥有时把微服务建模为容器，多团队各自拥有时提升为软件系统；事件驱动场景下把每个主题（如 order.created、stock.reserved）建模为独立容器。实际体验：这套规则能直接消解评审会上大半的口水战，图也更经得起追问；注意事项是务必用动作动词标注关系（“发布到”“订阅自”），而不是统一写"使用"。

场景四：上线前的部署图与关键流程动态图

角色：DevOps / SRE。痛点：生产拓扑与真实容器编排对不上，出故障时没人能快速说清调用链。使用方式：用 C4Deployment 画部署节点（客户浏览器、云区域、集群、数据库实例），用 C4Dynamic 给登录、下单等复杂流程画带编号的请求流。实际体验：动态图的编号顺序对排查链路问题帮助很大；关系标签重叠时用 $offsetX/$offsetY 微调即可，不必换工具。

6. 该技能能为用户带来的价值

效率提升：过去从"想清楚"到"画完、贴进文档"往往要花掉半天到一天，现在主要成本变成"描述清楚系统"和"审阅产出"两件事，绘图与排版环节基本被压缩掉。改图也不再是重画，而是改几行 Mermaid。

门槛降低：C4 模型本身有学习曲线——什么算容器、什么算组件、什么时候该拆图，很多团队其实没统一。技能把这些判断规则内置了，团队新人不需要先读完整套方法论，也能产出符合规范的图。

质量与一致性提升：内建的最佳实践（单向箭头、动作动词、技术标签、单图元素上限、必须有标题、有意义的别名）与反模式清单（容器与组件混淆、把共享库当容器、把消息代理画成单框、自造"子组件"这类未定义抽象层级）会持续生效，避免团队各自画各自的。

长期价值：架构文档进 Git 之后，可以随代码一起 review、一起演进，文档腐化的速度显著下降；统一的 docs/architecture/ 目录与命名约定，让"架构图在哪"不再是问题。按受众裁剪细节的规则，还能减少为不同角色重复准备材料的浪费。

可量化的收益方向：可以用"单张图从绘制到入库的耗时"“架构评审中被追问边界问题的次数”“新人上手时需要的口头讲解时长”"架构文档的更新频率与代码变更的同步度"来衡量效果。

7. 常见问题 FAQ

Q1：怎么安装这个技能？需要付费吗？

A：通过官方技能入口搜索英文名 c4-architecture 或技能ID 12299 添加，安装命令、入口位置、是否需要授权与是否收费，均以官方说明为准。建议安装后用一个简单请求（如"画一个系统上下文图"）验证是否生效。

Q2：它生成的图是图片还是代码？能改吗？

A：生成的是 Mermaid 代码（如 C4Context、C4Container 等），可直接在支持 Mermaid 的 Markdown 环境中渲染，也可以像改代码一样修改元素、关系、样式与布局。这也是它比导出图片更适合长期维护的原因。

Q3：我是不是必须画满五层图？

A：不需要。技能明确建议"上下文 + 容器图对大多数软件开发团队足够"，组件图只在真正增加价值时创建，部署图用于生产系统，动态图用于复杂工作流。按受众选级别即可：高管只看上下文，产品经理看上下文 + 容器，DevOps 看容器 + 部署。

Q4：它和直接用 AI 聊天画架构图有什么区别？

A：通用对话能画出"看起来像"的图，但缺少分层判断和反模式护栏，容易出现容器与组件混淆、把消息中间件画成单框、关系全写"使用"等问题；本技能内置 C4 语法参考、常见错误清单与输出目录规范，产出更接近可以入库、可以评审的正式文档。

Q5：适合谁用？团队规模小值得用吗？

A：适合架构师、技术负责人、后端与平台工程师、DevOps/SRE，以及需要快速理解陌生系统的开发者。小团队同样值得用——正是因为人手少、没人专职写文档，把架构图变成几行可维护的文本，性价比更高。