Codex AGENTS.md 配置教程-CSDN博客

先看现象：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.md

2. 先写最小可用版本

第一版不要写得太花。先把最容易出问题的部分定住，比如测试命令、禁止修改范围、代码风格。下面是一个够用的模板：

# 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 summary

3. 把“禁止项”写具体

最容易踩坑的是“不要乱改配置”这种空话。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 或网关方式接 Codex，AGENTS.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 的默认行为固定住。先放对位置，再把边界、测试和流程写清楚，后面改代码会顺很多。遇到异常时，先查文件是否被读取，再查接口链路，排查顺序对了，问题通常不难定位。