需要为软件系统生成 C4 架构图与架构文档时，用…

当需要创建架构图、记录系统架构、可视化软件结构或生成 C4 模型图（上下文、容器、组件、部署、动态）时使用。

适用场景

解决思路

1. 先明确范围：根据受众确定需要哪些 C4 层级。
2. 分析代码库：探索系统以识别组件、容器及其关系。
3. 生成图表：在合适的抽象层级上创建 Mermaid C4 图。
4. 编写文档：将图表写入 markdown 文件，并附上解释性上下文。
5. 按需选择层级：Level 1 C4Context（面向所有人，展示系统与外部参与者，始终创建）；Level 2 C4Container（面向技术人员，展示应用、数据库、服务，始终创建）；Level 3 C4Component（面向开发者，展示内部组件，仅在确有价值时创建）；Level 4 C4Deployment（面向 DevOps，展示基础设施节点，用于生产系统）；C4Dynamic（面向技术人员，展示带编号的请求流程，用于复杂工作流）。
6. 记住关键结论：Context + Container 图对大多数软件开发团队已经足够，只有在组件/代码图确实增加价值时才创建。
7. 使用元素语法：Person/Person_Ext、System/System_Ext/SystemDb/SystemQueue 表示人与系统；Container/Container_Ext/ContainerDb/ContainerQueue 表示容器；Component/Component_Ext/ComponentDb 表示组件；Enterprise_Boundary/System_Boundary/Container_Boundary/Boundary 表示边界；Rel/BiRel/Rel_U/Rel_D/Rel_L/Rel_R 表示关系；Deployment_Node/Node 表示部署节点。
8. 用 UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") 配置布局（$c4ShapeInRow 默认 4，$c4BoundaryInRow 默认 2）。
9. 用 UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red") 设置元素样式。
10. 用 UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10") 设置关系样式，并用 $offsetX/$offsetY 修复重叠的关系标签。
11. 遵循基本规则：每个元素必须有名称、类型、技术（适用时）和描述；只使用单向箭头（双向箭头会产生歧义）；箭头用动作动词标注（如 "Sends email using"、"Reads from"，而不是仅 "uses"）；包含技术标签（如 "JSON/HTTPS"、"JDBC"、"gRPC"）；每张图保持在 20 个元素以内，复杂系统拆分为多张图。
12. 遵循清晰度准则：从 Level 1 开始（上下文图有助于界定系统范围）；每个文件一张图，保持单一抽象层级；使用有意义的别名（如 orderService 而非 s1）；描述尽量控制在 50 个字符以内；始终包含标题（如 "System Context diagram for [System Name]"）。
13. 避免常见错误：混淆容器（可部署）与组件（不可部署）；把共享库建模为容器；把消息代理显示为单个容器而非各个主题；添加未定义的抽象层级（如 "subcomponents"）；为 "简化" 图表而移除类型标签。
14. 微服务单团队归属时：将每个微服务建模为容器（或容器组）。
15. 微服务多团队归属时：将微服务提升为软件系统（由不同团队拥有时）。
16. 事件驱动架构时：将各个主题/队列显示为容器，而不是单个 "Kafka" 盒子。
17. 输出位置：将架构文档写入 docs/architecture/，命名约定为 c4-context.md（系统上下文图）、c4-containers.md（容器图）、c4-components-{feature}.md（按功能划分的组件图）、c4-deployment.md（部署图）、c4-dynamic-{flow}.md（特定流程的动态图）。
18. 按受众调整细节：高管只看 System Context；产品经理看 Context + Container；架构师看 Context + Container + 关键 Components；开发者按需看所有层级；DevOps 看 Container + Deployment。

适用边界 · 注意事项

• 不要为 "简化" 图表而移除类型标签或添加未定义的抽象层级（如 subcomponents）。
• 不要把共享库建模为容器，也不要把消息代理显示为单个容器而非各个主题。
• 不要使用双向箭头，也不要在单张图中超过 20 个元素。