Community影像github.com

c4-diagrams

在建立、審查、更新或說明使用 C4 模型(系統脈絡 L1、容器 L2、元件 L3、程式碼 L4、系統全景、動態或部署圖)的軟體架構圖時觸發,特別是在 Markdown/Mermaid 中。

c4-diagrams 是什麼?

C4 圖表技能為 AI 代理在建立、審查或解釋軟體架構圖時提供了一套結構化規則,採用 C4 模型(系統脈絡、容器、元件、程式碼)。其核心目標是解決傳統方框及連線圖中的常見問題,例如缺少圖例、混合抽象層級、未標示的箭頭以及模糊的標籤。這項技能支援系統脈絡(L1)、容器(L2)、元件(L3)與程式碼(L4)圖表,另外也支援系統全景、動態與部署圖表。它明確界定了 Person(人物)、Software System(軟體系統)、Container(容器)和 Component(元件)等抽象層級,包含關於佇列、主題與微服務建模的詳細指引。此技能對於 Cursor、Claude Code 和 Codex 等代理平台至關重要,因為它強制要求一致、無歧義的圖表,以改善技術溝通。關鍵規則包括:使用單向箭頭、要求每條關係上都有具體的動作標籤與協定、在所有圖表中加入圖例,以及維護純粹的抽象層級(不混合在單一圖表中)。對於以 Markdown 為基礎的工具,此技能預設使用標準的 Mermaid flowchart 語法,並提供了系統脈絡、容器、部署與動態圖表的範本,以確保在不同渲染器中的相容性與正確的語法。

相容平台~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 是一組程式碼的四層縮放地圖:脈絡(Context)、容器(Containers)、元件(Components)、程式碼(Code)。由 Simon Brown 創建,靈感來自 UML 和 4+1 視圖模型,用以取代臨時的方框和連線圖。它能修正的典型問題包括:無圖例、混合抽象層級、未標示的箭頭、缺少技術堆疊,以及模糊的標籤(例如「商業邏輯」)。

C4 不受記號法及工具限制。重要的是以下抽象層級與規則,而非形狀。

2. 抽象層級

階層:人物(Person) -> 軟體系統(Software System) -> 容器(Container) -> 元件(Component) -> 程式碼(Code)。每一層級都是對上一層級中某個元素的放大。

抽象層級定義範例
人物 (Person)系統的人類使用者、參與者、角色或人物誌客戶、支援專員、管理員
軟體系統 (Software System)最高層級的抽象;為使用者提供價值。通常由單一團隊擁有和建置。它不是產品領域、限界上下文(bounded context)、部落(tribe)或小隊(squad)購票平台、支付系統
容器 (Container)軟體系統內部可獨立執行或部署的應用程式或資料儲存伺服器端網頁應用程式、SPA、桌面應用程式、行動應用程式、無伺服器函式、批次/主控台應用程式、微服務 API、資料庫綱要、S3/物件儲存、CDN、檔案系統、Shell 腳本
元件 (Component)容器內部,透過明確定義的介面所封裝的一組相關功能。不可單獨部署:一個容器內的所有元件共用同一個程序空間OrderController、PaymentService、EmailSender
程式碼 (Code)元件內部的類別、介面、函式或資料庫表格class OrderValidator、orders 表格

容器規則 (C4 FAQ)

  • C4 的容器不是 Docker。 它是一個可執行/可部署的應用程式或資料儲存,無論其封裝方式為何。
  • 伺服器端渲染的 HTML 應用程式是 1 個容器。伺服器加上 SPA 或行動用戶端是透過遠端 API 通訊的 2 個容器。
  • JAR、DLL、組件和模組不是容器。它們是容器內部組織程式碼的方式。
  • 當您擁有或控制儲存槽或綱要時,受管理的資料服務(S3、RDS、CDN)是您系統邊界內的容器。它們不是外部系統。

元件規則

  • 元件不是一個資料夾、套件或 JAR。它是一個帶有介面的功能分組。
  • 元件不可獨立部署。如果可以獨立部署,它就是一個容器。

調整術語

團隊可以使用與語言慣例相符的名稱(例如在函數式程式碼中使用「模組 (Module)」或「函式 (Function)」),但必須在圖表或其文件中明確定義該詞彙。除非每個額外的抽象層級都有嚴格的定義,否則不要發明新的層級。

3. 特殊建模模式

佇列 (Queues) 和主題 (Topics)

  • 錯誤方式: 在中間放一個巨大的「訊息匯流排 (Message Bus)」容器,所有服務都連接到它(中樞與輻射式)。這會隱藏誰產生以及誰消費了什麼訊息。
  • 選項 1(建議): 將每個佇列或主題建模為一個容器(一個訊息資料儲存)。生產者寫入,消費者讀取或訂閱。
  • 選項 2: 針對直接的點對點耦合,省略佇列方框,並將關係標記為 "Publishes order events via Queue orders [AMQP]"。可選擇性地使用與 HTTP 呼叫不同的線條樣式(請在圖例中說明)。

範例:Order API --"Publishes OrderPlaced to [Kafka]"--> [(orders topic)] --"Reads OrderPlaced from [Kafka]"--> Fulfilment Worker。

微服務 (Conway's Law 規則)

  • 單一團隊擁有整個軟體系統: 將每個微服務建模為該系統邊界內的一組容器(API 容器加上其自己的資料庫綱要容器,或一個單一的無狀態 Lambda 容器)。
  • 不同團隊擁有各自的服務: 將每個獨立擁有的服務提升為其自己的軟體系統 (Software System),每個系統都有自己的系統脈絡圖和容器圖。明確說明跨系統邊界的佇列/主題擁有權。

4. 圖表目錄

核心靜態層級

層級圖表建議範圍受眾顯示/省略
1系統脈絡 (System Context)是1 個軟體系統技術與非技術人員系統周圍的人物與外部系統。省略低階技術與協定
2容器 (Container)是1 個軟體系統技術與營運人員主要技術選擇與程序間協定。省略叢集、負載平衡器、容錯移轉
3元件 (Component)否:僅在能帶來明顯價值時使用(最好是自動化產生)1 個容器架構師、開發人員單一容器內的元件及其互動
4程式碼 (Code)否:在 IDE 中按需產生1 個元件開發人員UML 類別圖或 ER 圖

輔助圖表

圖表建議用途
系統全景 (System Landscape)是,適用於組織和投資組合企業或部門層級的地圖,顯示所有系統和人員。一張沒有單一焦點系統的脈絡圖
動態 (Dynamic)否:謹慎使用複雜的執行時期協作。可使用編號協作風格或 UML 順序圖風格
部署 (Deployment)是1 個環境(生產、暫存、開發)。巢狀部署節點(實體機、VM、Docker、Kubernetes、執行時期)包含系統/容器實例,以及基礎設施節點(DNS、負載平衡器、防火牆)

相容性

  • arc42: 脈絡與範圍 (Context & Scope) -> L1;建構區塊層級 1 (Building Block level 1) -> L2;建構區塊層級 2 (Building Block level 2) -> L3;建構區塊層級 3 (Building Block level 3) -> L4。
  • UML: 使用 UML 狀態圖、順序圖和 ER 圖來補充 C4,用於工作流程、狀態機和資料模型。

縮放規則

當圖表變得雜亂時,不要試圖將數十個方框塞進一個畫布中。應按業務領域、限界上下文、功能或單一服務焦點(焦點服務及其入站和出站鄰居),在相同的抽象層級上進行拆分。

5. 記號法規則

圖表

  • 標題需說明圖表類型和範圍:Container diagram for Checkout System。
  • 務必包含一個圖例 (key/legend) 來說明形狀、顏色、邊框、線條類型、箭頭和縮寫。
  • 保持嚴格的抽象層級純粹性:永遠不要混合抽象層級(例如,在 L2 容器圖中放入「元件」方框),並且永遠不要在 L1 系統脈絡圖中放入協定或內部實作步驟(例如 [HTTPS]、masked packet、tool_runner)。
  • 在比較競爭或歷史架構時,請明確標示邊界標題(例如 Option A (Superseded) 與 Option B (Current)),並在需求或假設變更時更新文件中的所有圖表。

元素

  • 名稱、明確的元素類型(Person、Software System、Container、Component、Database、Deployment Node),以及簡潔的職責描述。
  • 每個容器、元件和部署節點都需要明確的技術堆疊。

關係

  • 僅使用單向箭頭。 絕對不要用 <-->。如果資料是雙向流動的,請顯示發起者的方向,並在標籤中描述回應。
  • 使用具體主動動詞的標籤。永遠不要只寫「Uses (使用)」。請寫 Submits orders to、Reads seat map from。
  • 在容器對容器的關係上標註協定/技術:[JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。

6. Markdown 中的 Mermaid

預設使用 flowchart(flowchart TB 或 LR),而不是 Mermaid 原生的 C4Context/C4Container。原生的 C4 語法仍在實驗階段,經常無法在 Markdown 檢視器中正確渲染。僅在使用者明確要求並確認渲染器支援時才使用它。

流程圖慣例:

  • 使用 subgraph 作為系統邊界(容器/元件)或部署節點。
  • 使用 [(...)] 表示資料庫、資料儲存、佇列和主題。
  • 使用包含 HTML 的標籤:"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility"。
  • 使用包含標籤的箭頭:A -->|"Action [Protocol]"| B。
  • 每種元素類型使用一個 classDef,並一致地套用。
  • 當使用顏色、圓柱形狀或多種線條樣式時,需要一個緊湊的 Legend 子圖(未連接的節點,透過一個不可見的 bottomNode ~~~ Legend 連結固定在底部,以防 Dagre 將其放置在頂部);在程式碼區塊正上方放置一個標題或 Title: ... 行。
  • 動態圖表:使用 sequenceDiagram,或使用帶編號箭頭標籤的 flowchart(例如 1. Submits order [JSON/HTTPS])。
  • 部署圖:在 flowchart 中使用巢狀 subgraph。
  • 當標籤包含括號、方括號或冒號時,務必使用引號。
  • 絕對不要在 sequenceDiagram 或 stateDiagram-v2 的標籤中放入未跳脫的分號(;)(Mermaid 會將 ; 視為陳述式終止符,並將剩餘文字分割成錯誤的狀態或解析錯誤);在 sequenceDiagram 中,使用 <br/> 包裹較長的 Note 區塊,以防止文字在視口邊緣被裁剪。

範本:L1 系統脈絡圖

標題:System Context diagram for Ticketing Platform

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 容器圖(含佇列容器)

標題:Container diagram for Ticketing Platform

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

圖例說明:箭頭從發起者指向目標。標籤說明了動作和通訊協定 [protocol]。

範本:部署圖

標題:Deployment diagram for Ticketing Platform (Production)

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

如果您使用了預設以外的顏色或樣式,請加入一個 Legend 子圖。

範本:動態圖(序列圖)

標題:Dynamic diagram (sequence style) for Order Checkout in Ticketing Platform

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

為了確保與大多數 Markdown 檢視器的相容性,請保持 sequenceDiagram 的參與者和訊息標籤中不含未加引號的斜線、分號(;,Mermaid 會將其解析為陳述式終止符)或原始換行符。

7. Diagr

…

[已截斷以利翻譯]

Individual skills in this repo

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

相關技能