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.

截至 August 2026，清單中有 7 家公司：Atlassian、Clerk、Mintlify、Nuxt、Resend、Vercel 和 VoltAgent。每個檔案都有穩定的公開 URL，因此你現在就能在終端機中閱讀其中一個。

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

這兩份都是設計系統文件。它們說明產品應呈現的樣子：色彩、字體、間距與動態效果。請不要只關注主題，因為真正有用的是文字的結構，而不是內容所屬的領域。

Nuxt 的檔案約有 2,100 個字，其中大多數內容都是附帶原因的規則：

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Vercel 的檔案更長，截至 August 2026 約有 6,500 個字，而且更進一步。其中一個標題是 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 收錄了 73 個從公開網站反向工程而來的檔案。每個檔案都採用相同的 9 個章節格式，因此可以將其中一個檔案提供給代理程式，產生風格相近的結果。這些檔案很有用，但仍然只是推測。相關公司沒有人審閱過這些內容。

第一方檔案有所不同，因為它是來源，而不是對輸出結果的解讀。Vercel 調整字型比例時，vercel.com/design.md 也會隨之更新。3 月抓取的副本仍會教導代理程式使用舊的字型比例，而儲存庫中沒有任何內容會告訴你這份副本已經過時。

7 個發布者仍是少數，儲存庫也明確說明了這點：這項標準仍然很新，官方採用率正在上升。兩個集合都由 VoltAgent 維護。VoltAgent 是開放原始碼代理程式框架，也發布了自己的檔案。因此，應將這份清單視為追蹤器，而不是中立的普查結果。這份清單仍值得關注，原因在於這 7 家公司的身分。其他開發人員最常複製的，就是這些公司的前端程式碼；它們的檔案也逐漸成為 DESIGN.md 實際應用方式的範例。比較 AGENTS.md 的發展路徑：agents.md 現在已有超過 60,000 個開放原始碼專案採用這項格式，維護工作則由 Linux Foundation 旗下的 Agentic AI Foundation 負責。代理程式可讀檔案的慣例正在迅速定型，而且是由頂端開始定型。

沒有使用者介面的專案，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 中加入指向該檔案的指標：

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 一項會直接觸及不變條件的工作。例如：「新增一個背景工作，將過期資料列標記為 expired。」檔案是否發揮作用，會先反映在回答中，之後才是程式碼：agent 應該告訴你，這項工作會透過 queue.enqueue() 寫入，因為直接寫入會略過 audit log。如果它開啟資料庫連線並直接寫入，只有兩種可能：檔案根本沒有被讀取，或是不變條件的描述不夠明確，留下了爭辯空間。

也要注意 token 數量，因為每一輪都會載入這個檔案。如果加入 DESIGN.md 後，context 使用量增加，但回答沒有改善，表示檔案包含 agent 原本就知道的文字。閱讀 Claude Code 中的 token 計數器會說明這些預算的使用位置。

當 agent 運行在伺服器上，而不是你的筆電上時，這點尤其重要。像 在 VPS 上使用 tmux 建立 Claude Code 工作區 這類長時間執行的 session，不會記得前一天的對話。儲存庫就是記憶。你在聊天中說明、但從未提交的內容，下一個 session 就會消失；而 DESIGN.md 能保存這些說明，讓它們持續存在。

先處理你經常爭論的決策

第一個版本只需要 20 分鐘。開啟最近幾個 pull request，找出審查者寫下「不，我們這裡的做法不同」的地方。這些留言都代表尚未記錄的 invariant，也是 agent 會重複犯錯的地方，而且速度更快、頻率更高。只有在檔案未能協助你時才更新，不要依照固定排程更新。如果你仍在摸索 agent 適合放入一般開發工作流程的方式，2026 年學習 AI agent 的指南 是合理的下一步。

FAQ

DESIGN.md 是官方標準嗎？

不是，至少不像 AGENTS.md 那樣。AGENTS.md 在 agents.md 有專屬網站，目前有超過 60,000 個開源專案採用，並由 Linux Foundation 旗下的 Agentic AI Foundation 負責維護。截至 August 2026，DESIGN.md 沒有管理組織，也沒有公開的規格。它目前具備的是第一方採用：包括 Vercel、Nuxt、Atlassian 和 Resend 在內的 7 家公司，會在公開 URL 提供這類檔案；社群集合則收錄了另外 73 份從公開網站反向整理的檔案。你現在就可以把它視為一項慣例來採用，並自由擴充，因為沒有任何機制會驗證你的章節名稱。

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

對小型儲存庫而言，是的。代理程式確實會讀取的 1 個檔案，勝過其中 1 個會被忽略的 2 個檔案。當 AGENTS.md 不再容易快速瀏覽，或你發現兩個檔案的變更頻率不同時，再將它們拆開。AGENTS.md 會在建置流程變更時修改。DESIGN.md 會在決策變更時修改，這種情況較少，但影響更大。拆分後，請在 AGENTS.md 加入 1 行，告訴代理程式在編輯程式碼前先讀取 DESIGN.md，因為不是每個工具都會載入根目錄中的所有 markdown 檔案。

DESIGN.md 與架構決策紀錄有何不同？

ADR（架構決策紀錄）是針對單一決策所寫的具日期紀錄，成熟的專案通常會在資料夾中累積數十份 ADR。這是一段歷史，而載入歷史的成本很高，因為代理程式必須讀完所有紀錄，才能判斷哪些內容仍然有效。DESIGN.md 描述的是目前狀態，設計目標是每次執行任務時完整讀取。如果你已經在撰寫 ADR，請兩者並用。ADR 說明做了什麼決定，以及決定的時間。DESIGN.md 說明今天哪些內容有效，也是你應該提供給代理程式閱讀的檔案。

DESIGN.md 應該多長？

短到每次互動都能載入，而且不會讓人後悔。公開範例較長，是因為它們定義了完整的視覺語言：截至 August 2026，Nuxt 檔案約有 2,100 個單字，Vercel 檔案約有 6,500 個單字。後端服務通常需要少得多。先從 1 頁開始，只有在代理程式犯下原本只要 1 句話就能避免的錯誤時，才繼續擴充。長度不是衡量標準。每一行都應該描述代理程式原本可能弄錯的事項。