architecture

架構 skill 總覽

architecture skill 的用途

architecture 是一個用來在 HTML 與 CSS 中建立分層系統視圖的繪圖 skill，不是泛用的畫圖提示詞。它能幫你把粗略的系統想法整理成可讀的架構圖，包含色塊分區、以格線為基礎的版面，以及清楚的元件階層。

誰適合使用它

如果你需要向工程師、利害關係人或審查者說明平台結構、服務邊界、請求流程或基礎架構層，architecture skill 很適合你。它特別適合想要用 Diagramming workflow 產出圖表的使用者，因為這種工作方式便於快速編輯、在 Markdown 中順利渲染，而且能在不同專案間維持一致。

最適合的使用情境與限制

它最適合用來表達使用者／應用程式／資料／基礎架構視角、微服務地圖、企業應用總覽，以及儀表板風格的系統摘要。它不適合拿來做像素級精準的客製繪圖、正式 UML 建模，或圖表型資料視覺化；這些情境通常會有其他工具更合適。

如何使用 architecture skill

安裝並先讀對檔案

進行 architecture install 時，先用 npx skills add markdown-viewer/skills --skill architecture 安裝這個 skill，然後從 SKILL.md 開始。接著查看 layouts/ 裡的版面檔案，以及 styles/ 裡的樣式預設，先選出與你的結構相符的模板，再開始寫內容。

把粗略想法變成可用提示詞

好的 architecture 使用方式，起點是明確目標，而不是一句「幫我做一張架構圖」。你要提供系統目的、希望呈現的層級、重要元件，以及它們之間的關係。例如：「為一個支付平台建立架構圖，包含公開 API、驗證層、訂單服務、資料庫、queue，以及外部 PSP 整合。」

先選對模板

在補細節前，先決定圖的形狀。一般分層系統請用 layouts/layer-layouts.md，等權重服務適合 layouts/grid-catalog.md，整合平台適合 layouts/hub-spoke.md，而當流程方向最重要時則用 layouts/connectors.md。如果你不確定，先看 layouts/banner-center.md、layouts/dashboard.md 與 layouts/pipeline.md，因為它們展示了最常見的組合模式。

遵守 HTML 限制

architecture skill 期待的是直接嵌在 Markdown 裡的 HTML，而且圖形內容外層不要再包 fenced code block。HTML 區塊內部要保持連續，不要插入空白行，因為 parser 對結構很敏感。建立圖表時應分階段進行：先搭框架，再放容器，接著加標籤與內容，最後才調整樣式。

architecture skill 常見問題

architecture skill 比一般提示詞更好嗎？

多數情況下是，尤其當你需要可重複產出的 Diagramming 結果時。這個 skill 提供版面模式、HTML 規則與樣式慣例，能減少猜測，也讓輸出比一次性的提示詞更容易渲染與修改。

使用前我應該提供什麼？

請提供系統目標、主要層級、關鍵服務，以及任何重要的方向性流程或邊界。如果你已經知道輸出形式，也要明確說出來，例如「單一堆疊」、「雙欄分割」或「hub and spoke」，這樣 skill 不必自行推斷結構。

什麼時候不該用 architecture？

當目標是精準的視覺草圖、正式軟體標記法，或分析型圖表時，就不要用它。如果你的輸出需要精確幾何、符合標準的 UML，或大量資料圖，architecture skill 通常不是最佳選擇。

它適合初學者嗎？

適合，只要你能用白話描述一個系統。初學者最容易得到好結果的方式，是先做一張圖、鎖定一個受眾、採用一種版面，而不是一開始就想把整個平台一次建模完成。

如何改善 architecture skill

給 skill 更少但更清楚的決策

architecture skill 最能發揮效果的情況，是你在一開始就定義好受眾與細節層級。請說明這張圖是給工程師、管理層還是文件用途，並只保留會影響故事重點的元件；箱子太多通常只會讓可讀性變差。

指定流程，而不只是列出元件

常見的失敗情況，是只列元件，卻沒說明它們如何互動。要改善 architecture 的使用，請先寫出主要路徑，例如「browser → API gateway → service → database」，再只在必要時補上 cache、async queue 或第三方呼叫等例外。

讓版面對應問題本身

如果第一版看起來很擁擠，問題往往是模板不合，而不一定是內容不好。可以用更適合的結構重寫提示詞：平台堆疊視角用分層版面，服務組合用 grid catalog，而當依賴關係與箭頭才是重點時，就用 connectors。

用具體修正方式迭代

在第一版之後，請提出明確修改：減少巢狀、放大核心服務、分開外部系統，或簡化標籤。architecture skill 更適合接收「要保留什麼、要改什麼」這類輸入；比起只說「做得更乾淨」，有指出問題點的修正指令更有效。