用 AGENTS.md 约束 Codex：我先把允许修改的文件写清楚

不会安装 Codex CLI？先看上一篇 Windows 一键安装教程：https://blog.csdn.net/qq_43761275/article/details/163592885?spm=1011.2415.3001.5331

让 Codex 修一个小问题并不难，难的是提前说清楚：它到底可以改哪些文件？

如果任务只写“把测试修好”，修改实现、放宽测试、调整 package.json 都可能让测试变绿。结果看起来一样，改动范围却完全不同。这次我把边界写进项目自己的 AGENTS.md，再用失败基线、文件哈希、git diff 和测试退出码做验收。

本文已经实际验证项目状态和失败测试。Codex 的 workspace-write 修改还没有完成，因此不会提前写成“已经遵守规则并修复成功”。

1. 示例项目只有 5 个文件

项目名是 codex-agents-guard-demo：

codes/codex-agents-guard-demo/
├── AGENTS.md
├── README.md
├── package.json
├── src/format.js
└── test/format.test.js

图 1：真实项目文件列表。后续如果出现额外文件，也要纳入检查。

当前函数只返回标题：

export function formatBook(book) {
  return book.title;
}

测试要求返回 Clean Code (2008)。项目没有第三方依赖，测试直接使用 Node.js 内置的 node:test。

2. AGENTS.md 只写可检查的边界

# 本项目规则

- 只允许修改 `src/format.js`。
- 不允许修改 `test/`、`README.md`、`package.json` 和本文件。
- 不增加依赖。
- 修改后运行 `npm test`。
- 不读取或写入 API Key、Cookie、Authorization 或用户私密数据。

图 2：项目中实际读取到的规则。

这些规则都能逐项验收。“只允许修改一个文件”可以看 git diff --name-only；“不增加依赖”可以检查 package.json 和新增文件；“运行测试”则要保存完整输出和退出码。

AGENTS.md 也不等于操作系统权限。workspace-write 控制工具在沙箱层面能否写工作区，项目规则再把允许范围缩小到 src/format.js。两层都配置后，最终仍要看实际 diff。

3. 先固定失败基线

Set-Location .\codes\codex-agents-guard-demo
npm test
$LASTEXITCODE

真实结果如下：

测试总数：1
通过：0
失败：1
实际值：Clean Code
期望值：Clean Code (2008)
退出码：1

图 3：后续修复必须对应同一个输入和断言。

测试前还应运行：

git status --short -- .

如果示例目录本来就有修改，要先记录原有状态，否则任务结束后无法区分哪些 diff 是本次产生的。

4. 给受保护文件保存修改前哈希

Get-FileHash AGENTS.md,README.md,package.json,test\format.test.js `
  -Algorithm SHA256

图 4：4 个禁止修改文件的真实修改前哈希。

实际修改结束后再次计算。如果哈希逐项一致，可以证明这些文件内容没有变化。哈希不替代 diff：哈希适合快速确认“有没有变”，diff 适合继续判断“具体变了什么”。

5. 给 Codex 的任务也重复边界

请先读取当前目录的 AGENTS.md，并说明你将遵守的文件范围。

修复 formatBook，让它返回“标题 (年份)”格式。
只允许修改 src/format.js。
不要修改测试、README、package.json 或 AGENTS.md，不要增加依赖。
完成后运行 npm test，并列出实际修改文件和测试退出码。

项目规则负责长期边界，任务文本负责这一次的目标。两处都写，回看记录时不需要猜测当时的验收口径。

6. 验收不能只看测试变绿

任务结束后按顺序执行：

git status --short -- .
git diff --name-only -- .
git diff -- .\src\format.js
git diff --check -- .
npm test
$LASTEXITCODE

合格结果至少满足：

只修改 src/format.js
没有新增依赖
实现没有硬编码 Clean Code (2008)
受保护文件哈希保持一致
git diff --check 无报错
npm test 全部通过，退出码为 0

如果测试、README、package.json 或 AGENTS.md 出现在 diff 中，应先停下来检查。测试通过不能抵消范围越界。

7. 当前验证状态

已经完成：项目文件核对、规则截图、受保护文件哈希和失败基线。基线仍为 1 项测试、0 通过、1 失败，退出码 1。

尚未完成：Codex workspace-write 实际修改、修改后文件列表、修复后测试和退出码。后续只补真实执行结果，不用示例输出代替。

llapi.org 配置提醒

需要给 Codex 配置模型服务时，可以到 llapi.org 查看当前申请入口、Base URL 和服务规则。字段以当前 Codex CLI 和官网说明为准，本文不承诺模型效果、额度、价格或稳定性。

文章和截图只使用 <YOUR_LLAPI_API_KEY> 占位符。真实 Key、Cookie、Authorization、完整配置文件和用户私密数据不要放进源码、截图或 Git 历史。

示例代码地址：https://gitee.com/heihei_66/codex-demo