AGENTS.md 怎么写：让编程智能体理解项目规则
Neaptide · 2026年9月6日 · 7 分钟阅读
说明 AGENTS.md 的内容、Codex 的读取范围和验证方法。附简短示例、可下载模板与目录范围图。
本文目录
如果智能体总把文章放错目录，或者反复建议不存在的测试命令，可以把长期约定写进 AGENTS.md。它是一个 Markdown 文件，用来提供项目工作指令。最有价值的是那些无法仅凭代码可靠推断的信息。
不同信息放到不同位置
| 位置 | 用途 |
|---|---|
| README | 供人阅读的安装、运行与项目介绍 |
| AGENTS.md | 项目长期工作约定 |
| Skill | 可复用的研究、编辑或检查流程 |
| 任务消息 | 这次要做什么，以及具体例外 |
“写高质量代码”很难指导具体选择。“文章放在哪个目录，改完运行哪项检查”则可以验证。已有文档只需链接并说明何时阅读，不要复制多份。
内容网站的简短示例
下面的路径和构建命令在我们的网站中存在。用于别的项目之前，应先核实并修改。下载文件扩展名为 .txt，将适配后的内容保存为目标目录中的 AGENTS.md。
# 项目工作约定
- 修改前阅读 package.json 和相邻文件。
- 文章放在 content/blog/articles，不放入界面字典。
- 已发布文章保留 slug，除非任务要求更改地址。
- 修改内容后运行 npm run build。
- 添加逻辑后，运行 scripts 中相关的检查。
- 汇报已完成的检查及仍存在的限制。不要因为别人的模板有 npm test 就照搬；项目可能没有这个脚本。检查应与改动相关，修改一条图片说明不应自动触发全面审计。
Codex 如何发现指令文件
根据官方文档，Codex启动时先读取全局指令，再沿项目根目录到当前工作目录的路径，读取各层目录中的指令文件。在同一目录中，它先查找AGENTS.override.md，最多只选用一个文件，不会再叠加该目录的AGENTS.md。越靠近工作目录的指令，用来细化前面的规则。其他工具的读取方式可能不同，应分别查阅说明。
如果某个子目录使用专属命令或有特殊约定，可以在其中另放一个AGENTS.md。整个项目共用的规则保留在根目录，无需到处复制。
怎样确认规则起作用
- 检查文件名以及任务的工作目录。
- 更改指令后重新启动一次任务，请智能体列出适用文件与相关规则。
- 安排一个小的实际修改，检查它修改了哪些路径、运行了什么命令。
- 如有遗漏，先找冲突和 override 文件，再把模糊规则写清楚。
智能体能正确复述规则，不代表实际操作一定正确。要看最终改动和命令结果。Codex 还规定了项目指令的总大小限制，不能假定一个很长的文件总会完整进入上下文。
Markdown 不能替代技术控制
在文件里写“不要读取密钥”，并不能真正限制访问；写“运行测试”，也不会自动配置持续集成（CI）检查。AGENTS.md用来说明工作要求，访问权限、分支保护和自动测试则需要另外设置。示例中也不要放入真实凭据。
项目结构变化时同步更新 AGENTS.md。针对反复出现的明确问题添加规则，在后续任务中验证效果，过时后删除。它应该减少猜测，而不是记录每一次历史错误。