DESIGN.md：AGENTS.md 之後該建立的檔案

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

DESIGN.md 是存放在儲存庫根目錄中的 Markdown 檔案，用來告訴 AI 程式碼代理程式，程式碼為何採用目前的結構。AGENTS.md 回答的是另一個問題：如何在此處工作，包括建置命令、測試命令、必須通過的 lint，以及不可變更的路徑。DESIGN.md 記錄已確立的設計決策，以及撤銷這些決策時會造成的問題。

程式碼代理程式是指 Claude Code 或 Cursor 這類能自行讀取及編輯儲存庫的工具。這類工具預設會充滿信心。它發現不熟悉的模式時，會改進該模式。手寫的快取可能會被改成 Redis（記憶體內資料儲存區），因為在模型讀過的大多數程式碼中，快取通常就是這樣實作。AGENTS.md 無法阻止這種情況，因為 make test 無論採用哪種方式都能通過。遭到違反的規則，從未記錄在代理程式能讀取的位置。

如果你尚未建立第一個檔案，請先從這裡開始。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.

截至 2026 年 8 月，清單中有 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 檔案更長，截至 2026 年 8 月約有 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 份檔案。每份檔案都採用相同的九個章節格式，因此可以將其中一份提供給代理程式，產生風格相近的結果。這些檔案很有用，但仍然只是推測。相關公司沒有審閱過這些檔案。

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

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

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

在 VPS 上執行的大多數軟體，都沒有需要指定視覺語言的使用者介面。這個檔案仍然有其價值，因為其作用與色彩無關。它用於記錄限制條件，避免原本有經驗的編輯者在未察覺的情況下違反這些條件。

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

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

邊界。 說明小幅編輯可能造成大範圍影響的位置。資料庫 schema。客戶已經透過指令碼使用的公開路由前綴。部署程序會在應用程式啟動前讀取的設定檔。假設只會執行一個副本的 cron 項目。列出這些項目，並說明變更各項目需要付出的代價。

詞彙。 如果程式碼使用 tenant，團隊卻使用 customer，請記錄兩者的對應關係。agent 若在此處猜錯，會產生讀起來沒有問題、但實際上建模錯誤的程式碼；這是程式碼審查中最難發現的錯誤類型。

今天即可複製的 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行猜測內容的檔案則不行。

有些工具會載入儲存庫根目錄中的所有 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 一項會直接觸及不變條件的工作。「新增一個背景工作，將過期資料列標記為已過期。」檔案是否發揮作用，會先反映在回答中，而不是程式碼中：agent 應告訴你，此工作會透過 queue.enqueue() 寫入，因為直接寫入會略過稽核記錄。如果它開啟資料庫連線並寫入，原因只有兩種。檔案根本沒有被讀取，或是不變條件的措辭過於寬鬆，足以讓人提出異議。

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

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

從你爭論過的決策開始

第一個版本只需二十分鐘。開啟最近幾個 pull request，查看審查者寫下「不，我們這裡的做法不同」的地方。每則這類留言都是未曾記錄的 invariant，也是 agent 會犯下相同錯誤的地方，而且速度更快、頻率更高。只有在檔案讓你失望時才更新，不要依照固定時程更新。如果你仍在釐清 agent 如何融入一般開發工作流程，2026 年學習 AI agent 的指南是合理的下一步。

FAQ

DESIGN.md 是正式標準嗎？

它不像 AGENTS.md 那樣是正式標準。AGENTS.md 的官方網站是 agents.md，已有超過 60,000 個開源專案使用，並由 Linux Foundation 旗下的 Agentic AI Foundation 負責管理。截至 2026 年 8 月，DESIGN.md 沒有管理組織，也沒有公開規格。它目前具備的是第一方採用：包括 Vercel、Nuxt、Atlassian 和 Resend 在內的 7 家公司，已在公開 URL 發布 DESIGN.md；此外，社群也整理了 73 份從公開網站反向工程而來的版本。您現在即可將它視為一項慣例並自由擴充，因為沒有任何機制會驗證您的區段名稱。

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

對小型儲存庫而言，是的。讓 agent 確實讀取一個檔案，優於提供兩個檔案卻有一個被忽略。當 AGENTS.md 不再容易快速瀏覽，或您發現兩個部分的變更頻率不同時，再將它們拆開。AGENTS.md 會在建置流程變更時更新。DESIGN.md 會在設計決策變更時更新，而這種情況較少見，影響也更大。拆分後，請在 AGENTS.md 加入一行，告知 agent 在編輯程式碼前讀取 DESIGN.md，因為並非每個工具都會載入根目錄中的所有 markdown 檔案。

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

ADR（架構決策紀錄）是針對單一決策建立的日期化紀錄，而健康的專案會在某個資料夾中累積數十份 ADR。這是一段歷史，而載入歷史的成本很高，因為 agent 必須讀取全部紀錄，才能判斷哪些內容仍然有效。DESIGN.md 描述目前狀態，設計目的是在每項工作中完整讀取。如果您已經撰寫 ADR，請保留兩者。ADR 說明做了什麼決策以及何時做出。DESIGN.md 說明今天仍然成立的內容，也是您應該指示 agent 讀取的檔案。

DESIGN.md 應該多長？

長度應足以在每次互動中載入，且不會造成負擔。截至 2026 年 8 月，已發布的範例較長，因為它們描述完整的視覺語言：Nuxt 檔案約 2,100 字，Vercel 檔案約 6,500 字。後端服務通常需要少得多。請先從一頁開始，只有當 agent 犯下原本一句話即可避免的錯誤時，才增加內容。長度不是衡量標準。每一行都應該描述 agent 否則會弄錯的事項。