design-doc-mermaid

Mermaid Architect - 階層式圖表與文件技能

Mermaid 圖表與文件系統，具備專門指南與程式碼轉圖表功能。

決策樹

此技能的運作方式：

使用者提出請求 → 技能分析意圖
技能決定圖表/文件類型 → 載入適當指南
AI 讀取專門指南 → 使用範本產生圖表/文件
傳送結果 → 附帶驗證與匯出選項

使用者意圖分析：

flowchart TD
    Start([使用者請求]) --> Analyze{分析意圖}

    Analyze -->|"工作流程、流程、商業邏輯"| Activity[載入活動圖指南<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"基礎設施、部署、雲端"| Deploy[載入部署圖指南<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"系統架構、元件"| Arch[載入架構指南<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API 流程、互動"| Sequence[載入序列圖指南<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"程式碼轉圖表"| CodeToDiag[載入程式碼轉圖表指南<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"設計文件、完整文件"| DesignDoc[載入設計文件範本<br/>assets/*-design-template.md]
    Analyze -->|"Unicode 符號、圖示"| Unicode[載入 Unicode 符號指南<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"提取、驗證、轉換"| Scripts[使用 Python 腳本<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[產生圖表]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[執行腳本]

    Generate --> Validate{驗證？}
    Validate -->|是| RunValidation[執行 mmdc 驗證]
    Validate -->|否| Output
    RunValidation --> Output[輸出結果]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

可用指南與資源

圖表類型指南（`references/guides/diagrams/`）

指南	完整路徑	當使用者想要	範例
活動圖	`references/guides/diagrams/activity-diagrams.md`	工作流程、流程、商業邏輯、使用者流程、決策樹	「顯示結帳流程」、「記錄 ETL 管線」、「建立核准工作流程」
部署圖	`references/guides/diagrams/deployment-diagrams.md`	基礎設施、雲端架構、K8s、無伺服器、網路拓撲	「顯示 AWS 架構」、「記錄 GCP 部署」、「建立 K8s 圖表」
架構圖	`references/guides/diagrams/architecture-diagrams.md`	系統架構、元件設計、高層級結構	「顯示系統元件」、「記錄微服務」、「架構概觀」
序列圖	`references/guides/diagrams/sequence-diagrams.md`	API 互動、服務通訊、請求/回應流程	「顯示 API 呼叫順序」、「記錄驗證流程」、「服務互動」

程式碼轉圖表指南與範例

資源	完整路徑	提供內容
主指南	`references/guides/code-to-diagram/README.md`	分析任何程式碼庫並提取圖表的完整工作流程
Spring Boot	`examples/spring-boot/README.md`	Controller→Service→Repository 架構、部署設定、方法序列、商業邏輯活動
FastAPI	`examples/fastapi/README.md`	Python 非同步模式、Pydantic 模型、依賴注入、雲端部署
React	`examples/react/README.md`	元件階層、狀態管理、資料流、建置管線
Python ETL	`examples/python-etl/README.md`	資料管線、轉換步驟、錯誤處理、排程
Node/Express	`examples/node-webapp/README.md`	中介軟體鏈、路由處理器、非同步模式、部署
Java Web App	`examples/java-webapp/README.md`	傳統 MVC、Servlet 容器、WAR 部署

設計文件範本

範本	完整路徑	用途	何時載入
架構設計	`assets/architecture-design-template.md`	系統級架構	「建立架構文件」、「記錄系統設計」
API 設計	`assets/api-design-template.md`	API 規格	「API 設計文件」、「記錄 REST API」
功能設計	`assets/feature-design-template.md`	功能規劃	「功能設計」、「規劃新功能」
資料庫設計	`assets/database-design-template.md`	資料庫綱要	「資料庫設計」、「記錄綱要」
系統設計	`assets/system-design-template.md`	完整系統	「系統設計文件」、「完整系統文件」

Unicode 符號指南

完整路徑： references/guides/unicode-symbols/guide.md

當使用者提到時載入： 「unicode 符號」、「圖表中的表情符號」、「語義圖示」、「加入符號」

快速參考：

📦 基礎設施：☁️ 🌐 🔌 📡 🗄️
⚙️ 運算：⚙️ ⚡ 🔄 ♻️ 🚀 💨
💾 資料：💾 📦 📊 📈 🗃️ 🧊
📨 訊息傳遞：📨 📬 📤 📥 🐰 📢
🔐 安全性：🔐 🔑 🛡️ 🚪 👤 🎫
📝 監控：📝 📊 🚨 ⚠️ ✅ ❌

Python 腳本（`scripts/`）

腳本	用途	何時載入
`extract_mermaid.py`	從 Markdown 提取圖表、驗證語法、取代為圖片	「提取圖表」、「驗證 mermaid」、「找出所有圖表」
`mermaid_to_image.py`	將 .mmd 轉換為 PNG/SVG、批次轉換、自訂主題	「轉換為圖片」、「渲染圖表」、「建立 PNG」
`resilient_diagram.py`	完整工作流程：儲存 .mmd、產生圖片、驗證、錯誤復原	「產生圖表」、「建立圖表並驗證」、「彈性圖表」

使用模式

常見請求模式與指南選擇。請參閱何時使用什麼以取得完整對應。

模式	範例請求	要載入的指南
單一圖表	「為登入流程建立活動圖」	圖表類型指南 + Unicode 符號
程式碼轉圖表	「從 application.yml 產生部署圖」	框架範例 + 部署指南
設計文件	「建立 API 設計文件」	assets/ 中的範本 + 相關圖表指南
提取/驗證	「從 design.md 提取圖表」	使用 `scripts/extract_mermaid.py`
批次轉換	「將所有 .mmd 轉換為 PNG」	使用 `scripts/mermaid_to_image.py`

彈性工作流程

重要： 這是所有圖表產生的建議方法。它確保驗證、錯誤復原和一致的檔案組織。

完整指南： references/guides/resilient-workflow.md

工作流程概觀

flowchart LR
    A[1. 識別類型] --> B[2. 儲存 .mmd + 圖片]
    B --> C{3. 有效？}
    C -->|是| D[4. 加入 Markdown]
    C -->|否| E[5. 錯誤復原]
    E --> F{找到修正？}
    F -->|是| A
    F -->|否| G[搜尋外部]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

關鍵原則

在圖表通過驗證之前，絕對不要將其加入 Markdown。 這可防止文件中出現損壞的圖表。

使用腳本（建議）

# 產生並完整錯誤復原
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

輸出： ./diagrams/ 目錄中的 .mmd 和 .png 檔案。

檔案命名慣例

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

範例： ./diagrams/api_design_01_sequence_auth_flow.png

錯誤復原優先順序

當驗證失敗時，工作流程會自動：

檢查疑難排解指南 - references/guides/troubleshooting.md（28 個記錄的錯誤）
使用 perplexity 搜尋 - perplexity_ask MCP 處理語法問題
使用 brave 搜尋 - brave_web_search MCP 尋找近期解決方案
詢問 gemini - gemini 技能取得替代觀點
一般搜尋 - WebSearch 工具作為備援

手動備援步驟

如果腳本不可用：

從第一行識別圖表類型（flowchart、sequence 等）
從 references/guides/diagrams/ 載入參考指南
儲存至 ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
驗證： mmdc -i file.mmd -o file.png -b transparent
發生錯誤時： 搜尋 references/guides/troubleshooting.md 尋找相符錯誤
如果找不到： 依上述優先順序使用搜尋工具
加入參考： ![Description](./diagrams/filename.png)

模式 6：彈性圖表產生

使用者： 「建立一個序列圖並加入設計文件中」

技能動作：

識別意圖：圖表產生 + Markdown 整合
載入工作流程指南：references/guides/resilient-workflow.md
識別圖表類型：序列
載入圖表指南：references/guides/diagrams/sequence-diagrams.md
使用範本產生 Mermaid 程式碼

執行彈性工作流程：

python scripts/resilient_diagram.py \
    --code "[產生的程式碼]" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "api_sequence" \
    --json

如果驗證失敗 → 套用疑難排解修正 → 重試
成功後 → 將 ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) 加入 Markdown

Unicode 語義符號

一律使用 Unicode 符號來增強圖表清晰度。常見模式：

基礎設施與部署

graph TB
    Client[👤 使用者] --> LB[🌐 負載平衡器]
    LB --> App1[⚙️ 應用伺服器 1]
    LB --> App2[⚙️ 應用伺服器 2]
    App1 --> DB[(💾 資料庫)]
    App1 --> Cache[(⚡ Redis)]

含狀態的活動流程

flowchart TD
    Start([🚀 開始]) --> Process[⚙️ 處理資料]
    Process --> Check{✓ 有效？}
    Check -->|是| Save[💾 儲存]
    Check -->|否| Error[❌ 錯誤]
    Save --> Complete([✅ 完成])

微服務架構

graph TB
    API[🌐 API 閘道] --> Auth[🔐 驗證服務]
    API --> Orders[📋 訂單服務]
    Orders --> Queue[📬 訊息佇列]
    Queue --> Worker[⚙️ 背景工作者]
    Worker --> Storage[📦 物件儲存]

如需完整符號參考，請載入： references/guides/unicode-symbols/guide.md

Python 工具

提取 Mermaid 圖表

# 列出所有圖表
python scripts/extract_mermaid.py document.md --list-only

# 提取到個別檔案
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# 驗證所有圖表
python scripts/extract_mermaid.py document.md --validate

# 取代為圖片參考（用於 Confluence 上傳）
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

轉換為圖片

# 單一轉換
python scripts/mermaid_to_image.py diagram.mmd output.png

# 自訂設定
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# 批次轉換目錄
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# 從標準輸入
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

決策樹範例

範例 1：使用者要求工作流程圖

輸入： 「顯示結帳流程工作流程」

技能決策路徑：

1. 分析：工作流程、流程 → 活動圖
2. 載入指南：guides/diagrams/activity-diagrams.md
3. 尋找模式：電子商務結帳（指南中有範本）
4. 使用範本 + Unicode 符號產生
5. 輸出含決策點的活動圖

輸出： 包含購物車、付款、訂單狀態 Unicode 符號的完整活動圖。

範例 2：使用者提供 Spring Boot 程式碼

輸入： 「這是我的 Spring Boot 控制器，建立圖表」

技能決策路徑：

1. 分析：Spring Boot、提供程式碼 → 程式碼轉圖表 + SPRING BOOT
2. 載入指南：
   - examples/spring-boot/README.md
   - guides/diagrams/architecture-diagrams.md（用於結構）
   - guides/diagrams/sequence-diagrams.md（用於方法呼叫）
   - guides/diagrams/activity-diagrams.md（用於商業邏輯）
3. 產生多個圖表：
   a. 從 @RestController/@Service/@Repository 註解產生架構圖
   b. 從方法呼叫鏈產生序列圖
   c. 從商業邏輯流程產生活動圖
4. 輸出所有圖表並附說明

輸出： 3-4 個圖表顯示 Spring Boot 應用程式的不同視角。

範例 3：使用者想要基礎設施文件

輸入： 「記錄我的 GCP Cloud Run 部署搭配 AlloyDB」

技能決策路徑：

1. 分析：基礎設施、GCP、Cloud Run → 部署圖
2. 載入指南：
   - guides/diagrams/deployment-diagrams.md
   - examples/spring-boot/ 或 examples/fastapi/（如果提供程式碼）
3. 檢查 IaC 檔案（Pulumi、Terraform、docker-compose）
4. 產生部署圖，包含：
   - Cloud Run 服務與規格
   - VPC 連接器
   - AlloyDB 叢集
   - 安全性（IAM、Secret Manager）
   - 監控
5. 套用 Unicode 符號以提升清晰度
6. 輸出並附資源規格

輸出： 完整 GCP 部署圖，所有資源均已標示。

高對比樣式

所有圖表必須使用高對比顏色：

graph TB
    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black

    %% 每個 classDef 必須有 color: 屬性

規則：

淺色背景 → 深色文字顏色
深色背景 → 淺色文字顏色
務必在每個 classDef 中指定 color:

檔案組織

design-doc-mermaid/
├── SKILL.md                          # 此檔案 - 主要協調器
├── README.md                         # 使用者文件
├── CLAUDE.md                         # Claude Code 指示
│
├── references/                       # 參考資料
│   ├── mermaid-diagram-guide.md     # 舊版通用指南
│   └── guides/                       # 專門指南（隨需載入）
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # 工作流程、流程
│       │   ├── deployment-diagrams.md    # 基礎設施、雲端
│       │   ├── architecture-diagrams.md  # 系統架構
│       │   └── sequence-diagrams.md      # API 互動
│       ├── code-to-diagram/
│       │   └── README.md                 # 程式碼分析主指南
│       ├── unicode-symbols/
│       │   └── guide.md                  # 完整符號參考
│       └── troubleshooting.md        # 常見語法錯誤與修正
│
├── assets/                           # 設計文件範本
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
│
├── scripts/                          # Python 工具
│   ├── extract_mermaid.py           # 提取與驗證圖表
│   └── mermaid_to_image.py          # 轉換為 PNG/SVG
│
├── examples/                         # 語言特定模式
│   ├── spring-boot/                 # Spring Boot 模式
│   ├── fastapi/                     # FastAPI 模式
│   ├── react/                       # React 模式
│   ├── python-etl/                  # 資料管線模式
│   ├── node-webapp/                 # Express.js 模式
│   └── java-webapp/                 # 傳統 Java 模式
│
└── references/                       # 通用 Mermaid 參考
    └── mermaid-diagram-guide.md     # 完整 Mermaid 語法指南

工作流程摘要

分析使用者意圖 → 決定圖表類型、文件類型或所需動作
載入適當指南 → 僅讀取所需內容（節省 token）
套用範本與模式 → 使用指南中的範例
產生輸出 → 建立圖表或文件
驗證（選用）→ 使用腳本確認
轉換（選用）→ 如有需要匯出為圖片

何時使用什麼

使用者請求	載入此項目
「活動圖」、「工作流程」、「流程圖」	`references/guides/diagrams/activity-diagrams.md`
「部署」、「基礎設施」、「雲端」、「k8s」	`references/guides/diagrams/deployment-diagrams.md`
「架構」、「系統設計」、「元件」	`references/guides/diagrams/architecture-diagrams.md` + 設計範本
「API」、「序列」、「互動」、「流程」	`references/mermaid-diagram-guide.md`（序列部分）
「Spring Boot 程式碼」	`examples/spring-boot/` + 相關圖表指南
「FastAPI 程式碼」、「Python API」	`examples/fastapi/` + 相關圖表指南
「React 應用程式」、「前端」	`examples/react/` + 架構指南
「ETL」、「資料管線」、「Python 批次」	`examples/python-etl/` + 活動指南
「符號」、「unicode」、「表情符號」	`references/guides/unicode-symbols/guide.md`
「語法錯誤」、「圖表無法渲染」、「疑難排解」	`references/guides/troubleshooting.md`
「提取圖表」	`scripts/extract_mermaid.py`
「轉換為圖片」、「PNG」、「SVG」	`scripts/mermaid_to_image.py`
「建立圖表」、「產生圖表」、「將圖表加入 markdown」	`scripts/resilient_diagram.py` + `references/guides/resilient-workflow.md`
「設計文件」、「完整文件」	`assets/*-design-template.md` + 圖表指南

最佳實踐

單一職責：一個圖表 = 一個概念
Unicode 增強：一律使用語義符號提升清晰度
高對比：絕不省略樣式中的 color: 屬性
及早驗證：使用腳本捕捉語法錯誤
範本重複使用：善用現有範本與範例
隨需載入：僅讀取特定請求所需的指南
Token 效率：使用階層式載入而非讀取所有內容

學習路徑

Mermaid 新手？ 從這裡開始：

閱讀 references/guides/unicode-symbols/guide.md 了解符號意義
閱讀 references/guides/diagrams/activity-diagrams.md 了解基本模式
嘗試 examples/spring-boot/ 或 examples/fastapi/ 中的範例
使用 scripts/extract_mermaid.py --validate 檢查你的作品

需要記錄程式碼？ 遵循以下步驟：

識別你的框架 → 載入相關的 examples/{framework}/
將程式碼模式對應到圖表類型
使用指南中的範本
使用腳本驗證

正在建立設計文件？ 遵循以下步驟：

選擇文件類型 → 從 assets/ 載入範本
填寫文字區段
根據需要為每個區段載入圖表指南
全程使用 Unicode 符號
儲存至 docs/design/ 並加上時間戳記

版本： 2.0（階層式架構）
最後更新： 2025-01-13
維護者： Claude Code Skills

您可能也喜歡

deployment-patterns

230Kdevops-cloud

Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications.

affaan-m

獲取

import-infrastructure-as-code

37Kdevops-cloud

Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type.

github

獲取

docker-expert

41Kdevops-cloud

您是進階的 Docker 容器化專家，具備全面的實務知識，涵蓋容器優化、安全強化、多階段建置、編排模式以及基於當前業界最佳實務的生產部署策略。

sickn33

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新

design-doc-mermaid

相關技能

Mermaid Architect - 階層式圖表與文件技能

目錄

決策樹

可用指南與資源

圖表類型指南（references/guides/diagrams/）

程式碼轉圖表指南與範例

設計文件範本

Unicode 符號指南

Python 腳本（scripts/）

使用模式

彈性工作流程

工作流程概觀

關鍵原則

使用腳本（建議）

檔案命名慣例

錯誤復原優先順序

手動備援步驟

模式 6：彈性圖表產生

Unicode 語義符號

基礎設施與部署

含狀態的活動流程

微服務架構

Python 工具

提取 Mermaid 圖表

轉換為圖片

決策樹範例

範例 1：使用者要求工作流程圖

範例 2：使用者提供 Spring Boot 程式碼

範例 3：使用者想要基礎設施文件

高對比樣式

檔案組織

工作流程摘要

何時使用什麼

最佳實踐

學習路徑

您可能也喜歡

deployment-patterns

import-infrastructure-as-code

docker-expert

繼續探索

圖表類型指南（`references/guides/diagrams/`）

Python 腳本（`scripts/`）