规则文件不是文档，是团队的接口

上周三我把仓库根目录那个 743 行的 AGENTS.md 删到 91 行，在 PR 描述里贴了 diff，只写了一句：删掉的每一条我都问过两个人，没人说得出它是从哪来的。

没人反对。这件事本身比删掉的内容更值得警惕——一份七百行的规则，团队里没有一个人为它负责，它却每天都在被模型和新同事当成事实读。

规则文件的死法是被复制，不是被写错

我们最初只有一份约定。后来接入编码助手，多了一个 AGENTS.md；再后来换工具，多了 .cursorrules；再后来我把其中一部分抄进了 onboarding 文档，因为新人不会去翻仓库根目录。

三份文件讲的其实是一件事，但讲法不一样。仓库里那份写「提交信息用英文，首行不超过 72 字符」，onboarding 文档里写「提交信息统一英文」，助手那份写「commit message in English, concise」。看起来一致，实际执行时都往最宽松的方向走——concise 谁说了算？最后没有人被约束。

更常见的一种死法，是把已经不存在的东西写进规则。文件里有一条「新组件放在 src/components/legacy/ 下」，那个目录三个月前就被删了。模型照着这条建议新建了一个 legacy 目录，review 的时候没人觉得不对，因为规则里就是这么写的。

后来我定了一条硬规矩：规则只有一个物理来源，其余位置只能是引用，不能是副本。

repo/
├── RULES.md                  # 唯一来源，正文只在这里
├── AGENTS.md                 # 5 行：定位 + 指向 RULES.md + 禁止复制
├── .cursor/rules/*.mdc       # 每条规则一个文件，frontmatter 用 glob 限定生效范围
└── docs/rules/CHANGELOG.md   # 只记「为什么改」，不重复内容

.mdc 那种一条规则一个文件的做法我很喜欢，倒不是因为工具支持，而是因为它天然把「一条规则」变成了可 diff、可 blame、可单独删除的单位。七百行的单文件里，你没法给某一行标负责人。

一条能被执行的规则，长什么样

我给了个模板，五段，缺一段就打回。

### R-014 新增接口必须带超时
- 场景：调用任何外部 HTTP 服务
- 动作：显式设置 connect 与 read 超时，默认各 2s / 5s
- 反例：`http.Get(url)` 直接调用；只设总超时不分段
- 负责人：@我
- 复查：2026-01 之前确认默认值是否还合适

「场景」和「反例」是这里面最有用的两段。规则写「代码要健壮」是废话，写「调用外部服务时必须设超时，反例是裸 http.Get」才有人能对照检查。反例尤其重要，它把边界说清楚了：设了总超时但没分段的，算不算？心里打问号的时候，review 就有话可说了。

「复查」这行是后来加的。没有失效日期的规则会一直活到自己变成负担。我们现在默认填 6 个月后，到期不是必须改，而是必须有人看一眼说「还有效」。

评审不是投票，是找出它什么时候会害人

规则文件的 PR 和其他 PR 一样走评审，但模板不一样，我只问三件事：

1. 这条规则拦下过什么？新增的规则必须举一个真实发生过的例子，或者一个即将上线的需求。想不出来就先别写。
2. 它和现有哪一条重叠？重叠的话改旧的，不加新的。
3. 谁在什么时候复查？

我还加了个预算：仓库根规则文件不超过 120 行，超了就得先删。这招很粗暴，但有效。规则文件的增长曲线和代码不一样，代码多了可以拆模块，规则多了只会没人读。

评审里我更喜欢听到「这条我不认同」，而不是「可以」。全票通过的规则通常意味着没人真的读过。所以 PR 模板里留了一栏「反例或异议」，空着也行，但会显得这份评审没做完。

还有一个固定动作：每月最后一周的周三，30 分钟，会名就叫「删规则」。不新增、不讨论新需求，只做三件事——删掉没人引用的；给过期的续期或删掉；把被违反过三次以上的规则拎出来，看看是不是规则本身错了。

最后这点值得单说。一条规则如果经常被违反，先别急着加强检查，很可能它写得不合实际。我们有条「所有 PR 不超过 400 行」，实际执行中大批 PR 都在 600 行上下——不是大家不守规矩，是拆分的成本比收益高。后来改成「超过 400 行需要在描述里写一句为什么」，违反率立刻下去了，因为它变成了一个解释成本，而不是一堵硬墙。

还没定论的部分

规则文件到底该给模型读，还是给人读，我到现在没有定论。两者的最优写法不一样：给模型读的要短、要无歧义、最好带可执行的判定；给人读的可以带上下文和「为什么」。现在的做法是同一个文件里既写规则也写一句为什么，靠注释区分优先级，但这大概只是个折中，不是答案。

下周三那个 30 分钟的会我已经建好了，日历上就三个字：删规则。参加的人只有两个，我和上个月新来的同事——他是唯一一个真的从第一行读到第七百行的人，我想听听他觉得哪几条是废话。