c4-architecture

c4-architecture 技能總覽

c4-architecture skill 可協助你把軟體架構文件整理成 Mermaid C4 圖，不只是單純畫幾個方塊。它特別適合工程師、技術寫作者、資深架構師，以及需要依受眾層級清楚說明系統的團隊：給廣泛讀者看 Context、給技術利害關係人看 Container、給開發者看 Component、給維運人員看部署視圖。

c4-architecture 主要適合做什麼

當真正的工作是把程式碼庫、服務版圖，或一份還很粗略的系統描述，整理成有結構的架構文件時，就很適合使用 c4-architecture。如果你需要的是能放進 Markdown、納入版本控制，而不是一次性白板匯出的圖，這個 skill 尤其實用。

最適合的使用情境

這個 c4-architecture skill 很適合用在：

• 為既有 repo 製作 onboarding 架構文件
• 為 ADR 或技術文件建立 system context 與 container 視圖
• 說明 microservices、事件驅動系統，以及外部相依
• 為文件網站、wiki 或 pull request 產出架構圖
• 在 Technical Writing 工作流程中建立架構內容

它和一般畫圖 prompt 有什麼不同

一般 prompt 也能產出「看起來像圖」的回答，但這個 skill 提供了更清楚的工作流程與更好的預設做法：

• 以 C4 model 為核心，讓抽象層級更一致
• 把 Context 和 Container 視為基線，而不是可有可無的附加項
• 提供 Mermaid C4 diagram 的語法指引
• 在你發布容易誤導人的文件之前，先提醒常見建模錯誤
• 涵蓋 microservices 與較複雜系統的進階模式

使用者通常最先在意的事

在安裝或呼叫 c4-architecture 之前，多數人最想先確認的是：

• 如果我對系統只了解一部分，它有幫助嗎？有，只要你能提供角色、主要服務、資料儲存、外部系統等基本資訊。
• 它適合以 Markdown 為主的文件流程嗎？適合，Mermaid 輸出就是它的核心價值。
• 對沒有深厚架構背景的技術寫作者有用嗎？有，因為這個 skill 對層級切分與常見錯誤有明確主張。
• 它能取代深入的架構審查嗎？不能。它能加快初稿與結構化文件產出，但系統是否準確仍取決於你的輸入。

如何使用 c4-architecture skill

在你的 skills 環境中安裝 c4-architecture

如果你的 agent 支援此 repo 所使用的 skills CLI 模式，請用以下指令安裝：

npx skills add softaworks/agent-toolkit --skill c4-architecture

如果你的環境是從 clone 下來的 repository 載入 skills，則使用以下路徑中的 skill：

skills/c4-architecture

第一次使用前，先讀這些檔案

如果你想快速掌握重點、得到高訊號的 c4-architecture guide，建議依這個順序閱讀：

1. skills/c4-architecture/SKILL.md
2. skills/c4-architecture/references/common-mistakes.md
3. skills/c4-architecture/references/c4-syntax.md
4. skills/c4-architecture/references/advanced-patterns.md
5. skills/c4-architecture/README.md

這個順序有效的原因是：

• SKILL.md 先交代預期工作流程
• common-mistakes.md 可先幫你避開最常見的建模錯誤
• c4-syntax.md 能讓你更快排查 Mermaid 輸出問題
• advanced-patterns.md 在你的系統不是單純 monolith 時特別重要

在下 prompt 前，先選對 C4 層級

c4-architecture usage 最大的品質槓桿，就是先依受眾選對層級：

• C4Context：一律從這裡開始；顯示使用者與外部系統
• C4Container：通常是必要的；顯示 app、database、queue 與 service
• C4Component：只有在內部結構真的能幫助讀者時再加
• C4Deployment：用於執行環境／基礎設施層面的關注點
• C4Dynamic：用於重要的 request 或 event flow

最常見的失敗模式，是一開始就直接跳到 component，結果在讀者還沒理解系統邊界前，圖就先變得雜亂。

給這個 skill 它真正需要的最少輸入

你不需要有完美的架構筆記，但至少要有足夠結構，才能避免產出憑空想像的 topology。好的輸入包括：

• 系統名稱與用途
• 主要使用者或外部角色
• 重要服務／app／datastore
• 外部系統或 vendor
• 關鍵關係與通訊協定
• 目標受眾
• 想要的 diagram 層級
• 輸出檔案或文件位置

如果你只說「幫我的 app 畫一張 C4 diagram」，就要預期輸出會偏泛泛。

把模糊需求改寫成有力的 c4-architecture prompt

較弱的 prompt：

Create a C4 diagram for our platform.

較強的 prompt：

Use the c4-architecture skill to document our B2B analytics platform. Audience: engineering and product. Create C4Context and C4Container diagrams in Mermaid plus brief Markdown explanations. System boundary: Analytics Platform. Actors: Customer Admin, Analyst. External systems: Okta, Stripe, Snowflake, SendGrid. Internal containers: React web app, API gateway, Python ingestion service, dbt transform jobs, PostgreSQL app DB, Redis cache. Show key relationships and protocols. Avoid component-level detail unless necessary.

後者之所以更好，是因為它明確交代了受眾、範圍、邊界、角色、內部 container 與外部相依。

用實際可行的工作流程，不要只想一次問完

很多人評估 c4-architecture install 值不值得，關鍵其實在於它的工作流程是否貼近真實文件工作。實務上建議這樣做：

1. 先要求產出 context diagram
2. 檢查是否漏掉角色與外部系統
3. 再產生 container diagram
4. 只有在讀者真的需要時，才補 component 或 deployment 視圖
5. 把圖存進 Markdown，搭配簡短說明文字

這種分階段做法，比一次要求五種 diagram 更可靠，因為第 1、2 層出錯，後面所有更細的圖都會一起被拖累。

在 Technical Writing 中好好用它

c4-architecture for Technical Writing 很適合需要可讀、可維護、且能隨程式碼一起版本化的架構文件。這個 skill 的價值，在於能產出可直接嵌入 Markdown、並搭配短說明文字的圖。

做技術寫作任務時，建議一併提供：

• 目標讀者層級：executive、mixed technical、developer、ops
• glossary 用語或已核准的產品名稱
• 服務與團隊的偏好術語
• 文件位置，例如 /docs/architecture/
• 是否需要說明每張 diagram 為何存在

這能避免常見問題：圖在技術上看似合理，卻和文件語氣或資訊架構不一致。

先掌握最影響輸出品質的建模規則

這個 repository 的 mistake guide 特別整理出幾條影響很大的規則：

• container 是可部署／執行時的單位，不是 class
• component 是 container 內部的組成部分
• 不要自行發明非官方的 C4 層級
• 同一張圖內要維持抽象層級一致
• 只加入能支持讀者做判斷的細節

如果你只記得一件事，就記住這句：大多數糟糕的 C4 圖，問題不在語法，而在混用了不同層級。

Mermaid 輸出失敗時，該怎麼用參考文件排查

當產出的圖無法 render，或結構看起來明顯不對時，請優先檢查：

• references/c4-syntax.md：確認合法的 C4 Mermaid 宣告與元素
• 先看 relationship syntax 與 boundary syntax
• 檢查你是否用了正確的 diagram type，例如 C4Container 而不是 C4Component

這個 skill 之所以比一般 prompt 更好用，其中一個原因就是語法參考文件提供了明確的修復路徑。

什麼時候需要看進階模式

當你的架構包含以下情況時，請打開 references/advanced-patterns.md：

• 有多個 service boundary 的 microservices
• API gateway
• 事件驅動或以 queue 為核心的工作流程
• 不只一個 ownership boundary
• 需要真實節點與環境的 infrastructure 或 deployment 視圖

當「一個 system、一個 app、一個 database」這種簡化心智模型會導致文件失真時，這份檔案特別有用。

c4-architecture skill 常見問題

c4-architecture 適合初學者嗎？

適合，尤其是你能用白話描述系統時。這個 skill 的工作流程與 mistake guide 能減少常見的 C4 錯誤。初學者建議先只做 Context 與 Container，在系統邊界還沒穩定之前，先不要急著畫 Component diagram。

什麼情況下不該用 c4-architecture？

如果你只需要快速、非正式的草圖、像素級精緻的設計稿，或偏重 UML 的內部設計模型，就不必用 c4-architecture。它最強的是可維護的 Mermaid 架構文件，而不是鉅細靡遺的實作設計。

這比直接叫 AI 畫 Mermaid diagram 更好嗎？

通常是，尤其在架構文件場景。一般 prompt 也能輸出 Mermaid，但 c4-architecture 提供了更完整的結構：層級選擇、建模紀律、語法參考，以及已知 anti-pattern。對需要讓別人閱讀、維護的文件來說，可靠度更高。

c4-architecture 同時適用 monolith 與 microservices 嗎？

適用。對 monolith 來說，它有助於把 context、container 與選擇性的 component 視圖切開。對 microservices 來說，advanced patterns 參考文件能幫你判斷哪些 service 應該畫成 container，哪些則該提升為更大的 system boundary。

我需要能存取完整 codebase 嗎？

不需要，但來源資料越完整，結果通常越好。這個 skill 可以根據架構筆記、repo 結構、service 清單、API 文件、deployment manifest，或利害關係人的描述來工作。如果你的輸入不完整，請要求它明確標示假設。

我可以用 c4-architecture 畫 deployment 與 runtime 視圖嗎？

可以。這個 skill 支援 C4Deployment，也支援 dynamic flow diagram。不過只有在執行拓樸或 request flow 對讀者真的重要時才建議使用，否則容易增加雜訊。

如何改進 c4-architecture skill 的使用效果

先提供事實，再要求推論結構

想提升 c4-architecture 輸出品質，最快的方法，是在要求畫圖前先給一份事實清單：

• 使用者
• 系統邊界
• 可部署單位
• 資料儲存
• 外部相依
• 通訊協定
• 環境或 hosting model

這能降低模型很有自信、但關係畫錯的情況。

要求它明確列出假設

一個高價值的 prompt 補充句是：

If any element is uncertain, list assumptions before generating the final Mermaid.

當你是在接手既有系統，或只拿到零散筆記來做文件時，這點尤其有幫助。

在往下細化前，先檢查 context 與 container 輸出

在 context 與 container 層沒有正確前，不要接受 component diagram。若 container model 本身就錯，component 細節只會讓文件看起來更完整，卻仍然不準確。

對抽象層級錯誤要果斷修正

如果輸出把 class、package 或 endpoint 畫成 container，先停下來修這件事。common-mistakes.md 的指引很重要，因為一旦抽象層級錯了，整份文件都會變得不可信。

一個實用的修正 prompt 是：

Revise this as a true C4Container diagram. Only include deployable applications, services, data stores, and external systems. Move internal modules to a later component view.

每個正式需求都要指定受眾

受眾會直接改變「什麼叫做好」：

• executives 需要 context、結果與外部相依
• engineers 需要 containers、protocols 與責任邊界
• developers 可能需要某個 container 內的 component 細節
• ops 團隊需要 deployment node 與 environment

如果沒有交代受眾，即使語法正確，skill 也可能產出錯誤層級的內容。

每張圖都搭配簡短說明文字

如果你要求在每張圖下附上 2–5 個 bullet，說明以下內容，這個 skill 會更實用：

• 這張圖在表達什麼
• 為什麼選這個層級
• 關鍵互動有哪些
• 哪些內容是刻意不放進來的

這個小補充，會讓輸出在文件與 review thread 中好用很多。

用精準修訂迭代，不要整份重寫

第一輪產出後，提升品質的更好方式，是給出聚焦修正，例如：

• 補上缺漏的外部系統
• 依產品術語重新命名 containers
• 把一個過度塞滿的 service 拆成兩個 containers
• 在 relationships 上補 protocol
• 從 container 視圖移除 component 細節
• 只為 production 產生 deployment 視圖

這種針對性迭代能保留原本好的結構，也比一句「重試一次」更快收斂。

把 c4-architecture 當成文件系統，而不只是產生器

長期來看，c4-architecture skill 最好的用法，是把它拿來標準化 repo 裡的架構文件。把 Mermaid diagram 放在程式碼或文件附近，在 pull request 中審查，並在服務或邊界變動時同步更新。這正是它勝過臨時 ad hoc prompting 的地方：它支援可重複、以 Markdown 為原生格式的架構文件流程。