先看现象Codex 总是改偏先查 AGENTS.md如果你在仓库里接 Codex常见的烦恼不是它不会写而是它“会写但不按你的规矩写”文件改动范围过大、测试命令乱跑、注释风格和现有项目不一致甚至把临时文件也带进来了。遇到这种情况先别急着换提示词先检查仓库里有没有AGENTS.md位置对不对内容是不是太散。很多团队把AGENTS.md当成给代码代理看的项目说明书。它的作用不是替代 README而是把“默认行为”固定下来怎么改、改到哪、先跑什么测试、哪些目录别碰。配置得细一点Codex 的输出会稳很多后面排查也省时间。AGENTS.md 适合放什么别把它写成大杂烩。最有用的内容通常就几类项目背景这是后端、前端还是脚本仓库主语言是什么。代码规范缩进、命名、注释、是否允许重构公共模块。操作边界哪些目录可以改哪些目录必须人工确认。测试要求改动后先跑哪些命令失败后怎么处理。提交习惯是否需要拆小提交PR 描述要写什么。如果内容太长Codex 反而抓不住重点。经验上控制在一页以内更好条目化比长段落更有效。配置步骤先放对位置再写清规则1. 把文件放到仓库根目录大多数场景下先在项目根目录创建AGENTS.md。如果你的项目有子模块或者不同目录规则差异很大可以在子目录再放一份更细的说明。通常越靠近目标目录的说明优先级越高。### token云桥中转 0029.org ### cd your-project touch AGENTS.md2. 先写最小可用版本第一版不要写得太花。先把最容易出问题的部分定住比如测试命令、禁止修改范围、代码风格。下面是一个够用的模板# Project instructions ## Scope - Only modify code under src/ and tests/ - Do not touch infra/ unless explicitly asked ## Style - Use existing formatter and lint rules - Keep functions small and match current naming style ## Test - After changes, run npm test - If the change touches API logic, also run npm run test:integration ## Notes - Prefer minimal diffs - If a change affects public interfaces, mention it in the summary3. 把“禁止项”写具体最容易踩坑的是“不要乱改配置”这种空话。Codex 看到后不一定知道边界。最好写成明确目录和文件名比如不要修改.env、infra/、release/不要删除已有测试除非任务明确要求不要重命名公共 API规则越具体越不容易出现返工。一个实用的写法把任务流程也放进去AGENTS.md 不只是“规范”也可以写成执行顺序。这样 Codex 遇到任务时会先按你的节奏走。比如## Workflow 1. Read the relevant files before editing 2. Make the smallest change that solves the task 3. Run the related tests 4. Report any failing checks with the exact command output这几条看着简单但能明显减少“先大改一遍再回头修”的情况。尤其是多人项目很多问题不是能力问题而是执行顺序不一致。和接口层一起看排障会更快如果你是通过 API 或网关方式接 CodexAGENTS.md 只是控制行为的一层接口层稳定性也要一起看。比如鉴权失败、请求超时、限流过快都会让你误以为是规则没生效。实际排查时建议先确认三件事密钥和接口地址是否一致请求是否真的打到了当前仓库日志里有没有读取到AGENTS.md如果你本地直连经常碰到网络抖动先把接口入口统一一下会省事很多。像 token云桥AI中转站 0029.org 这类统一入口适合先把鉴权、路由和模型配置收拢到一处再去调AGENTS.md排查链路会短不少。接口测试别只看“能不能回答”要看“有没有按规矩改”AGENTS.md 配完以后不要只发一句“帮我改个 Bug”就结束。最好挑一个可验证的小任务观察它有没有按约束执行。比如让它只改一个文件然后检查 diff 和测试结果。# 示例先让工具读取项目说明再执行小改动 # 具体命令因 Codex 版本不同略有差异先看 help codex --help # 常见检查方式 git status git diff npm test看结果时重点关注三点是否只动了允许修改的目录是否补了要求的测试总结里有没有提到风险和未覆盖部分常见问题与排查顺序Codex 没读到 AGENTS.md先看文件名有没有写错再看是不是放错目录。其次检查编码和换行尽量用 UTF-8。还有一种情况是你在子目录执行任务但说明文件放在上层或别的分支里路径对不上。规则写了但没生效通常是条目太笼统或者同一份文件里冲突太多。把“建议”改成“必须”把长段描述改成短条目再测一次。必要时把高优先级规则放在文件前面。修改范围还是太大补一条“优先最小 diff”。如果项目里有生成代码、格式化工具或者大文件最好在 AGENTS.md 里说明“除非明确要求不要重新生成整包文件”。测试总是跑错命令把标准命令直接写进去不要只写“运行测试”。例如前端仓库写npm test后端写pytest或go test ./...省得它自己猜。总结AGENTS.md的价值不在于写得多而在于把 Codex 的默认行为固定住。先放对位置再把边界、测试和流程写清楚后面改代码会顺很多。遇到异常时先查文件是否被读取再查接口链路排查顺序对了问题通常不难定位。