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 年 10 月，其中列出 11 个：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

这两个文件都是设计系统文档。它们描述产品应有的外观：颜色、字体、间距和动效。不要停留在主题本身，因为真正有用的是文章的结构，而不是主题。

截至 2026 年 10 月 27 日，Nuxt 文件约有 2,000 个单词，其中大部分内容都是附带理由的规则。文件开头说明深色模式是默认主题。它列出品牌绿色 #00DC82，并注明品牌颜色“用于徽标、社交媒体图片和印刷品。不要在 UI 代码中将其作为原始值使用。”接近末尾处，一个标题为 Reject these 的章节包含：

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

截至 2026 年 10 月，Vercel 文件更长，约有 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 个文件；根据其 README 截至 2026 年 10 月 27 日的统计，每个文件都采用相同的九章节格式编写，因此可以将其中一个文件提供给代理，让它生成风格相近的内容。这些文件很有用，但它们仍然只是推测。被审查的公司没有任何一家审阅过这些文件。

第一方文件有所不同，因为它是源文件，而不是对输出结果的解读。Vercel 更改字体比例时，vercel.com/design.md 也会随之变化。3 月抓取的副本会继续让你的代理使用旧比例，而代码库中不会有任何信息告诉你这份副本已经过时。

目前只有 11 个发布者，这个数字仍然很少，代码库也明确说明了这一点：该标准还很新，官方采用正在增加。这两个集合都由 VoltAgent 维护。VoltAgent 是一个开源代理框架，也发布了自己的文件。因此，应将这份列表视为跟踪器，而不是中立的普查结果。它仍然值得关注，原因在于其中的成员。名单中有几家公司，其前端代码最常被其他开发者复制；较新的成员 Ant Design、Microsoft FAST、Juspay 和 Oxide Computer，则是其他团队构建产品所依托的设计系统。它们的文件正逐渐成为 DESIGN.md 实例的实际范例。可以比较 AGENTS.md 的发展路径：agents.md 目前统计显示，已有超过 60,000 个开源项目使用这种格式，其维护工作由 Linux Foundation 旗下的 Agentic AI Foundation 负责。DESIGN.md 也开始走上同一条道路。2026 年 4 月 21 日，Google 将该格式的规范草案开源，并以 google-labs-code/design.md 发布，同时提供令牌模式和一个采用 Apache-2.0 许可证的 CLI。截至 2026 年 10 月，该格式处于 alpha 版本，仍在积极开发中；它由 Google Labs 而不是中立基金会维护，并且描述的是视觉标识，因此没有说明后端文件所需的不变量。面向代理可读文件的约定正在迅速形成，而且其形成过程由顶层推动。

没有用户界面时，DESIGN.md 应该写什么

大多数运行在 VPS 上的软件都没有需要定义的视觉语言。这个文件仍然有价值，因为它与颜色无关。它用于记录约束，否则即使是有经验的编辑者也可能在未察觉的情况下违反这些约束。

不变量。 每条用一句话说明任何编辑后都必须保持不变的内容。“所有写入都必须经过 queue.enqueue()。直接写入数据库会跳过审计日志，而合规导出读取的正是审计日志。” 将原因一并写入的不变量，即使面对未预料到的任务也能继续发挥作用。单独写不变量看起来像偏好，而偏好通常会在优化时被删除。

已拒绝的替代方案。 写明显而易见的方案，以及它为何被放弃。“我们不使用 Redis 进行缓存。服务运行在单台 VPS 上，因此进程内映射更快，而且少维护一个需要保持运行的 daemon。等有第二台应用服务器后再重新评估。” 没有这段说明时，如果要求 agent 提升缓存速度，它添加 Redis 是合理的：因为你从未告知它这一约束。本节的价值足以支撑整个文件。

边界。 说明哪些位置的小改动会造成大范围影响。例如数据库 schema、客户已经通过脚本调用的公共路由前缀、应用启动前部署流程读取的配置文件，以及假设只运行一个副本的 cron 条目。列出这些边界，并说明修改每一项需要付出什么代价。如果 agent 还可以访问开放网络，例如通过 配置为其搜索后端的自托管 SearXNG 实例，这也是值得记录的边界，因为文件应说明哪些抓取的文本可以影响代码，哪些文本只能原样引用给您。

词汇。 如果代码使用 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行猜测内容。如果仓库包含多个软件包，一个根目录文件无法覆盖全部内容。此时可采用与单体仓库中嵌套的 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。但你可以在一分钟内运行一个检查。

给 agent 分配一个会直接触及不变量的任务。例如：“添加一个后台作业，将过期行标记为 expired。”文件是否生效，会在代码出现前体现在回答中：agent 应该告诉你，该作业通过 queue.enqueue() 写入，因为直接写入会跳过审计日志。如果它打开数据库连接并直接写入，原因只有两个：要么根本没有读取该文件，要么不变量的表述过于宽泛，无法据此判断。

还要监控 token 数量，因为每轮都会加载该文件。如果添加 DESIGN.md 后上下文用量上升，但回答质量没有提高，说明文件中包含了 agent 已经掌握的冗余说明。读取 Claude Code 中的 token 计数器可查看这些预算的具体消耗位置。

当 agent 运行在服务器上而不是你的笔记本电脑上时，这一点尤其重要。运行在长期会话中的 agent，例如 使用 tmux 的 VPS 上的 Claude Code 工作区，不会记得昨天的对话。仓库就是它的记忆。你在聊天中解释过但从未提交的内容，会在下一次会话开始时全部丢失。DESIGN.md 用于保存这些说明，使其能够持续存在。

从最常争论的决策开始

第一个版本只需 20 分钟。打开最近几条拉取请求，找到审阅者写过“不要这样，我们这里的做法不同”的请求。每条此类评论都代表一个从未记录下来的不变量，也是代理会重复犯错的地方，而且它犯错的速度和频率都会高于人工操作。只有在文件无法帮助你时才更新它，不要按固定计划更新。如果你还在确定代理应如何融入日常开发流程，可以继续阅读2026 年 AI 代理学习指南。

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 仓库中，采用 Apache-2.0 许可证。截至 October 2026，它处于 alpha 版本，仍在积极开发中，内容描述的是视觉标识，包括颜色、字体、布局和组件。DESIGN.md 也已有第一方采用者：包括 Vercel、Nuxt、Atlassian 和 Resend 在内的 eleven 家公司和项目发布了该文件；截至 October 27, 2026，一个社区集合还从公开网站中提取并收录了 84 份。对于记录不变量和被拒绝方案的后端文件，应将其视为现在即可采用、并可自由扩展的约定，因为没有规范规定这些章节名称。

DESIGN.md 是否应该只是 AGENTS.md 的一个章节？

对于小型仓库，是的。让代理确定会读取一个文件，优于使用两个文件但其中一个被忽略。当 AGENTS.md 不再便于快速浏览，或您发现两部分的变更频率不同，就应将它们拆分。构建流程变化时，AGENTS.md 会变化。决策变化时，DESIGN.md 会变化；这种情况更少见，影响也更大。拆分后，应在 AGENTS.md 中添加一行，告知代理在编辑代码前读取 DESIGN.md，因为并非所有工具都会加载根目录中的每个 markdown 文件。

DESIGN.md 与架构决策记录有什么区别？

ADR（架构决策记录）是针对单项决策的带日期记录，成熟项目通常会在一个目录中积累几十份。这些记录构成历史，而加载历史的成本很高，因为代理必须读取全部记录，才能判断哪些内容仍然有效。DESIGN.md 描述当前状态，设计目标是每次任务都完整读取。如果您已经在编写 ADR，就保留两者。ADR 说明做出了什么决策以及何时做出。DESIGN.md 说明今天哪些内容有效，也是您应当提供给代理的文件。

DESIGN.md 应该有多长？

应短到每次加载都不会造成负担。已发布的示例篇幅较长，因为它们规定了完整的视觉语言：截至 October 2026，Nuxt 文件约有 2,000 个单词，Vercel 文件约有 6,000 个单词。后端服务通常需要少得多。先从一页开始，只有当代理犯了一个本可以由单句说明避免的错误时，才继续扩展。长度不是衡量标准。每一行都应说明代理否则可能出错的事项。