c4-diagrams

C4 图

概述

使用 C4 图在详细设计前厘清软件架构。重点关注边界、职责、参与者、依赖关系和数据流；只绘制有实际价值的层级。

首要决策

开始绘图前，先确定以下选项。如果用户已指定某项，则遵照执行。如果有多个选项不明确，则用一个简洁的问题一并询问。

选项	可选项	默认行为
目的	现有代码、新系统、设计评审	对于现有代码，先探索代码库；对于新系统，明确列出假设。
格式	ASCII、Mermaid	询问用户。Mermaid 指普通 Mermaid 语法，而非 C4 专用 Mermaid 语法。
严谨程度	严格遵循 C4、轻量级 C4 风格、混合	询问用户。不要默默替用户决定。

如果用户要求跳过问题以节省时间，仍需将未解决的选项明确列为假设，并使第一张图保持轻量。

工作流

1. 确定目的、格式和严谨程度。
2. 对于现有代码，在绘图前检查入口点、运行时边界、集成和持久化。快速检查时，至少了解语言 / 框架、启动入口、主要目录、外部集成和数据存储；将其他未知信息标记为未知。
3. 选择最精简且有用的图集。先绘制系统上下文图或容器图；仅当组件图、动态视图或部署图能回答实际问题时再添加。
4. 使用 ASCII 或普通 Mermaid 绘制图表。
5. 用 3-6 个项目符号解释图表：边界、职责、关键关系、假设和待解问题。
6. 除非用户认可图表并要求继续，否则在详细设计前停止。

C4 层级选择

层级	适用情况	不适用情况
系统上下文	确认用户、外部系统和范围	范围已十分明确且仅涉及本地内容。
容器	展示可部署 / 可运行单元、数据存储、API、CLI、队列	只需了解代码级调用流程。
组件	说明一个容器的内部结构	容器内有实际意义的部分很少。
代码	少数情况下，用于关键类 / 模块	普通组件图已足够。
动态	展示请求、事件或工作流的顺序	问题实际关注的是静态结构。
部署	展示基础设施、节点、网络和运行时部署位置	部署信息未知或无关紧要。

对于小型系统，如果用户要求绘制全部四个 C4 层级，应提出异议并建议采用更精简的图集。如果用户仍要求绘制全部四个层级，则照做，但将价值较低的层级标记为轻量草图，并说明维护这些图可能没有必要。

输出规则

• Mermaid 图表必须使用普通 flowchart 或 sequenceDiagram 语法，以便移植。
• ASCII 图表应优先采用易读的方框和箭头，避免过度装饰。
• 标签应具体明确：参与者、系统、容器、组件、数据库、队列、外部服务。
• 不要意外混淆层级：容器是可运行 / 可部署单元；组件属于某个容器内部。
• 绘制未来系统或不完整代码库的图表时，始终列出假设。
• 边界、所有权、数据流或部署存在不确定性时，始终列出待解问题。

模板

使用此技能目录中的 templates.md，获取精简的 ASCII 和 Mermaid 起始模板。

常见错误

错误	修正方法
默认绘制全部四个 C4 层级	只绘制能回答当前问题的层级。
立即开始详细设计	先确认上下文 / 容器边界。
使用 C4 专用 Mermaid 语法	使用普通 Mermaid flowchart 或 sequenceDiagram。
将模块视为容器	容器是可运行 / 可部署单元；模块通常是组件。
隐藏不确定性	在图表后说明假设和待解问题。