DESIGN.md是什么？如何补充AGENTS.md的设计决策

DESIGN.md 的作用，以及 AGENTS.md 未涵盖的内容

DESIGN.md 是仓库根目录中的一个 Markdown 文件，用于说明代码为何采用当前结构。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 上，因此进程内映射更快，也少维护一个需要持续运行的守护进程。当存在第二台应用服务器时再重新评估。” 没有这段说明，当代理被要求提高缓存性能时，它会添加 Redis，而且这样做是合理的：因为你从未告知它这一约束。这一节的价值足以支撑整个文件。

边界。 指出小修改会造成大范围影响的位置。例如数据库架构、客户已经用于脚本调用的公共路由前缀、应用启动前部署流程读取的配置文件，以及假定只运行一个副本的 cron 条目。列出这些边界，并说明修改每一项的代价。

术语。 如果代码使用 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行猜测内容的文件没有用。

有些工具会加载仓库根目录中的所有 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 计数器介绍了这些预算的去向。

当 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 负责维护。截至 August 2026，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 应该有多长？

应短到每轮都能加载，而不会让您后悔。已发布的示例较长，因为它们规定了完整的视觉语言：截至 August 2026，Nuxt 文件约有 2,100 个词，Vercel 文件约有 6,500 个词。后端服务通常需要少得多。可以先从一页开始。只有当代理犯了本可由一句话避免的错误时，才增加内容。长度不是衡量标准。每一行都应描述代理原本可能犯错的一项内容。