AI Agent / 系统课时
组织分层项目指令
组织分层项目指令
当一个仓库同时包含前端、后端、基础设施等模块时,把所有要求塞进一份根级说明会让规则彼此干扰。本篇用 AGENTS.md 与目录作用域组织 Codex 项目指令,让仓库共识向下继承,同时让子模块只获得真正适用的测试、风格和安全约束。
学习目标
- 理解 Codex 如何从全局、仓库根目录到当前工作目录发现并合并项目指令
- 能为仓库级共识与子目录专属规则选择合适的
AGENTS.md或AGENTS.override.md - 能判断冲突规则最终由哪一层生效,并避免把指令文件写成冗长知识库
分层指令解决什么问题
Codex 启动一次任务或新的 TUI 会话时,会构建一条项目指令链:先读取 Codex Home 中的全局指令,再从项目根目录沿路径走到当前工作目录;同一路径中越靠近当前目录的规则越晚加入,因此能覆盖更宽泛的上层约束。默认项目指令总量达到 project_doc_max_bytes 限制后会停止继续加入,该值默认是 32 KiB。:contentReference[oaicite:0]{index=0}
这意味着“规则放在哪里”本身就是配置的一部分。仓库根目录适合放所有模块都成立的约束,例如通用测试入口、依赖管理原则和提交前检查;支付、移动端或基础设施目录则只放该模块特有的命令、生成文件边界和安全要求。

设计仓库级与模块级规则
下面建立一个最小示例:根级规则要求所有改动先做基础检查,支付模块再追加自己的专项测试和生成文件边界。这里使用普通 AGENTS.md 做层叠,不需要覆盖同目录中的另一份指令文件。
mkdir -p services/payments
# 根级规则只写整个仓库都成立的约束
cat > AGENTS.md <<'EOF'
# Repository instructions
- Before finishing code changes, run `npm run lint`.
- Keep public APIs backward compatible unless the task explicitly changes them.
EOF
# 子目录规则只补充 payments 模块的专属要求
cat > services/payments/AGENTS.md <<'EOF'
# Payments instructions
- For changes in this directory, run `npm run test:payments`.
- Do not edit files under `services/payments/generated/` by hand.
EOF
printf '%s\n' AGENTS.md services/payments/AGENTS.md预期输出:
AGENTS.md
services/payments/AGENTS.md当 Codex 的当前工作目录位于 services/payments 时,这两份项目指令都会进入作用链;若只从仓库根目录启动并停留在根目录,Codex 不会继续向未进入的子目录搜索,因此子模块规则不会凭空作用于整个仓库。
判断覆盖关系
在同一个目录里,Codex 按 AGENTS.override.md、AGENTS.md、配置的备用文件名依次检查,并且每个目录最多选择一个非空文件。存在 AGENTS.override.md 时,同目录的 AGENTS.md 不会同时加入;它更适合临时、强制或环境特定的替代规则,而不是日常层叠。:contentReference[oaicite:1]{index=1}
跨目录时则遵循“从宽到窄”的原则。根级写“修改 JavaScript 后运行全仓 lint”,子目录可以进一步写“支付模块还必须运行专项测试”;如果两层对同一事项给出冲突指令,应让更深目录表达更具体的例外,并把原因写清楚,避免出现两个都像绝对规则、却没有适用条件的句子。
让指令保持高信号
好的项目指令应回答“在这个范围内,Codex 做事时必须知道什么”,而不是复制整个开发手册。优先写可执行约束:使用哪个测试命令、哪些目录禁止手改、公共接口变化要满足什么兼容要求、生成代码由哪个命令产生。
对于架构解释、领域背景和长篇设计文档,可以在 AGENTS.md 中只给出入口路径,让 Codex 按任务需要再读取对应文档。这样既减少长期上下文占用,也降低规则过期后误导任务的概率。OpenAI 的工程实践同样强调让短小的 AGENTS.md 更像“地图”,而不是把所有知识塞进单一说明文件。:contentReference[oaicite:2]{index=2}
落地时先把真正全局的约束留在根目录,再把模块特例移动到最靠近代码的目录;只有需要替换同目录规则时才引入 AGENTS.override.md。最终目标不是让 Codex“看到更多规则”,而是让它在当前工作范围内只看到清晰、无冲突、可验证的规则。