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 月抓取的副本仍会让代理使用旧的字号比例，而仓库中不会有任何信息提示你该副本已经过时。

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。等存在第二台应用服务器时再重新评估。”没有这段说明时，如果要求 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 行猜测内容的文件则不是。如果代码仓库包含多个软件包，一个根目录文件无法覆盖所有软件包。此时应采用与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。您可以在一分钟内运行一项检查。

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

还要关注 token 数量，因为该文件每轮都会加载。如果添加 DESIGN.md 后上下文用量上升，但回答没有改善，说明文件中包含 agent 已经掌握的冗余说明。读取 Claude Code 中的 token 计数器介绍了这些 token 的消耗位置。

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

从你最常争论的决策开始

第一个版本只需 20 分钟。打开最近几份 pull request，找到审阅者写下“不是这样，我们这里采用另一种做法”的评论。每条评论都代表一个尚未记录的不变量，也是 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 发布了 DESIGN.md；一个社区集合还收录了从公开网站反向整理出的另外 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 个单词。后端服务通常需要少得多。可以先从 1 页开始。只有当代理犯了一个本可由单句说明避免的错误时，才增加内容。长度不是衡量标准。每一行都应描述代理原本可能弄错的一件事。