用户级与项目级两条来源、向上发现与 override 优先级、32KB 预算、缓存刷新,以及规则为何不能代替沙箱权限。
同样修空字符串测试、还要保持旧接口——换个仓库,能做的事和要求就不一样:测试命令、目录约定、生成文件不能乱改……每次口头重说很容易漏。第五章讲项目规则:AGENTS.md 从哪找到、怎么进模型请求、没按要求做时查哪里。
规则解决什么问题
用户目标 + 项目长期约定 + 实际读到的代码,共同影响修改方案。规则不能证明测试已通过,但能告诉 Agent 怎么收集证据、怎么检查。把长期有效要求放进文件,团队就有可一起维护的地方——前提是文件能被找到,内容能正常进请求。
两条来源:用户级 vs 项目级
- 用户级指令:由宿主提供,常见从 Codex 配置目录读规则;其他宿主也可把提供者交给核心——不能把所有来源都当成仓库里同一个文件。
- 项目规则:按当前工作环境与工作目录确定要检查哪些目录,再读候选文件;两边内容之后组合。还支持线程级指令,本章先把前两条讲清。
排错时:个人偏好没配好 → 查宿主用户级;某包测试约定没进来 → 查项目发现路径。项目处于不可信状态时,这份实现可能跳过项目规则,宿主用户指令仍可保留。
如何发现:向上找根,再沿路径读
默认常以 .git 等为根标记(也可配置)。找到仓库根后,从根到当前工作目录每一层都可贡献一份规则;不在这条路径上的旁支目录不会被这次自动发现扫进来。不会为了找 AGENTS.md 把整个仓库所有子目录扫一遍。若向上找不到根,可能只检查当前目录。排查「规则有没有加载」时,先确定实际工作目录与根标记,往往比反复改文件内容更有用。
每个目录读哪个文件
顺序大致是:先 AGENTS.override.md(或类似 override 名),再 AGENTS.md,再配置的备用文件名。选择单位是目录:前一个候选存在且是文件就选中它,不会把同目录几份内容全部叠在一起。override 适合替换这一层的常规规则,不是「往 AGENTS.md 后面加几句」这么简单。
坑:程序先按「文件是否存在」做选择,再读内容;一个空白的 override 仍会挡住同层 AGENTS.md,读到空白后也不会回头选下一个名字。想让后面候选接管,先检查前面文件是否还存在。备用名需显式配置,不是放个 README 就会自动当项目规则。
总字节预算(默认约 32KB)
按仓库根 → 工作目录顺序读写;根先占额度,再外层包,再到当前目录。某文件超过剩余额度就只保留预算内部分;额度耗尽后后面的项目文件不再加入。于是:越靠近当前包的规则排在后面,反而可能装不全。技巧是入口规则写短,留下必须遵守的要求与必要引用。这份预算管的是项目发现内容,不会顺手吃掉整份宿主用户指令额度。
从外到内组合,不是可自动求值的规则表
根放全仓约定,包目录放本包要求(如根写「保持公开接口兼容」,包写「改完跑本包测试」)。源码按从外到内组合文本,并不把每句自然语言解析成可自动求值的规则表;也不能简单理解成「最后一句盖掉前面所有用户要求」——用户当前明确限制要严格保留。任务进入更深目录时,还要确认那里适用规则是否已取得;规则适用范围与启动时自动发现了哪些文件,是两个要分别检查的问题。
改了磁盘上的文件,下次请求一定看到吗?
不一定。负责管理规则的组件会在启动与请求边界刷新指令快照,但项目侧有缓存:当前环境选择或项目信任状态等变化后才会重新走项目发现;条件没变可沿用已加载内容。宿主用户级/线程级提供者在请求边界也会被调用,且可有自己的缓存。临时改规则后,不能只看磁盘已保存就断定运行中任务已采用新版本——要核对当前加载来源与内容。普通工具读了一个文件 ≠ 项目规则快照已重建。
规则影响决策,不替代执行层权限
规则组合成指令文本进入上下文。写明「不要直接改生成文件」有助于选对源文件;写清测试入口能少猜命令。但这些句子没有变成 OS 访问控制——审批、沙箱、文件权限在真正执行工具时另有处理。必须禁止的操作应在执行机制落实,不能只靠 AGENTS.md 一句「禁止」。反过来,工具被拒绝也不能只在项目规则里找原因。
怎么写才好用
「保证代码质量」没错,但模型难判断具体步骤。更具体的例子:修改某输入处理前先读相关测试;保持已有公开接口签名与约定行为;为空字符串补用例;按本包目录约定跑实际可用的测试命令;没跑检查前要明确说清楚。命令必须是仓库真实入口。大量背景资料可放到专门文档再引用,别把一切塞进自动加载入口。
没按约定跑测试时怎么查
- 加载:实际 cwd、项目根、信任状态;是否被同层 override 挡住;前面规则是否占完预算;刚改文件时快照是否仍旧;
- 内容:要求是否进了请求、是否含糊、是否冲突;
- 执行:有没有发起测试、命令被拒、执行失败,还是结果还没拿到。
修法各不相同:有时改发现路径,有时改规则写法,有时补跑检查或解释受限原因。规则文件与实际执行证据要放在一起看。
下一期拆权限与沙箱:审批、文件范围与网络策略如何汇到真正执行。