结论先行:AGENTS.md 的价值不在「写了多少规则」,而在每条规则可判定违反。规则写得再全,模型遵守不了、或者你自己在第 30 次对话后忘了为什么写它,就是负资产。

为什么需要行为宪法

AI 编码助手每个会话都是失忆重启。你调教出来的偏好——汇报要结论先行、测试红着不许说完成、高峰期别跑批量任务——如果不落成文件,每次都要重新教一遍。我在没有宪法的时期吃过亏:同一个项目,昨天刚纠正过的汇报格式,今天新会话又退回流水账;上个会话说好不装新依赖,这个会话顺手就给装上了。教训不是模型不听话,是行为约定没有持久化的载体——靠对话调教出来的习惯,寿命只有当前这个会话。

AGENTS.md 就是这个载体。它跨会话生效、随目录走,对模型来说相当于"这个用户反复强调过的事"。把口头调教升级成文件,才有资格谈稳定协作。

另外要区分两份文件:全局的 ~/.zcode/AGENTS.md 管跨项目通用的工作方式与红线;项目根的 AGENTS.md 管这个仓库特有的约定——构建命令、目录结构、领域红线。两份都要薄,各自只写该自己管的事,写串了就会在冲突裁决时互相扯皮。

还有一个常见误用:把 AGENTS.md 当知识库塞。领域知识、操作流程、项目事实都不是宪法的内容——它们分别属于记忆层和流程层。宪法只回答一个问题:在这个工作台前,你该怎么行事。内容归属错了,宪法会越吹越胖,真正要紧的红线反而被稀释。

分层:硬约束与软约定

我的人口结构分两层:

  • 硬约束(红线):不擅自 commit/push、不装新依赖、不删看不懂的文件、测试不许作假。违反 = 事故。
  • 软约定(效率习惯):结论先行、不谄媚、大文件 grep 后 offset/limit 读。违反 = 难受但不致命。

这个区分的价值在于例外处理:软约定允许例外,但要求例外时用一句话说明原因,不许默默违反。没有这个口子,模型会在不合时宜的场合僵硬执行;没有这个约束,软约定又会在第三次例外后名存实亡。

红线尽量写成负面清单——“不做 X"比"要做 Y"更容易判定违反。正面要求天然模糊,怎么算"做好"没有边界;负面清单的违反事件是离散的:push 了就是 push 了,装了就是装了。我后来新增红线时都先问一句:这条能不能写成"不做 X"的形式,不能就继续打磨到能。

维度硬约束(红线)软约定(效率习惯)
定位防事故提效率
典型例子不擅自 commit/push、不装新依赖结论先行、大文件局部读
违反后果不可逆损失或信任崩塌输出变差,可挽回
例外政策不允许例外允许,但须一句话说明原因
写法要求每条可判定违反描述行为倾向,可观察
审查节奏季度审,只减不增反复违反就改写或删除

冲突裁决链

规则一定会打架。我定了一条明确的裁决链:

本轮明确指令 > 项目根 AGENTS.md > 全局 AGENTS.md

本轮指令最高优先,这保证临时需求永远能覆盖历史约定;项目级覆盖全局,保证不同仓库可以有个性。

这条链解决过我的真实纠结:全局宪法写了"高峰期不跑批量任务”,某天下午线上出问题需要批量拉日志排查。按裁决链,“先抢修"这个本轮指令覆盖全局软约定——模型说明了一句原因就执行了。如果没有裁决链,这种场景要么僵硬拒绝执行耽误事,要么静默违反破窗;有了裁决链,例外是受控的、留痕的。

裁决链本身只有一行,但每一级的存在都有理由:本轮指令最高,因为对话里的明确要求代表最新意图;项目级居中,因为仓库个性需要被保留;全局兜底,因为跨项目的通用习惯不该在每个仓库里重复维护。行数越少,被引用时越没有歧义。

一份可直接抄走的骨架

# AGENTS.md

## 0. 规则层级
- 冲突裁决:本轮明确指令 > 项目根 AGENTS.md > 本文件
- 硬约束不允许例外;软约定例外时用一句话说明原因

## 1. 硬约束(红线)
- 不擅自 git commit / git push
- 不安装新依赖,确需安装先征询
- 不删除看不懂用途的文件,先问
- 测试与验证不许作假(禁 mock 被测逻辑、禁注释断言、禁跳过用例)

## 2. 效率习惯(软约定)
- 汇报结论先行,附最小有效信息
- 大文件先 grep 定位,再 offset/limit 局部读
- 不输出与任务无关的延伸分析

## 3. 维护
- 每季度清一次:没人触发过的规则请出去
- 某条规则被反复违反 → 改写或删除,不叠加新禁令

骨架的关键是第 0 节:把裁决链写进文件本身,模型遇到规则打架时才有依据可循,而不是现场发挥。其次是第 3 节:把"宪法会腐烂"这件事写进宪法,审查动作才不会被遗忘。

宁少而硬:元规则

最重要的一条元规则:某条软约定被反复违反,说明这条写法有问题——改写或删掉它,不要用叠加新禁令的方式打补丁。规则是给模型读的,不是给人看的:禁令越叠越多,每条的遵守概率反而被稀释。每季度清一次,把没人触发过的规则请出去。

“可判定违反"值得单独强调。“写好代码"不是规则,是愿望;“测试红着不许报完成"才是规则——违反与否一眼可判。我清理规则时有个粗略检验:让一个没读过上下文的人拿着这条规则看一次输出,他能不能立刻说出违反了没有。说不出来,就重写成能说出来的形式。

遵守概率被稀释的机制值得说透:模型对每条指令的注意力是有限的资源,五十条规则和十条规则相比,单条获得的注意力大约按比例缩水。叠禁令的人以为在加固,实际是在分摊——第十条同类禁令生效的前提是模型还记得前九条,而它往往只记得最近几条。这也是"软约定被反复违反"的常见真相:不是模型变笨了,是规则池涨了。

宪法的最终形态:硬约束不到 10 条,软约定按场景分组,全文一个屏幕读完。

真实场景

说一个规则膨胀的教训。早期我把所有想到的约定都往全局文件里堆,一度堆到四十多条,其中"汇报不要啰嗦"和"该完整处完整"长期打架——模型时而过度精简弄丢关键信息,时而为了完整把无关细节全铺开。我起初的做法是给两条规则各补三条解释,结果文件更胖、行为更飘,哪条都没稳住。真正起作用的做法是把两条一起删掉,重写成一条:“汇报长度匹配任务重量;关键信息不省略导致返工”。矛盾消失了,遵守也稳定了。当时权衡过要不要保留两条各自的细节,最后选择信任"少而硬”,事后看是对的。做得不够好的地方:我在第一次发现两条打架时就该动手做减法,打补丁的那几轮不只是没用,还在训练我"规则可以靠堆"的错误直觉——这个直觉比几条废规则更难清掉。

检查清单

  • 每条规则都能回答"怎么判定违反了”
  • 硬约束与软约定分节存放,红线不超过 10 条
  • 文件开头写明冲突裁决链,本轮指令最高
  • 软约定有例外口子,且要求说明原因
  • 没有两条规则对同一行为提出相反要求
  • 最近一个季度没人触发过的规则已删除
  • 全文一个屏幕读完,没有第二条同类禁令