c4-architecture

c4-architecture 技能概览

c4-architecture skill 的作用，不只是帮你“画几个框”，而是把软件架构文档系统化地生成为 Mermaid C4 图。它特别适合工程师、技术写作者、资深架构师，以及需要按受众层级来解释系统的团队：给广泛读者看上下文，给技术相关方看容器视图，给开发者看组件视图，给运维看部署视图。

c4-architecture 适合解决什么问题

当你的真实需求是把代码库、服务版图，或一份还比较粗糙的系统描述，整理成结构化的架构文档时，就该用 c4-architecture。如果你需要的不是一次性的白板导出，而是能直接放进 Markdown、进入版本控制持续维护的图，这个 skill 会尤其有用。

最适合的使用场景

这个 c4-architecture skill 很适合用于：

• 为现有 repo 补充架构文档，方便新人 onboarding
• 为 ADR 或技术文档生成 system context 和 container 视图
• 解释微服务、事件驱动系统，以及外部依赖关系
• 为 docs site、wiki 或 pull request 产出架构图
• 为 Technical Writing 工作流编写架构内容

它和普通画图提示词有什么不同

普通 prompt 也许能产出“像图一样”的结果，但这个 skill 提供了更清晰的工作流和更靠谱的默认方式：

• 以 C4 model 为中心，抽象层级更容易保持干净
• 把 Context 和 Container 视为基础，而不是可有可无的附加项
• 提供 Mermaid C4 图的语法指导
• 在你发布容易误导读者的文档之前，先提示常见建模错误
• 包含适用于微服务和复杂系统的高级模式

用户最先关心的通常是什么

在安装或调用 c4-architecture 之前，大多数用户首先会想知道：

• 如果我对系统只了解一部分，它还有用吗？有，只要你能提供角色、主要服务、数据存储和外部系统。
• 它适合 Markdown-first 文档吗？适合，Mermaid 输出正是它的核心价值。
• 对不具备深度架构背景的技术写作者有帮助吗？有，因为这个 skill 对层级划分和常见错误都有明确约束。
• 它能替代深入的架构评审吗？不能。它能加速首版草稿和结构化文档产出，但系统是否准确仍取决于你的输入。

如何使用 c4-architecture skill

在你的 skills 环境中安装 c4-architecture

如果你的 agent 支持本仓库使用的 skills CLI 模式，可以这样安装：

npx skills add softaworks/agent-toolkit --skill c4-architecture

如果你的环境是从克隆的仓库中加载 skills，则使用这里的 skill：

skills/c4-architecture

首次使用前，先读这些文件

如果你想快速获得一个高信息密度的 c4-architecture guide，建议按这个顺序阅读：

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

为什么这个顺序更有效：

• SKILL.md 说明了推荐工作流
• common-mistakes.md 能帮你避开最常见的建模错误
• c4-syntax.md 便于你快速排查 Mermaid 输出问题
• advanced-patterns.md 在你的系统不是简单单体时尤其重要

提示前先选对 C4 层级

c4-architecture usage 中，最影响输出质量的因素之一，就是是否为目标读者选对层级：

• C4Context：始终从这里开始；展示用户和外部系统
• C4Container：通常是必需的；展示应用、数据库、队列和服务
• C4Component：只有在内部结构确实能帮助读者理解时再加
• C4Deployment：用于运行时 / 基础设施相关内容
• C4Dynamic：用于展示关键请求流或事件流

一个很常见的失败模式，是一上来就跳到 component，结果在读者还没理解系统边界前，图就已经变得很杂乱。

给 skill 提供它真正需要的最小输入

你不需要准备一份完美的架构说明，但必须给出足够的结构信息，避免生成“脑补出来”的拓扑。比较好的输入包括：

• 系统名称和用途
• 主要用户或外部角色
• 关键服务 / 应用 / 数据存储
• 外部系统或 vendor
• 关键关系和协议
• 目标读者
• 希望生成的图层级
• 输出文件或文档位置

如果你只说“给我的 app 画一个 C4 图”，那就要预期输出会比较泛。

把模糊需求改写成高质量的 c4-architecture prompt

弱 prompt：

Create a C4 diagram for our platform.

更强的 prompt：

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

更强版本之所以效果更好，是因为它明确了受众、范围、边界、角色、内部容器和外部依赖。

用实用工作流，不要指望一次性全做完

很多人是否决定采用 c4-architecture install，最终取决于它的工作流是否贴近真实文档工作。实际操作里，更推荐这样做：

1. 先要一个 context diagram
2. 审核是否遗漏了角色和外部系统
3. 再生成 container diagram
4. 只有在读者确实需要时，才补 component 或 deployment 视图
5. 把图保存到 Markdown，并配上简短说明文字

这种分阶段方式，比一次要求五种图更可靠，因为第 1、2 层出错后，后面所有更低层级的图都会跟着错。

在 Technical Writing 中如何更好地使用它

c4-architecture for Technical Writing 很适合这样的场景：写作者需要的是可读、可维护、并能和代码一起版本化的架构文档。这个 skill 的价值在于，它生成的图可以直接嵌入 Markdown，并配合简短说明文字使用。

做技术写作任务时，建议额外说明：

• 目标读者层级：高管、混合技术读者、开发者、ops
• glossary 术语或批准使用的产品名称
• 服务和团队的首选命名方式
• 文档存放位置，例如 /docs/architecture/
• 是否需要说明每张图“为什么存在”

这样能避免一个常见问题：图在技术上说得通，但和文档语气或信息架构不一致。

最影响输出质量的建模规则

仓库里的 mistake guide 总结了几条非常关键的规则：

• container 是可部署 / 运行时单元，不是类
• component 是 container 内部的组成部分
• 不要自己发明非官方的 C4 层级
• 同一张图里要保持抽象层级一致
• 只加入能支持读者判断的信息细节

如果你只记住一件事，那就是：大多数糟糕的 C4 图，问题不在语法，而在于层级混用。

Mermaid 输出失败时，优先看参考文档

如果生成出来的图无法渲染，或者结构看起来不对，优先检查：

• references/c4-syntax.md：确认 C4 Mermaid 声明和元素是否合法
• 先检查 relationship syntax 和 boundary syntax
• 是否用了正确的图类型，比如 C4Container 而不是 C4Component

这个 skill 比普通 prompt 更好用的一个原因，就是它在语法出错时给了你清晰的修复路径。

什么时候需要看 advanced patterns

当你的架构包含以下情况时，打开 references/advanced-patterns.md：

• 存在多个服务边界的微服务
• API gateway
• 事件驱动或基于队列的工作流
• 不止一个 ownership boundary
• 需要真实节点和环境信息的基础设施或部署视图

当“一个系统、一个应用、一个数据库”这种简单心智模型会误导文档时，这个文件尤其有价值。

c4-architecture skill 常见问题

c4-architecture 适合新手吗？

适合，尤其是在你能用自然语言把系统讲清楚的情况下。这个 skill 的工作流和 mistake guide 可以显著减少常见的 C4 错误。新手建议只从 Context 和 Container 开始，在系统边界稳定之前先不要做 Component 图。

什么时候不该用 c4-architecture？

如果你只需要一张快速的非正式草图、一个像素级精细的设计稿，或者一套偏 UML 的内部设计模型，那就没必要用 c4-architecture。它最擅长的是可维护的 Mermaid 架构文档，而不是穷尽实现细节的设计建模。

它比直接让 AI 生成 Mermaid 图更好吗？

通常来说，对于架构文档，是更好的。泛用 prompt 也能输出 Mermaid，但 c4-architecture 提供了更强的结构约束：层级选择、建模纪律、语法参考，以及已知反模式。这让它更适合那些要被别人阅读和长期维护的文档。

c4-architecture 既适用于单体，也适用于微服务吗？

适用。对于单体，它能帮助你区分 context、container 和有限度的 component 视图。对于微服务，advanced patterns 参考文件则很适合用来判断：某些服务应该作为 container 展示，还是应该上升为更大的 system boundary。

我必须拿到完整代码库才能用吗？

不需要，但源材料越完整，效果越好。这个 skill 可以基于架构笔记、repo 结构、服务清单、API 文档、部署清单，或利益相关方的描述来工作。如果你的输入不完整，建议要求它把假设明确标出来。

可以用 c4-architecture 生成部署图和运行时视图吗？

可以。这个 skill 支持 C4Deployment，也支持动态流程图。但只有当运行时拓扑或请求流对读者真的重要时，才值得加；否则它们只会增加噪音。

如何改进 c4-architecture skill 的使用效果

先给事实，不要先让它推断结构

想提升 c4-architecture 输出质量，最快的方法是在要求生成图之前，先提供一份事实清单：

• 用户
• system boundary
• 可部署单元
• 数据存储
• 外部依赖
• 协议
• 环境或 hosting model

这样能减少“看起来很自信但其实错了”的关系推断。

要求它显式列出假设

一个很有价值的 prompt 补充是：

If any element is uncertain, list assumptions before generating the final Mermaid.

当你在为接手来的旧系统补文档，或只能基于零散笔记使用这个 skill 时，这一点尤其有帮助。

在继续深入之前，先审好 context 和 container 输出

在 context 和 container 层没理顺之前，不要接受 component diagram。因为如果 container model 本身就错了，component 细节只会让文档“看起来更专业”，却依然不准确。

对抽象层级错误要及时纠正

如果输出把类、包或 endpoint 当成 container，先停下来修这个问题。common-mistakes.md 里的指导非常关键，因为一旦抽象层级错了，整份文档都会变得不可信。

一个实用的修正 prompt 是：

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

每次正式请求都明确写出受众

受众不同，“好结果”的标准也不同：

• 高管需要 context、结果导向和外部依赖
• 工程师需要 containers、协议和职责边界
• 开发者可能需要某一个 container 内部的 component 细节
• ops 团队需要部署节点和环境信息

如果不写明受众，即使语法完全正确，这个 skill 仍可能给出错误层级的细节。

给每张图配上简短说明文字

如果你要求它在每张图下面额外给出 2–5 条 bullet，说明以下内容，这个 skill 会更实用：

• 这张图展示了什么
• 为什么选择这个层级
• 关键交互有哪些
• 有哪些内容是刻意不展示的

这个小改动会让输出在文档和 review 讨论串里都更容易使用。

通过定向修改迭代，不要整段重写

第一版出来之后，提升质量的更好方式是给出聚焦的修正，例如：

• 补上遗漏的外部系统
• 把 containers 重命名为符合产品术语的名称
• 把一个过于臃肿的服务拆成两个 containers
• 在关系上标注协议
• 从 container 视图中移除 component 细节
• 只为 production 生成 deployment view

这种定向迭代能保留已有的好结构，比一句“再试一次”更快收敛。

把 c4-architecture 当成文档系统来用，而不只是生成器

c4-architecture skill 最有长期价值的用法，是把它作为 repo 中架构文档的标准化方式。把 Mermaid 图放在代码或文档旁边，在 pull request 中审阅它们，并在服务或边界变化时同步更新。也正是在这里，这个 skill 比临时性的 ad hoc prompting 更有优势：它支持可重复、Markdown-native 的架构文档工作流。