先回答:AGENTS.md 适合放什么
AGENTS.md 用于保存 Codex 处理项目时持续适用的指导,例如目录、构建命令和验收要求。重复任务的方法适合整理成 Skill;外部工具与系统连接交给 MCP。三者可以配合,不能因为装了 MCP 就省去项目说明。
本篇用虚构的 Node.js 小项目说明写法。示例目录和命令不是你项目的事实,使用前先检查 package.json。本文核对了官方说明;没有把示例描述成在读者账户中的运行实录。
第一步:先盘点项目已有规则
在你的项目根目录检查 README、package.json 和已有 AGENTS.md。已有文件应先读后改,避免覆盖团队规则。确认平时使用的包管理器与命令,不要把别的项目的 npm test 直接搬进来。
准备三条项目事实:源码在哪、怎样启动、哪条命令能验证改动。若项目没有测试命令,就写清楚现有人工检查步骤,不要要求执行不存在的命令。
第二步:从这份最小示例开始
下面是一个假设已有 src、public、npm run build、npm run check 的项目示例。它是供人审阅后放进项目的规则,不是要求你在所有仓库强行创建这些目录。
# 项目指导
## 项目结构
- src/:页面与业务逻辑。
- public/:直接发布的静态资源。
- 先阅读 README 和 package.json,再选择验证命令。
## 修改约定
- 沿用现有模块风格,新增依赖前说明用途。
- 开始前检查 git status,保留已有未提交改动。
- 不在日志、示例或提交中写入真实凭据。
## 验收
- 内容与页面变动:npm run build,再运行 npm run check。
- 搜索相关改动:检查空输入、正常结果和无结果状态。
- 汇报实际执行结果,未执行的检查写明原因。规则应该描述稳定事实与可验证行为。“永远写最优雅代码”难以验收;“搜索无结果时保留清除筛选入口”更容易检查。环境会变,命令变更后要同步维护。
第三步:确认加载范围
Codex 可以加载用户级和仓库内不同位置的指导,更接近工作目录的规则有更具体的适用范围。因此遇到“明明写了却没照做”,先确认当前打开的是哪个项目与目录,再看目录中是否有其他指导。
不要仅凭模型说“我已经读了”判断成功。给它一个与规则相关的小任务,让最终改动和验证记录提供证据。
在当前项目把搜索无结果提示改为:没有找到相关教程,试试清除筛选。
先确认适用的项目指导与当前改动;只处理这一处提示。
按项目现有方式构建和检查,汇报实际执行的命令及结果。第四步:检查实际行为
- 差异中只出现预期的提示修改,没有清理无关工作。
- 执行了项目真实存在的验证命令,且结果可查。
- 搜索无结果仍可恢复操作,原来的正常结果未受影响。
- 如果无法运行验证,说明具体阻碍,而非写成全部通过。
一次成功不代表所有后续任务都遵守规则。将重复出现的失败整理成更具体的指导,并用下一次相关改动检验。需要强制执行的要求还应交给检查脚本或 CI,文字指导不能替代程序检查。
常见问题与处理顺序
命令找不到:回到 package.json 确认脚本,不要先安装陌生依赖。规则互相冲突:定位对应目录,删去过时或重复约定。文件越来越长:只留下稳定事实,把详细操作移入已有项目文档或 Skill,并说明什么时候阅读。
不要把客户名单、API 密钥和个人令牌写进 AGENTS.md;被版本控制保存的项目规则会随仓库分享。也不要把一次临时任务粘成永远适用的项目要求。
下一步练习
为你自己的项目写三项指导:一个真实验证命令、一个容易重复犯的具体错误、一个完成标准。用一处小改动验证,保存差异与执行记录。需要区分技能与连接时,继续阅读 Skills 与 MCP 的区别;还没完成第一次改动时,先看 Codex 入门实战。