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.

截至 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 个文件。每个文件都采用相同的九个章节格式，因此可以将其中一个文件提供给代理，让它生成风格相近的页面。这些文件很有用，但仍然只是推测结果。相关公司没有审核过它们。

第一方文件不同，因为它是源文件，而不是对最终输出的解读。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 上，因此进程内映射更快，也少维护一个需要持续运行的 daemon。等存在第二台应用服务器时再重新评估。” 没有这段说明时，如果要求代理提升缓存速度，它添加 Redis 是合理的：因为你从未告知它这一约束。整份文件的价值主要就在这一节。

边界。 说明哪些位置的小改动会产生大范围影响。例如数据库 schema、客户已经通过脚本调用的公共路由前缀、应用启动前由部署流程读取的配置文件，以及假定只运行一个副本的 cron 条目。列出这些位置，并说明修改每一项的代价。如果代理还可以访问开放 Web，例如通过 配置为其搜索后端的自托管 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.

填写今天可以凭记忆写出的两个部分：不变量和已否决的替代方案，其余部分保留为标题。包含四行真实内容的文件是有效的。包含四十行猜测内容的文件则不是。

有些工具会加载仓库根目录中的所有 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() 写入，因为直接写入会跳过审计日志。如果它打开数据库连接并直接写入，原因只有两种：要么根本没有读取该文件，要么不变量的表述过于宽泛，无法形成明确约束。

还要关注 token 数量，因为每轮都会加载该文件。如果添加 DESIGN.md 后上下文用量明显增加，但回答没有变好，说明文件中包含了 agent 已经掌握的内容。阅读 Claude Code 中的 token 计数器可以查看这些 token 的具体去向。

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

从你们经常争论的决策开始

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

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 上发布这类文件；一个社区集合还收录了从公开网站逆向整理出的另外 73 份文件。您可以立即将其作为约定采用并自由扩展，因为没有任何机制会验证您的章节名称。

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

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

DESIGN.md 与架构决策记录有何不同？

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

DESIGN.md 应有多长？

应短到可以在每次交互中加载，而不会造成负担。公开示例较长，因为它们描述了完整的视觉语言：截至 2026 年 8 月，Nuxt 文件约有 2,100 个单词，Vercel 文件约有 6,500 个单词。后端服务通常需要少得多。先从一页开始，只有当代理犯下本可由一句话避免的错误时，才继续扩展。长度不是衡量标准。每一行都应说明代理本来可能会弄错的一件事。