這些圖表的意義在於，剛接觸該儲存庫的人可以信賴它們。一張憑空捏造服務或遺漏資料庫的圖表比沒有圖表更糟，因此這裡的一切都著重於繪製程式碼實際顯示的內容。
1. 畫圖前先調查
對儲存庫根目錄執行 scripts/survey.py（此技能中的路徑是相對於其資料夾的）：
python3 scripts/survey.py /path/to/repo > /tmp/mermaid-survey.txt
它會列出模組及其檔案計數、清單檔、進入點、宣告的相依性中找到的外部服務、資料模型來源，以及模組之間的匯入圖（含計數）。每個匯入邊緣都來自真實的 import 陳述式，因此請使用這些邊緣作為架構圖的主幹。如果某個模組包含了大部分程式碼而需要拆分，請加上 --depth 3 重新執行。
接著閱讀腳本無法看到的內容：
- README 和任何現有文件，以取得團隊已使用的名稱
- 進入點，以查看哪些是以獨立程序運行的（伺服器、工作者、CLI、排程任務、Lambda）
- 部署設定（Dockerfile、compose 檔案、fly.toml、serverless/CDK、Terraform），以了解哪些是分開部署的以及它與什麼通訊
- 跨越程序邊界的呼叫：HTTP 客戶端和基礎 URL、佇列發布者和消費者、外部服務的 SDK 用戶端
簡短記錄哪個檔案支援每個方框和箭頭。這將成為輸出中的「來源」清單。
如果使用者只要求一個圖表（例如「我們資料庫的 ER 圖」），則只製作該圖表，但仍需先進行調查。
2. 架構概觀
繪製一個 flowchart，展示可部署的元件及其內部的模組，以及它們使用的資料儲存和外部服務。目標是 6 到 20 個節點。較大的儲存庫應按可部署單元分組為子圖，而不是增加更多方框。
- 節點是開發者會命名的東西：例如「API 伺服器」、「網頁應用程式」、「firehose 消費者」、「PostgreSQL」、「Stripe」。使用 README 或套件名稱中的團隊慣用名稱。
- 箭頭從呼叫者指向被呼叫者，並在跨越程序時說明方式（例如「REST /api」、「SQL」、「S3 上傳」）。保留程序內部的匯入不加上標籤。
- 捨棄無法解釋系統的內容：每個人都匯入的實用模組、僅有型別的套件、測試、建置腳本。如果它們很重要，在文字中提及即可。
- 不要畫你無法指出的東西。 如果你懷疑有連線但找不到程式碼，請省略它並在文字中說明。
形狀和樣式慣例請參閱 references/diagram-guide.md。
3. 資料模型
僅在調查列出資料模型來源時才繪製 erDiagram；如果沒有，則用一句話說明並跳過。不要從 API 型別或變數名稱推斷資料表，因為猜測的結構描述看起來與真實的一樣具有權威性。
- 遷移檔案是真理（如果存在）。按順序套用它們，因此後續的
ALTER、DROP和重新命名優先。如果 ORM 模型與遷移檔案不一致，請遵循遷移檔案並註明不一致之處。 - 兩組遷移檔案（例如，舊的
supabase/migrations/和當前的drizzle/資料夾）通常表示其中一組已過時。請遵循應用程式的 migrate 命令或 ORM 設定所指向的那一組（例如drizzle.config.*、prisma/schema.prisma、package.json中的migrate腳本），並在文字中命名過時的那組。 - 顯示鍵值和識別行的欄位：主鍵、外鍵、唯一欄位，以及少數讀者需要用來識別實體的欄位。除非時間戳記和其他記帳欄位很重要，否則請跳過它們。
- 從約束條件讀取基數。 非空的外鍵在父端是恰好一個，可空的是零或一個，而唯一的外鍵則表示關係是一對一。使用簡短的動詞短語標記每個關係。
- 如果實體超過約 15 個，則按領域拆分圖表，而不是繪製一整面牆的表格。
4. 寫入檔案
寫入 docs/architecture.md，如果該檔案已存在則更新它。如果儲存庫將文件放在其他地方，請遵循該位置；如果使用者指定了路徑，則使用他們的路徑。對於每個圖表：
## 架構
兩三句話說明圖表顯示的內容以及它遺漏了什麼。
<!-- mermaid-gen:start architecture -->
```mermaid
flowchart LR
...
```
<!-- mermaid-gen:end architecture -->
**來源：** `cmd/server/main.go`、`internal/handler/`、`fly.toml`
標記式註解讓後續執行時可以只替換圖表，而不會影響使用者手動編輯的文字。更新現有檔案時，僅更改標記內的內容，以及緊鄰它們的說明和來源。
5. 檢查渲染效果
對檔案執行 scripts/lint_mermaid.py：
python3 scripts/lint_mermaid.py /path/to/repo/docs/architecture.md
它會捕捉最常破壞渲染的錯誤：未引號標籤中的特殊字元、將 end 等保留字用作節點 ID、未封閉的 subgraph，以及格式錯誤的 ER 關係或屬性。在完成前修正每個錯誤。如果已安裝 mmdc（mermaid-cli），也一併使用它來渲染。
最後，告訴使用者檔案的位置、每個圖表涵蓋的內容，以及你遺漏或無法確認的任何事項。