Codex

Codex AGENTS.md 怎么写?用一个小项目验证规则是否生效

提供可复制的项目规则示例,解释 AGENTS.md、Skills、MCP 的分工,并用实际任务检查指令是否有效。

先回答: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 的项目示例。它是供人审阅后放进项目的规则,不是要求你在所有仓库强行创建这些目录。

markdown
# 项目指导
## 项目结构
- src/:页面与业务逻辑。
- public/:直接发布的静态资源。
- 先阅读 README 和 package.json,再选择验证命令。
## 修改约定
- 沿用现有模块风格,新增依赖前说明用途。
- 开始前检查 git status,保留已有未提交改动。
- 不在日志、示例或提交中写入真实凭据。
## 验收
- 内容与页面变动:npm run build,再运行 npm run check。
- 搜索相关改动:检查空输入、正常结果和无结果状态。
- 汇报实际执行结果,未执行的检查写明原因。

规则应该描述稳定事实与可验证行为。“永远写最优雅代码”难以验收;“搜索无结果时保留清除筛选入口”更容易检查。环境会变,命令变更后要同步维护。

第三步:确认加载范围

Codex 可以加载用户级和仓库内不同位置的指导,更接近工作目录的规则有更具体的适用范围。因此遇到“明明写了却没照做”,先确认当前打开的是哪个项目与目录,再看目录中是否有其他指导。

不要仅凭模型说“我已经读了”判断成功。给它一个与规则相关的小任务,让最终改动和验证记录提供证据。

text
在当前项目把搜索无结果提示改为:没有找到相关教程,试试清除筛选。
先确认适用的项目指导与当前改动;只处理这一处提示。
按项目现有方式构建和检查,汇报实际执行的命令及结果。

第四步:检查实际行为

  • 差异中只出现预期的提示修改,没有清理无关工作。
  • 执行了项目真实存在的验证命令,且结果可查。
  • 搜索无结果仍可恢复操作,原来的正常结果未受影响。
  • 如果无法运行验证,说明具体阻碍,而非写成全部通过。

一次成功不代表所有后续任务都遵守规则。将重复出现的失败整理成更具体的指导,并用下一次相关改动检验。需要强制执行的要求还应交给检查脚本或 CI,文字指导不能替代程序检查。

常见问题与处理顺序

命令找不到:回到 package.json 确认脚本,不要先安装陌生依赖。规则互相冲突:定位对应目录,删去过时或重复约定。文件越来越长:只留下稳定事实,把详细操作移入已有项目文档或 Skill,并说明什么时候阅读。

不要把客户名单、API 密钥和个人令牌写进 AGENTS.md;被版本控制保存的项目规则会随仓库分享。也不要把一次临时任务粘成永远适用的项目要求。

下一步练习

为你自己的项目写三项指导:一个真实验证命令、一个容易重复犯的具体错误、一个完成标准。用一处小改动验证,保存差异与执行记录。需要区分技能与连接时,继续阅读 Skills 与 MCP 的区别;还没完成第一次改动时,先看 Codex 入门实战。

官方资料与参考

产品功能与命令可能调整。遇到差异时,以对应官方页面和当前环境为准。

读完了,动手试一次。

完成练习后,标记进度,方便继续学习。

需要独立的 macOS 开发环境?

了解三万主机的远程 Mac 租赁,或先看看你是否需要一台远程 Mac。

了解三万主机 ↗