用途
c4-architecture 用于生成软件架构文档，采用 C4 模型并以 Mermaid 语法绘制架构图。当需要创建架构图、记录系统架构或可视化系统结构时使用。
主要能力
该技能支持 C4 模型的多个抽象层级：
- Level 1 C4Context：面向所有人，展示系统与外部参与者，始终需要创建。
- Level 2 C4Container：面向技术人员，展示应用、数据库、服务，始终需要创建。
- Level 3 C4Component：面向开发者，展示内部组件，仅在确有价值时创建。
- Level 4 C4Deployment：面向 DevOps，展示基础设施节点，用于生产系统。
- C4Dynamic：面向技术人员，展示带编号的请求流程，用于复杂工作流。
关键提示：上下文图与容器图对大多数软件开发团队已经足够，仅在组件/代码图确实增加价值时才创建。
使用方式
工作流程包括：
- 理解范围——根据受众确定需要哪些 C4 层级。
- 分析代码库——探索系统以识别组件、容器和关系。
- 生成图表——在适当的抽象层级创建 Mermaid C4 图。
- 编写文档——将图表写入 markdown 文件并附上解释性上下文。
输出位置：将架构文档写入 docs/architecture/ 目录，命名约定为：
- c4-context.md——系统上下文图
- c4-containers.md——容器图
- c4-components-{feature}.md——按功能划分的组件图
- c4-deployment.md——部署图
- c4-dynamic-{flow}.md——特定流程的动态图
适用场景
根据受众选择合适细节：
- 高管：仅系统上下文图
- 产品经理：上下文 + 容器图
- 架构师：上下文 + 容器 + 关键组件图
- 开发者：按需所有层级
- DevOps：容器 + 部署图
限制与注意事项
最佳实践中的关键规则：
- 每个元素必须有名称、类型、技术（如适用）和描述。
- 仅使用单向箭头，双向箭头会产生歧义。
- 用动作动词标注箭头，如“Sends email using”“Reads from”，而非仅“uses”。
- 包含技术标签，如“JSON/HTTPS”“JDBC”“gRPC”。
- 每张图保持在 20 个元素以内，复杂系统拆分为多张图。
清晰度指南：
- 从 Level 1 开始，上下文图有助于框定系统范围。
- 每个文件一张图，保持图表聚焦于单一抽象层级。
- 使用有意义的别名，如 orderService 而非 s1。
- 描述尽量简洁，控制在 50 个字符以内。
- 始终包含标题，如“System Context diagram for [System Name]”。
应避免的做法（详见 references/common-mistakes.md）：
- 混淆容器（可部署）与组件（不可部署）。
- 将共享库建模为容器。
- 将消息代理显示为单个容器而非各个主题。
- 添加未定义的抽象层级如“子组件”。
- 为“简化”图表而移除类型标签。
微服务指南：
- 单一团队拥有时，将每个微服务建模为容器（或容器组）。
- 多团队拥有时，将微服务提升为软件系统。
- 事件驱动架构中，将各个主题/队列显示为容器，而非单个“Kafka”框。
参考资料
- references/c4-syntax.md——完整的 Mermaid C4 语法
- references/common-mistakes.md——应避免的反模式
- references/advanced-patterns.md——微服务、事件驱动、部署