AI 编程与开发

AGENTS.md 怎么写：留下项目约束，再用索引组织细节

“保持样式”“别加后端”“改完跑测试”反复说了几次，就值得写进项目说明。AGENTS.md 适合留下长期有效的约束，下一次接手项目时更容易找回这些要求。

文件不用长，先把项目范围、修改边界和检查方法写明白。

一个小项目可以从这份说明开始

下面是待办项目的模板，路径和命令要按实际项目调整：

1
2
3
4
5
6
7
8
9
# 项目说明

- 原生 HTML/CSS/JavaScript；保存版位于 demo/after/。
- 保持页面样式和可访问名称，不新增后端。
- demo/before/ 是教学对照，不要把它改成保存版。
- 首次安装依赖使用 npm ci。
- 修改 JavaScript 或测试后运行 npm test。
- 验收覆盖新增后刷新、删除后刷新、空白输入和坏 JSON。
- 交付说明修改内容、实际运行的检查及未验证部分。

它比“写高质量代码”更容易执行：能找到目录、能运行命令，也能判断哪些行为不能改。

文件放在哪里

项目专用说明放在项目根目录。个人通用偏好可以放在 Codex 的全局说明中，默认目录是 ~/.codex。不要把某个项目的专属脚本写成所有项目都必须执行的命令。

官方说明中，Codex 在启动时构建指令链：先看全局，再从项目根目录走到当前工作目录；同一目录下 AGENTS.override.md 优先于 AGENTS.md。文件改变后，用新的运行或重开会话确认加载情况。官方 AGENTS.md 指南

可以先发一句检查用的任务：

1
2
列出实际读取的指令文件，概括本项目的范围、修改约束和验收命令。
先不要改代码；无法确认的地方明确说明。

这是提问模板，不是一次真实模型回复的截图或记录。

长起来以后，让它做索引

规则和操作细节越积越多时，可以在 AGENTS.md 中只留下入口与关键约束，详细方法放进 TASK.md 或项目文档，并明确要求先读。例如：

1
2
开始任务前先读 TASK.md，了解当前状态和已验证的方法。
发布与恢复步骤见 TASK.md；证据保存在 audits/。

TASK.md 在这里是项目约定，不是因为这个名字就会自动加载。文件里的指令也不能代替代码审查和测试输出。

原笔记发表于2026年10月5日，博客于10月27日整理并补充索引用法。原项目沿用已有测试，本篇新增的是说明模板，没有做模型遵守率或指令加载效果的对照实验。

本文发表日期：