用途:按 C4 模型把软件架构画成一组不同缩放层级的地图,每张图只表达一个抽象层级,面向不同受众讲同一故事的不同部分。
主要能力:支持系统上下文、容器、组件、代码、部署、动态和系统全景图。多数系统只需上下文图加容器图;组件图仅在确有价值时添加,代码图几乎不用。容器指必须运行的应用或数据存储(Web 应用、SPA、移动应用、无服务器函数、数据库模式、S3 桶),不是 Docker 容器,也不是 JAR/DLL/模块/包;组件在同一进程内运行,按职责描述,而非每个源码文件夹一个框。
使用方式:先选入口模式——从代码推导或全新设计。从代码推导时坚持证据优先,每个元素可追溯到读到的内容,标注“观察到”与“推断”,不得虚构参与者、外部系统或组件。默认输出 Mermaid C4,可在 GitHub/GitLab/VS Code 内联渲染,零配置;多层级长期文档或已有 workspace.dsl 时用 Structurizr DSL 作为单一事实来源并导出渲染;备选 D2 和 C4-PlantUML。用 scripts/render.sh <file> 渲染并检查错误,直到干净通过;可用 scripts/example-workspace.dsl 做本地渲染器冒烟测试。每张图需有标题和图例,每个元素需有类型、技术和一行职责,箭头单向且具体标注,跨容器连线注明协议。
适用场景:记录现有仓库架构、设计新系统、需要向不同受众沟通静态结构时。
限制:C4 只表达静态结构,不处理业务流程、工作流、状态、数据模型等行为,这些应改用 BPMN、UML 状态图、时序图或 ER 图;领域建模、端口适配器、错误设计属于 architecture 技能;决策理由、ADR 和文档防腐属于 living-documentation 技能。未渲染的图不算完成。资料未提供具体收费、价格或平台支持细节。