Community图像github.com

c4-diagrams

在创建、审查、更新或解释使用C4模型(系统上下文L1、容器L2、组件L3、代码L4、系统景观图、动态图或部署图)的软件架构图时触发,尤其适用于Markdown/Mermaid。

c4-diagrams 是什么?

该技能为Claude Code提供了一套全面的规则和模板,用于在Markdown中使用Mermaid绘制C4模型图。它基于C4模型官方文档,确保所有生成的图表都遵循结构化的抽象层次:人员、软件系统、容器、组件和代码。该技能解决了常见图表缺陷,如没有图例、混合抽象层次、未标记的箭头以及缺少技术细节。它支持多种图表类型,包括系统上下文图、容器图、组件图、系统景观图、动态图和部署图,并提供了Mermaid flowcharts的标准模板。此外,它还涵盖了队列/主题建模和微服务映射等特殊模式,清晰说明了如何在不同团队所有权下对微服务进行建模。该技能要求严格保持抽象纯度,在系统上下文图中不暴露协议,在组件图中不泄露部署细节。简洁是核心原则——混乱的图表应通过按业务领域或边界进行拆分来解决,而不是塞入大量元素。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

C4 图

来源:官方C4模型:https://c4model.com/。每当你绘制、审查或解释C4图时,请应用这些规则。当输出包含散文(ADR、文档、PR描述)时,同时加载`writing`技能。

1. 目的

C4是一组“代码地图”,有四个缩放级别:上下文、容器、组件和代码。Simon Brown受UML和4+1视图模型启发创建了它,旨在取代随意绘制的方框和线条图。它修复的典型问题:没有图例、抽象层次混杂、未标注的箭头、缺少技术细节、以及诸如“业务逻辑”之类的模糊标签。

C4独立于符号和工具。下面的抽象层次和规则才是重要的,形状并不重要。

2. 抽象层次

层次结构:人员 -> 软件系统 -> 容器 -> 组件 -> 代码。每个级别都放大上一级别的某个元素。

抽象层次定义示例
人员系统的人类用户、参与者、角色或用户画像客户、客服、管理员
软件系统最高级别的抽象;为用户提供价值。通常由一个团队拥有和构建。它不是产品域、限界上下文、部落或小队票务平台、支付系统
容器软件系统内可独立运行/部署的应用程序或数据存储服务器端Web应用、SPA、桌面应用、移动应用、无服务器函数、批处理/控制台应用、微服务API、数据库模式、S3/Blob存储、CDN、文件系统、Shell脚本
组件容器内部通过定义良好的接口组织在一起的相关功能集合。不可单独部署:容器的所有组件共享一个进程空间OrderController、PaymentService、EmailSender
代码组件内部的类、接口、函数或数据库表class OrderValidator、orders表

容器规则(C4常见问题解答)

  • C4中的容器不是Docker容器。 它是指可运行/可部署的应用程序或数据存储,无论其打包方式如何。
  • 一个服务器端渲染的HTML应用是1个容器。一个服务器加上一个SPA或移动客户端是2个通过远程API通信的容器。
  • JAR、DLL、程序集和模块不是容器。它们用于组织容器内的代码。
  • 当你拥有或控制存储桶或模式时,受管数据服务(S3、RDS、CDN)是系统边界内的容器。它们不是外部系统。

组件规则

  • 组件不是文件夹、包或JAR。它是一个具有接口的功能分组。
  • 组件不可独立部署。如果可以单独部署,那它就是容器。

术语适配

团队可以在图中或文档中明确定义后,使用语言惯用的名称(例如函数式代码中的Module或Function)。除非每个级别都有严格定义,否则不要发明额外的抽象级别。

3. 特殊建模模式

队列和主题

  • 错误做法: 在中部放置一个巨大的“消息总线”容器,连接所有服务(星型拓扑)。这掩盖了谁生产和谁消费。
  • 选项1(推荐): 将每个队列或主题建模为独立的容器(消息数据存储)。生产者写入,消费者读取或订阅。
  • 选项2: 对于直接的端到端耦合,省略队列框,并将关系标记为"Publishes order events via Queue orders [AMQP]"。可选择将这些线条与HTTP调用的样式不同(在图例中说明)。

例如:Order API --"将OrderPlaced发布到[Kafka]"--> [(orders topic)] --"从[Kafka]读取OrderPlaced"--> Fulfilment Worker。

微服务(康威定律规则)

  • 一个团队拥有整个软件系统: 将每个微服务建模为该系统边界内的一组容器(API容器及其自身数据库模式容器,或单个无状态Lambda容器)。
  • 独立团队拥有各自的服务: 将每个独立拥有的服务提升为独立的软件系统,每个系统都有各自的系统上下文图和容器图。在跨系统边界时明确说明队列/主题的所有权。

4. 图目录

核心静态级别

级别图推荐范围受众显示/省略
1系统上下文是1个软件系统技术人员与非技术人员系统周围的人员和外部系统。省略低级技术和协议。
2容器是1个软件系统技术人员、运维人员主要技术选择和进程间协议。省略集群、负载均衡器、故障转移。
3组件否:只有在能明确增加价值且最好自动生成时才使用1个容器架构师、开发人员一个容器内部的组件及其交互。
4代码否:按需在IDE中生成1个组件开发人员UML类图或ER图。

补充图

图推荐用途
系统景观图是,用于组织和项目组合所有系统和人员的企业或部门地图。一个没有单一焦点系统的上下文图。
动态图否:谨慎使用复杂的运行时协作。使用编号协作风格或UML序列风格。
部署图是1个环境(生产、预发布、开发)。嵌套的部署节点(物理、VM、Docker、Kubernetes、运行时)包含系统/容器实例,以及基础设施节点(DNS、负载均衡器、防火墙)。

兼容性

  • arc42: 上下文与范围 -> L1;构建块级别1 -> L2;构建块级别2 -> L3;构建块级别3 -> L4。
  • UML: 使用UML状态图、序列图和ER图来补充C4,用于工作流、状态机和数据模型。

缩放规则

当图表变得杂乱时,不要在一个画布上塞满几十个框。在相同的抽象级别上按业务领域、限界上下文、功能或单一服务焦点(焦点服务及其入站和出站邻居)进行拆分。

5. 符号规则

图

  • 标题指明图表类型和范围:Checkout System的容器图。
  • 始终包含解释形状、颜色、边框、线条类型、箭头和缩写的图例/说明。
  • 保持严格的抽象纯度:永远不要混合抽象级别(例如,在L2容器图中不要出现Component框),永远不要在L1系统上下文图中放置协议或内部实现步骤([HTTPS]、masked packet、tool_runner)。
  • 在比较竞争或历史架构时,明确标注边界标题(选项A(已淘汰) vs. 选项B(当前)),并在需求或假设发生变化时更新文档中的所有图表。

元素

  • 名称、明确的元素类型(Person、Software System、Container、Component、Database、Deployment Node)以及简洁的职责描述。
  • 每个容器、组件和部署节点上都要明确标注技术。

关系

  • 仅使用单向箭头。 绝不用<-->。如果数据双向流动,显示发起方的方向,并在标签中描述响应。
  • 使用具体的主动动词标签。从不使用赤裸裸的“使用”。写为向...提交订单、从...读取座位图。
  • 在容器到容器关系上标注协议/技术:[JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。

6. Markdown中的Mermaid

默认使用flowchart(flowchart TB或LR),而不是Mermaid原生C4Context/C4Container。原生的C4语法是实验性的,通常在Markdown查看器中渲染失败。仅在用户明确要求并确认渲染器支持时才使用它。

Flowchart约定:

  • 使用subgraph表示系统边界(容器/组件)或部署节点。
  • 使用[(...)]表示数据库、数据存储、队列和主题。
  • 带引号的HTML标签:"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility"。
  • 带引号标签的箭头:A -->|"Action [Protocol]"| B。
  • 每种元素类型一个classDef,并一致应用。
  • 一个紧凑的Legend子图(未连接的节点,使用不可见的bottomNode ~~~ Legend链接锚定在底部,当Dagre将其放在顶部时)在使用颜色、圆柱形状或多线条样式时是必需的;将标题作为标题或Title: ...行直接放在代码块上方。
  • 动态图:sequenceDiagram,或使用带有编号箭头标签(1. Submits order [JSON/HTTPS])的flowchart。
  • 部署图:flowchart中的嵌套subgraph。
  • 始终引用包含括号、方括号或冒号的标签。
  • 绝对不要在sequenceDiagram或stateDiagram-v2标签中放置未转义的分号(;)(Mermaid将;视为语句终止符,并将剩余文本拆分为虚假状态或解析错误);使用<br/>包裹sequenceDiagram中的长Note块,以免文本在视口边缘被裁剪。

模板:L1 系统上下文

标题:票务平台的系统上下文图

flowchart TB
    customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
    ticketing["<b>Ticketing Platform</b><br/>«Software System»<br/>Lets customers browse events and buy tickets"]
    payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
    email["<b>Email Service</b><br/>«Software System, external»<br/>Delivers confirmation emails"]

    customer -->|"Browses events and buys tickets using"| ticketing
    ticketing -->|"Requests card charges from"| payments
    ticketing -->|"Sends confirmation emails using"| email
    email -->|"Delivers confirmation emails to"| customer

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class ticketing system
    class payments,email external

    subgraph Legend
        direction LR
        l1["Person"]:::person
        l2["Software System (in scope)"]:::system
        l3["Software System (external)"]:::external
    end

模板:L2 容器(带队列容器)

标题:票务平台的容器图

flowchart TB
    customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
    payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]

    subgraph boundary["Ticketing Platform [Software System]"]
        spa["<b>Web App</b><br/>«Container: React SPA»<br/>Event browsing and checkout UI"]
        api["<b>Order API</b><br/>«Container: Java, Spring Boot»<br/>Validates and places orders"]
        db[("<b>Orders DB</b><br/>«Container: PostgreSQL»<br/>Stores orders and tickets")]
        topic[("<b>orders topic</b><br/>«Container: Kafka topic»<br/>OrderPlaced events")]
        worker["<b>Fulfilment Worker</b><br/>«Container: Python»<br/>Issues tickets and sends emails"]
    end

    customer -->|"Browses and buys using [HTTPS]"| spa
    spa -->|"Submits orders to [JSON/HTTPS]"| api
    api -->|"Writes orders to [SQL/TCP]"| db
    api -->|"Publishes OrderPlaced to [Kafka]"| topic
    worker -->|"Reads OrderPlaced from [Kafka]"| topic
    worker -->|"Updates ticket status in [SQL/TCP]"| db
    api -->|"Requests card charges from [JSON/HTTPS]"| payments

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class spa,api,worker container
    class db,topic store
    class payments external

    subgraph Legend
        direction LR
        l1["Person"]:::person
        l2["Container"]:::container
        l3[("Data store / queue / topic")]:::store
        l4["External system"]:::external
    end

图例说明:箭头从发起方指向目标。标签说明操作和[协议]。

模板:部署图

标题:票务平台的部署图(生产环境)

flowchart TB
    users["<b>Customer browser</b><br/>«Deployment Node: Chrome»"]

    subgraph aws["AWS «Deployment Node: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Infrastructure Node: DNS»"]
        lb["<b>Load Balancer</b><br/>«Infrastructure Node: ALB»"]
        subgraph eks["EKS «Deployment Node: Kubernetes cluster»"]
            subgraph pod["order-api pod «Deployment Node: Docker, x3»"]
                api["<b>Order API</b><br/>«Container instance: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Deployment Node: PostgreSQL 16»"]
            db[("<b>Orders DB</b><br/>«Container instance: PostgreSQL schema»")]
        end
    end

    users -->|"Resolves hostname using [DNS]"| dns
    users -->|"Sends requests to [HTTPS]"| lb
    lb -->|"Forwards requests to [HTTP]"| api
    api -->|"Reads and writes orders in [SQL/TCP]"| db

如果使用默认样式以外的颜色或样式,请添加图例子图。

模板:动态图(序列图)

标题:票务平台订单结账的动态图(序列样式)

sequenceDiagram
    autonumber
    actor customer as Customer
    participant spa as Web App (React SPA)
    participant api as Order API (Spring Boot)
    participant payments as Payment Provider
    participant db as Orders DB (PostgreSQL)
    participant topic as orders topic (Kafka)

    customer->>spa: Clicks "Place Order"
    spa->>api: POST /orders [JSON/HTTPS]
    api->>payments: Charges card [JSON/HTTPS]
    payments-->>api: Payment authorized
    api->>db: Inserts order row [SQL/TCP]
    api->>topic: Publishes OrderPlaced [Kafka]
    api-->>spa: 201 Created (order confirmation)
    spa-->>customer: Shows order receipt

保持sequenceDiagram参与者和消息标签中不含未转义的斜杠、分号(;,Mermaid将其解析为语句终止符)或原始换行符,以获得最佳的Markdown查看器兼容性。

7. Diagr

…

[翻译截断]

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能