现在随便打开一篇讲 Agent 工作流的文章，都逃不开同一个建议：在仓库里放一份 DESIGN.md，给模型当上下文。我也信了，认真写了一个月。结论先说：大部分没用，除非你写对。
1. 它是怎么变成废纸的
第一周，我写得挺虔诚：项目结构、每个目录的职责、模块之间怎么调用，配图带码。
第二周，改了两个 feature，文档和现实开始对不上。
第三周，最魔幻的事情发生了：agent 开始在「文档说 A、代码是 B」之间做选择题。它有时信文档，照着一个不存在的结构写；有时信代码，把文档当空气。反正每次输的都是文档。
一个月下来我明白了：描述「是什么」的文档必死。因为代码本身就是「是什么」的最准描述，而现在的模型读代码比你读得快，也比你想得准。写一份说明书去抢代码的活，就是用自己的短处打别人的长处。
2. 什么样的版本活得下来
活下来的版本只写代码里「看不出来」的东西：
- 为什么当年否掉了方案 X（不写的话，agent 半年后会热情地帮你重新发明它）；
- 哪些是不变量，动了会炸（「en.ts 是字典的规范形态，zh.ts 的键必须和它同步」）；
- 历史包袱和雷区（「这个函数别动，上游有 bug」）。
注意到了吗，这三条全是约束，没有一条是描述。
我自己这个 blog 的 AGENTS.md 就是现成的例子：最有用的是那几句「必须」「别动」，而不是前面的项目结构介绍——结构这种事，agent 扫一眼目录就知道了。
还有长度：一屏是上限。超过一屏的 DESIGN.md，本质是一份没人会读完的装饰品。
3. 怎么让它保持新鲜
人不该维护文档，人只该维护判断。两个实测有效的办法：
一是让 agent 自己养：任务收尾的时候让它顺手重写这一页，反正它刚把代码摸了个遍。二是按需生成：开工前让 agent 读完代码现写一份，用完就扔，永远不存在过期的问题。
4. 结尾
所以 DESIGN.md 到底有没有用？有用，但只在它说人话、讲约束、并且永远新鲜的时候。
它最好的形态是一页禁忌清单，而不是一本说明书。代码已经是一本说明书了，别写第二本。