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

原文：https://itjc.com/tutorials/codex-agents-md/
主题：Codex；级别：入门；更新时间：2026-11-15。

> 提供可复制的项目规则示例，解释 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 的区别](/tutorials/skills-vs-mcp/)；还没完成第一次改动时，先看 [Codex 入门实战](/tutorials/codex-first-change/)。

## 官方资料与参考

- [Codex 官方定制说明](https://learn.chatgpt.com/docs/customization/overview)
- [Codex 自定义项目指令](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
