LikeC4 C4 圖表
從口頭描述或程式碼庫產出符合 LikeC4 DSL 語法的有效 C4 圖表，並在交付前使用 CLI 驗證。參考文件按關注點拆分 — 只讀取任務需要的部分，在撰寫該部分之前讀取；不要猜測語法。
此處所有內容均針對 likec4 1.59.2 驗證（固定版本與升級程序請見 references/setup-and-validation.md）。
嚴格規則（只有兩條）
- 交付前務必驗證。 在專案上執行
likec4 validate，僅在 exit 0 時交付。完全沒有 CLI 可用 → 執行文件中說明的自我檢查並揭露此情況。程序：references/setup-and-validation.md。 - 絕不發明 DSL 語法。 如果不確定，開啟相關參考文件；若仍不確定，請查閱 https://likec4.dev/dsl/。
設定（第一件事，每次對話一次）
LC4="npx -y [email protected]"
v="$(likec4 --version 2>/dev/null | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' | tail -1)"
[ -n "$v" ] && [ "$(printf '%s\n1.53.0\n' "$v" | sort -V | head -1)" = "1.53.0" ] && LC4=likec4
只有在已安裝的 CLI 版本 >= 1.53.0 時才使用它 — 較舊版本沒有 format 指令，且 1.52.0 對無效模型也會回傳 exit 0，因此下方兩個門檻都會無聲通過。不需要全域安裝 — npx -y [email protected] 可在任何有 Node 22+ 和網路的環境中運作（首次執行下載，之後快取）。對於使用者想要保留的專案，建議執行 npm install --save-dev [email protected]。詳細資訊、版本下限、離線備援方案與錯誤目錄：references/setup-and-validation.md。
任務 → 應閱讀的內容
| 面前的任務 | 閱讀 |
|---|---|
| 系統上下文 / Landscape（「誰在使用它，它與誰通訊」） | references/levels/l1-context.md |
| 容器（「內部執行什麼」，技術選擇） | references/levels/l2-container.md |
| 元件（一個容器內部） | references/levels/l3-component.md |
| 程式碼層級 — 一個元件的類別/介面 | references/levels/l4-code.md |
| 資料流 / 情境 / 序列（登入、結帳、管道） | references/levels/flows-dynamic.md |
| 基礎設施 /「它在哪裡執行」 | references/levels/deployment.md |
| 任何跨領域的 DSL 問題（spec、model、FQN、extend、predicates） | references/syntax-core.md |
| 顏色、形狀、圖示、圖例、佈局 | references/styling.md |
| 給定儲存庫 / 原始碼 | references/code-to-diagram.md |
| 安裝、驗證、格式化、錯誤、預覽/匯出/CI | references/setup-and-validation.md |
根據任務擴展結構
- 小需求（一個系統，快速上下文/容器概覽）：從
templates/minimal/開始 — 3 個檔案（spec.c4、model.c4、views.c4）。不要為此建立多資料夾專案。 - 真實系統（2 個以上層級、多個系統、部署、流程）：使用
templates/full/佈局 — 複製檔案並重新命名內容：
architecture/
├── spec.c4 # 唯一的 specification 區塊：所有 kinds
├── model/
│ ├── landscape.c4 # 頂層系統 + 角色
│ ├── <system>.c4 # 每個系統一個檔案，透過 extend <system> { … }
│ └── externals.c4 # externalSystem 元素
├── deployment/prod.c4 # nodes + instanceOf（kinds 留在 spec.c4）
└── views/
├── context.c4 # 第 1 層（檢視索引）
├── <system>-views.c4 # 第 2/3 層檢視，含向下鑽研
└── dynamic-flows.c4 # 動態 + 部署檢視
透過新增檔案來擴充（新系統 → 新增 model/<s>.c4），保持 model 與 views 分離，並將 specification 集中在一個檔案中。該資料夾下的所有 .c4 檔案會自動合併為一個 model。
範本僅使用內建主題顏色（範圍內 = primary，外部 = 透過 externalSystem kind 的 gray，角色 = indigo）— 無自訂顏色，無標籤。這保持了 C4 慣例並能適應淺色/深色主題。
工作流程
- 界定範圍 — 識別系統、角色、外部元素；選擇層級。預設值：上下文 + 容器；只有對於非平凡的容器才使用元件；為每個關鍵情境建議一個動態檢視；當基礎設施重要時才使用部署；僅在明確要求或有充分理由時才使用第 4 層（
references/levels/l4-code.md— 預設替代方案是原始碼連結）。如果輸入是儲存庫 →references/code-to-diagram.md。如果範圍確實不明確 → 問一個問題；否則直接進行並說明假設。 - 設定 — 複製匹配的範本，執行上述的
LC4行。 - 先 Model，再 Views — 撰寫 model 檔案，然後撰寫含向下鑽研的 views（
view of、navigateTo），為你產出的每個圖表閱讀對應的層級檔案。 - 先驗證，再格式化 —
$LC4 validate <dir>；修正Line N:錯誤（目錄在setup-and-validation.md中），直到 exit 0。然後執行$LC4 format <dir>並重新驗證，確保檔案符合使用者自己工具所產生的 canonical 風格。 - 交付 — 顯示檔案樹、驗證結果，以及如何檢視圖表（
$LC4 start <dir>；匯出/CI 選項在setup-and-validation.md中）。
品質檢查清單（交付前確認）
-
likec4 validateexit 0（或揭露的自我檢查），stderr 乾淨。 -
likec4 format <dir> --checkexit 0 — 檔案為 canonical 格式。 - 每個元素都有描述；每個容器/元件都有
technology；每個關聯都有有方向的標籤（什麼 + 如何）。 - 每個檢視都有
title；每個檢視 ≤ ~20 個元素 — 擁擠的檢視請拆分。 - 各層級相連：上下文 → 容器 → 元件透過
view of/navigateTo。