结论先说
- 模型「走捷径」本质上是在目标未封口时优先追求命令返回绿灯。如果提示词只说「修好报错让测试通过」,未明确禁止改动测试和静态检查配置,模型可能用删除断言或关闭规则来快速达成表面成功。
- 用
AGENTS.md把团队底线固化在仓库里,每次会话自动生效。按官方文档,Codex 会先读取全局~/.codex/AGENTS.md,再从项目根目录逐级向下拼接到当前目录的AGENTS.md(存在AGENTS.override.md时同目录优先覆盖),整体合并默认上限为32 KiB(完整规则见 /guides/codex-agents-md-how-it-reads)。 - 写护栏要写「禁止动作 + 替代动作」,而不是空泛口号。把「代码质量要高」改成「严禁删除或
.skip已有测试;若确认为测试预期过期,必须先列出理由并暂停等待人工确认」。 AGENTS.md只是软护栏,必须配合沙箱、审批模式与 Git 检查形成硬闭环。高风险目录与命令应交由沙箱审批把关(配置见 /guides/codex-permissions-sandbox),提交前用git diff --stat与/review二次核验。- 团队持续磨合规则与多轮代码审查需关注套餐配额。若国内支付不便或需要更高并发与使用上限,可在本站自助选择 ChatGPT Plus 充值 或 ChatGPT Pro 充值,多人研发团队也可对接 ChatGPT Business 团队定制。

图:本站结合 OpenAI Codex 官方文档:AGENTS.md 与工程实践整理的示意图
本文根据 OpenAI Codex 官方文档《Custom instructions with AGENTS.md》《Advanced configuration》《Codex CLI》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 遇到 Codex 为了让测试变绿而直接删减用例、注释断言或硬编码特判入参的开发者;
- 苦恼于模型顺手添加
@ts-ignore、eslint-disable、重排无关文件代码导致 PR 差异难以审查的工程师; - 希望在团队仓库根目录沉淀一份简洁、可执行、不易被截断的
AGENTS.md规范的研发负责人。
一、先弄清 Codex 怎么读 AGENTS.md,避免写了不生效
很多开发者把上千行公司编码规范直接粘进 AGENTS.md,结果模型依然我行我素,通常有两个原因:一是文件放错层级或被同目录的 AGENTS.override.md 覆盖;二是各级文件拼接总字节数超过官方默认上限 32 KiB(对应 config.toml 中的 project_doc_max_bytes),导致末尾关键约束被截断。
此外,动态记忆(Memories)与 AGENTS.md 的职责不同:个人偏好可以放记忆,但涉及代码安全、测试保护与提交底线的硬规矩,务必显式写进受版本控制的仓库 AGENTS.md(两者对比见 /guides/codex-memories-how-to-use-vs-agents-md)。本站建议将根目录 AGENTS.md 控制在 80 到 150 行以内,把最关键的 5 条禁令置顶。
二、5 条可直接复制的 AGENTS.md 硬约束护栏写法
下面这份模板针对「删测试、硬编码绕校验、关检查、改无关文件、虚报结果」五类高频痛点编写,可直接放入项目根目录的 AGENTS.md 中按技术栈微调:
markdown
# Repository Guardrails for Codex
## 1. 测试保护护栏(严禁伪造绿灯)
- 严禁删除、注释、`.skip`、`.only` 或放宽任何已有单元测试、集成测试与 E2E 断言。
- 严禁针对测试用例里的特定输入值编写硬编码 `if` 分支来凑通过。
- 如果判断某个旧测试确实已与新需求冲突,必须先停止修改测试文件,列出冲突点与建议,等待人工明确批准后再改。
## 2. 类型与静态检查护栏(严禁掩盖报错)
- 严禁新增 `@ts-ignore`、`@ts-expect-error`、`as any`、`eslint-disable`、`# type: ignore` 或 `# noqa` 来绕过编译器和 Linter 报错。
- 严禁修改 `tsconfig.json`、`eslint.config.*`、`pyproject.toml` 中的严格校验级别来消除告警。
## 3. 最小改动范围护栏(禁止顺手改无关文件)
- 仅修改与当前任务直接相关的文件和代码行。
- 严禁对未涉及的旧文件执行全文件格式化、重排 import、重命名公共导出符号或「顺手重构」。
- 交付前先自查 `git diff --stat`,若出现无关文件改动必须主动还原。
## 4. 依赖、迁移与敏感文件护栏
- 未经明确授权,禁止安装或升级第三方依赖、修改锁文件、改动数据库迁移历史脚本,以及读写 `.env`、密钥或鉴权配置。
- 涉及破坏性命令(如删除目录、强制重置 Git 历史、清空数据库表)一律先说明影响并等待确认。
## 5. 真实执行与如实汇报护栏
- 每次修改完成后,必须实际运行对应校验命令(如 `npm run typecheck`、`npm test`、`ruff check`)。
- 若因沙箱限制或环境缺失无法运行验证命令,必须在答复开头明确写明「未运行校验及原因」,严禁在未执行时声称测试已通过。
订阅与账号准备提示:在大型仓库里执行多轮规则校验、单测回归与/review复核会稳定占用模型额度(额度规则见 /guides/codex-usage-limits)。重度编码用户可在本站升级 ChatGPT Pro 5x iOS 可覆盖档 或 ChatGPT Pro 5x 信用卡不可覆盖档;新账号首次开通 Codex 若遇到手机验证卡住,可参考 Codex 注册手机验证服务。
三、光靠 AGENTS.md 不够:叠加三道硬验收防线
AGENTS.md 属于提示词级约束,在超长对话上下文衰减时仍存在偶发越界可能。本站建议再叠加三道不依赖模型自觉性的工程闸门:
- 开启合理审批与沙箱模式:日常开发保持在工作区可写但敏感命令需审批的模式,禁止无脑常开全放行权限。
- 用只读命令与
/review做交付前审 diff:每次任务结束执行git diff --name-status查看是否触碰了tests/、配置文件或锁文件,再运行/review专门检查是否存在硬编码或弱化断言(详见 /guides/codex-code-review)。 - 在 Git 钩子与 CI 中卡死禁用注释:在 CI 流水线里用规则检查新增 diff 是否引入了
eslint-disable、@ts-ignore或.skip(,一旦命中直接拒绝合并。

图:本站结合工程治理经验整理的检查清单示意图
常见问题
问:为什么我改了 AGENTS.md,正在进行的 Codex 命令行会话里还是没按新规矩执行?
答:按官方文档说明,Codex 是在启动任务或新建会话时一次性读取并构建指令链的,中途修改 AGENTS.md 不会自动热更新到旧会话。改完规则后应退出当前会话并重新启动,或者新开一条独立对话验证。
问:子目录前端和后端规范不一样,全写进根目录 AGENTS.md 会不会冲突或太长?
答:不会。Codex 支持从仓库根逐级向下读取目录中的 AGENTS.md,后面的目录规则可补充或细化前面的要求。建议把通用 5 条护栏放在仓库根,把前端 Tailwind 或后端 SQL 专属细则拆分到 web/AGENTS.md 与 server/AGENTS.md,既清晰又不容易触发 32 KiB 上限。
问:国内缺少外币信用卡,或者研发团队想统一采购并开票报销,怎么开通 ChatGPT / Codex 订阅?
答:可在站内 AI 会员充值总览 直接选购 ChatGPT Plus、ChatGPT Plus 自助卡密 或高配额 ChatGPT Pro,支持支付宝、微信支付与 AlipayHK,提供卡密自助兑换(无需交出账号密码)与客服协助,并支持开具增值税发票;多人研发团队也可咨询 Business 团队席位定制。实时价格以页面显示为准,售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
- Codex 怎么读 AGENTS.md:全局和项目的读取顺序与 32 KiB 上限排查
- Codex 动态记忆(Memories)和 AGENTS.md 的区别与用法
- Codex 权限与沙箱设置:审批模式与安全边界
- Codex 代码审查(codex review)怎么用
参考资料
- OpenAI Codex 官方文档:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
- OpenAI Codex 官方文档:Advanced configuration — https://learn.chatgpt.com/docs/config-file/config-advanced
- OpenAI Codex 官方文档:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方文档:Command line options — https://learn.chatgpt.com/docs/developer-commands
0 条评论
还没有评论,来抢沙发~