DESIGN.md 是什麼？為何 AGENTS.md 不夠

DESIGN.md 的用途，以及 AGENTS.md 未涵蓋的內容

DESIGN.md 是儲存庫根目錄中的 markdown 檔案，用來告訴 AI coding agent 程式碼為何採用目前的結構。AGENTS.md 回答的是另一個問題：在這裡應如何工作，包括建置命令、測試命令、必須通過的 lint，以及不得修改的路徑。DESIGN.md 記錄已確立的設計決策，以及撤銷這些決策會造成什麼問題。

coding agent 是指 Claude Code 或 Cursor 之類，能自行讀取及編輯儲存庫的工具。這類工具預設會自行判斷。它遇到不熟悉的模式時，往往會加以改進。手寫的快取可能會被改成 Redis（一種記憶體內資料儲存區），因為模型讀過的大多數程式碼中，快取都是這樣實作的。AGENTS.md 無法阻止這種情況，因為無論採用哪種方式，make test 都能通過。被破壞的規則從未寫在 agent 能讀取的地方。

如果你還沒有建立第一個檔案，請先從那裡開始。AGENTS.md 以及放在旁邊的 HUMAN.md 說明檔案格式，以及每個工具會在哪裡尋找這些檔案。接下來的內容是該章之後的章節。

已發布的 DESIGN.md 實際包含哪些內容

了解格式最快的方法，是閱讀各家公司發布的相關檔案。official-design-md 儲存庫 只追蹤這些檔案。它的納入規則只有一行，而這一行正是整個集合的重點：

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

截至 October 2026，清單中共有 eleven 個項目：Ant Design、Atlassian、Clerk、Juspay、Microsoft FAST、Mintlify、Nuxt、Oxide Computer、Resend、Vercel 和 VoltAgent。每個檔案都有公開 URL，其中大多位於發布者自己的網域，其餘則位於公開的 GitHub 儲存庫，因此你現在就能在終端機中讀取其中一個。

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

這兩個檔案都是設計系統文件。它們描述產品應有的外觀，包括色彩、字體、間距和動態效果。請不要只看主題內容，因為真正有用的是文字的結構，而不是主題本身。

截至 October 27, 2026，Nuxt 檔案約有 2,000 個單字，其中大多數內容都是附帶理由的規則。檔案開頭先說明深色模式是預設主題。接著列出品牌綠色 #00DC82，並附註品牌色彩「適用於標誌、社群圖片和印刷品。請勿在 UI 程式碼中直接使用這些原始值。」接近結尾處有一個標題為 Reject these 的區段，其中包含：

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Vercel 檔案更長，截至 October 2026 約有 6,000 個單字，而且更進一步。其中一個標題是 Reject generated-design reflexes。下方列出一個有能力的產生器在沒有收到禁止指示時會採用的做法：

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

這句話定義了這種檔案的類型。它是對有自信的模型所產生之預設值的書面清單，發布這份清單是為了讓模型停止產生這些內容。任何值得提交的 DESIGN.md，都是某個領域的這份清單。

為什麼企業要發布自己的 DESIGN.md？

社群較早建立了這套做法。awesome-design-md 收錄 84 個從公開網站擷取的檔案。這是截至 October 27, 2026 的 README 計數。每個檔案都採用相同的九個章節格式，因此可以將其中一個提供給 agent，產生風格相近的結果。這些檔案很有用，但仍然只是推測。相關企業沒有人審查過這些內容。

第一方檔案有所不同，因為它是來源本身，而不是對產出結果的解讀。Vercel 調整字級比例時，vercel.com/design.md 也會同步變更。3 月擷取的複本仍會讓 agent 使用舊的字級比例，而 repository 中沒有任何資訊會告訴你這份複本已經過時。

11 家發布者仍然是少數，repository 也明確說明了這點：這項標準仍然很新，正式採用率正在提高。兩個集合都由 VoltAgent 維護。VoltAgent 是一個 open source agent framework，也發布了自己的檔案。因此，應將這份清單視為追蹤工具，而不是中立的普查結果。這份清單仍值得持續關注，因為其中的成員很重要。其中幾家企業的 front-end code 最常被其他開發者複製。較新的成員 Ant Design、Microsoft FAST、Juspay 和 Oxide Computer，則是其他團隊建置產品時採用的 design systems。它們的檔案正逐漸成為 DESIGN.md 應有形式的實作範例。比較 AGENTS.md 的發展路徑：agents.md 目前統計已有超過 60,000 個使用這項格式的 open source projects，相關維護工作則由 Linux Foundation 旗下的 Agentic AI Foundation 負責。DESIGN.md 已開始走上相同的道路。April 21, 2026，Google 將這項格式的草案規格開放為 open source，發布於 google-labs-code/design.md，並以 Apache-2.0 licence 提供 token schema 和 CLI。截至 October 2026，這項格式仍處於 version alpha，且持續積極開發中；目前由 Google Labs 而非中立 foundation 維護。它描述的是 visual identity，因此沒有說明 backend file 所需的不變條件。agent 可讀檔案的慣例正在快速定型，而且是由上而下逐步定型。

沒有使用者介面的專案，DESIGN.md 應包含哪些內容

在 VPS 上執行的多數軟體都沒有需要定義的視覺語言。這個檔案仍然有其價值，因為機制與色彩無關。它的用途是記錄限制條件，避免熟練的編輯者在未察覺的情況下違反這些條件。

不變條件。 每項各用一句話，說明任何編輯後都必須維持的狀態。「所有寫入都必須經過 queue.enqueue()。直接寫入資料庫會跳過稽核日誌，而合規性匯出讀取的正是稽核日誌。」附帶原因的不變條件，即使遇到未預期的工作也能維持有效。單獨列出的不變條件看起來像偏好，而偏好通常會在最佳化時被移除。

遭拒絕的替代方案。 說明看似合理的選項，以及它為何未被採用。「我們不使用 Redis 進行快取。服務只在單一 VPS 上執行，因此程序內 map 速度較快，也少了一個需要維持執行的 daemon。等到有第二台應用程式伺服器時再重新評估。」沒有這段說明時，如果要求代理程式加快快取速度，它會加入 Redis，而且這樣做是合理的：因為你從未告知它這項限制。這一節足以讓整個檔案發揮價值。

邊界。 說明小幅編輯可能造成重大影響的部分。例如資料庫 schema、客戶已經透過腳本使用的公開路徑前綴、部署程序在應用程式啟動前讀取的設定檔，以及假設只會執行單一副本的 cron 項目。列出這些項目，並說明修改各項的成本。如果代理程式也能透過 設定為搜尋後端的自架 SearXNG 實例 存取公開網路，也應記錄這項邊界，因為檔案應明確說明哪些擷取到的文字可以影響程式碼，以及哪些文字只能原樣引用給你。

詞彙。 如果程式碼使用 tenant，而團隊使用 customer，請記錄兩者的對應關係。代理程式若在這裡判斷錯誤，會產生讀起來正常、但實際建模錯誤的程式碼；這是程式碼審查中最難發現的錯誤類型。

今天就能複製使用的 DESIGN.md

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

填寫今天能憑記憶寫出的兩個部分：不變條件與拒絕的替代方案，其餘部分先保留標題。一份只有 4 行且內容誠實的檔案即可。包含 40 行臆測內容的檔案則不行。如果儲存庫包含多個套件，單一根目錄檔案無法涵蓋所有套件；此時適用於 monorepo 中巢狀的 AGENTS.md 檔案 的逐目錄拆分方式：根目錄放置一份簡短檔案，記錄所有套件共用的決策；每個有自身決策的套件旁，再放置一份更小的檔案。

有些工具會載入儲存庫根目錄中的所有 markdown 檔案，有些只會載入指定的檔案，因此不要自行假設。請在 AGENTS.md 中加入指向 DESIGN.md 的指標：

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

反模式：重複 README 內容的 DESIGN.md

最常見的錯誤版本讀起來通順，卻沒有提供任何新知。它先介紹專案的用途，列出功能，說明安裝方式，最後以授權條款結尾。這些內容 README 都已經涵蓋，而且沒有任何一項說明為什麼要這樣設計。

這會造成兩重成本。第一重是內容脈絡。代理程式每次開始工作時都會讀取這個檔案，因此每項工作都要付出相同的讀取成本；在固定的內容視窗中，重複的安裝章節只是額外負擔。如何分配這個視窗本身就是一項技能，詳見 在 Claude Code 中管理內容視窗。簡單來說：任何會自動載入的內容，都應該是儲存庫中價值最高的文字。

第二重成本更嚴重。同一項陳述有兩份副本時，內容會逐漸產生差異。README 說服務監聽 8080，DESIGN.md 卻仍寫著 3000，而代理程式無法判斷哪一份優先，因此會選擇其中一個，並據此撰寫程式碼。一個有時會出錯的檔案，會被以和一個始終正確的檔案相同的信心查閱。

測試很快。如果某個段落放在 README 中也很合適，就從 DESIGN.md 刪除。留下來的內容，應該是你在程式碼審查時會直接說出來的部分，也就是以「我們已經試過那個方法」開頭的內容。

如何確認檔案確實生效？

這沒有 linter 可用。但你可以在 1 分鐘內執行一項檢查。

交給 agent 一項會直接觸及不變條件的工作。例如：「新增一個背景工作，將過期資料列標記為已過期。」檔案是否發揮作用，會在任何程式碼出現前反映於回答中：agent 應告訴你，這項工作會透過 queue.enqueue() 寫入，因為直接寫入會略過 audit log。如果它開啟資料庫連線並直接寫入，只有兩種可能：檔案根本沒有被讀取，或不變條件的描述過於寬鬆，足以讓人提出異議。

也要監看 token 數量，因為每一輪都會載入這個檔案。如果加入 DESIGN.md 後，context 使用量上升，但回答沒有改善，表示檔案包含 agent 原本就知道的文字。閱讀 Claude Code 中的 token 計數器會說明這些額度用在哪裡。

當 agent 執行於伺服器而非你的筆電時，這點尤其重要。執行於長時間工作階段的 agent，例如 在 VPS 上使用 tmux 建立 Claude Code 工作區中的設定，不會記得昨天的對話。儲存庫就是記憶體。你在聊天中說明、卻未提交的所有內容，都會在下一個工作階段消失；而 DESIGN.md 就是保存這些說明、讓它們持續存在的地方。

從你最常爭論的決策開始

第1個版本只需要20分鐘。開啟最近幾個 pull request，找出審查者寫下「不行，我們這裡的做法不同」的地方。每則這類留言都代表一項尚未記錄的不變條件，也是 agent 會犯下相同錯誤的地方，而且速度更快、頻率更高。當它讓你出錯時就更新檔案，不要依照固定排程更新。如果你仍在摸索 agent 適合放入一般開發工作流程的方式，可以接著閱讀 2026年 AI agent 學習指南。

FAQ

DESIGN.md 是正式標準嗎？

不是，至少不像 AGENTS.md 那樣。AGENTS.md 在 agents.md 有專屬網站，目前有超過 60,000 個開源專案使用，並由 Linux Foundation 旗下的 Agentic AI Foundation 負責維護。DESIGN.md 雖然已有發布的規格，但沒有中立的維護組織。Google 在 April 21, 2026 將規格草案開源，目前存放於 google-labs-code/design.md repository，採用 Apache-2.0 授權條款。截至 October 2026，該規格仍處於 alpha 版本並持續開發中，內容描述視覺識別，包括色彩、字體、版面配置與元件。DESIGN.md 也已有第一方採用案例：包括 Vercel、Nuxt、Atlassian 與 Resend 在內的 eleven 家公司和專案都發布了這類檔案；截至 October 27, 2026，社群彙整資料中另有從公開網站擷取的 84 份檔案。若要在 backend 檔案中記錄不變條件與遭拒的替代方案，現在可以把它視為可採用並自由擴充的慣例，因為目前沒有任何規格涵蓋這些 section 名稱。

DESIGN.md 是否應該只是 AGENTS.md 的一個 section？

對小型 repository 而言，是的。讓 agent 確實讀取一個檔案，勝過使用兩個檔案但其中一個被忽略。當 AGENTS.md 不再容易快速瀏覽，或你發現兩個部分的變更頻率不同時，再將它們拆開。AGENTS.md 會隨著 build 變更。DESIGN.md 會在決策變更時更新，而這種情況較少發生，影響也更大。拆分後，請在 AGENTS.md 加入一行，告知 agent 編輯程式碼前先讀取 DESIGN.md，因為不是每個工具都會載入 root 中的每個 markdown 檔案。

DESIGN.md 與 architecture decision record 有何不同？

ADR（architecture decision record）是單一決策的具日期紀錄，健全的專案會在一個 folder 中累積數十份 ADR。這是一段歷史，而載入歷史的成本很高，因為 agent 必須讀取所有 ADR，才能判斷哪些內容目前仍然有效。DESIGN.md 則描述目前狀態，設計成每次執行 task 時完整讀取。若你目前已經撰寫 ADR，兩者都保留。ADR 說明當時決定了什麼，以及何時決定。DESIGN.md 說明今天哪些內容有效，也是你應該提供給 agent 的檔案。

DESIGN.md 應該有多長？

以每個 turn 都能毫不猶豫地載入為限。已發布的範例較長，因為它們定義完整的視覺語言：截至 October 2026，Nuxt 檔案約 2,000 words，Vercel 檔案約 6,000 words。backend service 通常需要少得多。先從一頁開始，只有在 agent 犯下原本一句話就能避免的錯誤時，才繼續擴充。長度不是衡量標準。每一行都應該描述 agent 否則會弄錯的事項。