每次开新对话都重复交代“用中文、别乱动文件、改完检查”，可以把这些工作约定放进 AGENTS.md。本教程使用一个原生 HTML、CSS 和 JavaScript 的待办清单演示项目，没有后端。
先准备一个独立演示项目
先保存一个正常版本并提交到 Git。AGENTS.md 放在项目根目录，和本例的 index.html、app.js、style.css 同级。先用测试项目练习，避免把演示过程混进日常项目。
下载待办清单演示 ZIP。完整解压后，用浏览器打开 index.html。本例可添加、勾选和删除待办，刷新后清空。演示包内已经附有五段模板，练习初始化前可先把模板另存，随后核对生成的草稿。
全局说明放在 Codex 主目录，默认是 ~/.codex/AGENTS.md，自定义过主目录时以实际位置为准。Codex 先加载全局说明，再从项目根目录向当前工作目录查找。靠近当前目录的项目说明排在后面，冲突时优先。每层优先采用非空的 AGENTS.override.md，再找 AGENTS.md。合并的项目说明默认上限为 32 KiB，按字节计算。
先生成，再修改
在本次桌面版本的输入框中输入 /，可以看到“初始化”命令（/init）。它会阅读项目并生成草稿。本次生成的是英文。逐条检查它有没有猜错项目结构和命令，再用自己的项目约定替换；生成稿不是无需检查的最终规则。
/init
可复制的五段模板
以下是针对本例整理的教学模板。把项目简介、命令和文件名替换成你实际使用的内容，不要把不存在的测试命令原样照抄。node --check 只检查语法，git diff --check 主要检查差异格式；都不能替代打开网页验证功能。
1. 项目说明
## 项目说明 - 这是一个待办清单网页，用原生 HTML、CSS、JavaScript 写的，没有后端。
2. 常用命令
## 常用命令 - 本地预览：直接用浏览器打开 index.html。 - 语法检查：node --check app.js。 - 差异检查：git diff --check。
3. 改代码的规矩
## 改代码的规矩 - 开始改代码前先运行 git status；有没提交的改动，先停下来问我。 - 只改和这次任务有关的文件。 - 不要修改 style.css，除非我明确要求。
4. 改完要检查
## 改完要检查 - 改完打开网页，把改到的功能实际操作一遍。 - 最后列出改了哪些文件，每个文件一句话说明。
5. 沟通
## 沟通 - 用中文回复。 - 需求不清楚就先问我，不要自己猜。
实测提示词
验证一：让它总结
保存 AGENTS.md 后，新建一个对话，输入：
总结一下你现在要遵守的项目说明。
核对它是否提到你刚写的项目、文件范围、修改前检查、修改后检查和沟通要求。不要只看文件已经存在，就当作它已经读到。
验证二：看实际行为
以下是本期用来验证行为的教学输入，并非日常项目的历史需求。
先给 app.js 添加一行无功能影响的教学注释，暂时不要提交。再输入：
把添加按钮改成蓝色。
本次实测中，Codex先执行 git status，发现 app.js 未提交后暂停，询问是否保留现有改动并继续。请求前后四个项目文件的哈希均未改变。这里的检查重点是是否先停下；不要把暂停误认为按钮已经改好。
AGENTS.md 是说明，不是保证任何请求都一定服从的开关。重要改动仍要检查实际差异并操作验证。
改了没生效怎么办
本次在规则中加入临时A/B标记：文件改成B后，原对话仍回答A，新对话才读到B。因此改规则后先开新对话，再问一次当前说明。A/B标记只是验证装置，不需要放进日常模板。
检查文件名是否为 AGENTS.md，位置是否为项目根目录。然后删掉空话，保留具体、可核对的约定。同目录有 AGENTS.override.md 时会优先采用该文件，排查时也要留意。
官方说明
本篇以 2026 年 11 月 7 日在本机桌面端的隔离项目实测为例。AGENTS.md 用来记录项目约定，实际改动仍需检查差异并操作验证。
全部资料下载
按实际视频章节回看
- 00:00 每次都要重新交代？
- 00:33 AGENTS.md 放在哪
- 01:34 先用初始化生成草稿
- 02:05 写什么：五段模板
- 03:51 实测：它到底读到没有
- 04:45 改了没生效怎么办
- 05:25 模板与下一步练习
完整视频文稿
展开完整口播文稿
每次都要重新交代？
每次跟 Codex 开新对话，都要把同样的规矩再交代一遍：用中文回复，哪些文件别动，改完要检查。
其实可以把这些约定写进一个 AGENTS.md，让 Codex 开工前先读。这期讲三件事：放在哪，写什么，还有怎么确认它真的读到了。完整模板和验证步骤，我也整理成了配套文章。
AGENTS.md 放在哪
AGENTS.md 就是一个普通的文本文件。先从最简单的用法开始，把它放在项目根目录，也就是 Git 仓库最外面那一层，跟这里的 index.html 放在一起。
还有一份全局说明，放在 Codex 主目录里。默认是用户目录下的点 codex 文件夹，适合写“用中文回复”这种个人习惯。如果你自定义过 Codex 主目录，就以实际位置为准。项目里的文件，则用来写这个项目的规矩。
两层都会读，项目里的排在后面，两边说法冲突时，以项目里的为准。
所有说明合起来还有大小上限，默认是三十二 KiB。这是文件大小，不是字数。所以写短一点，只写真正要它遵守的。
先用初始化生成草稿
不知道从哪写起，可以先在输入框输入斜杠 init。这里的菜单叫“初始化”，会让 Codex 看一遍项目，生成 AGENTS.md 草稿。
我这次生成的是英文，里面列了项目结构、检查命令，还有改代码的约定。先检查这些内容是不是符合你的项目，草稿只当参考，下面再按模板改成自己的。
写什么：五段模板
我把模板分成五段，你照着把内容换成自己项目的就行。
第一段，项目说明。一两句话说清楚这是什么项目，用了什么技术。这里是原生 HTML、CSS 和 JavaScript 写的待办清单，没有后端。
第二段，常用命令：怎么预览，怎么检查。这个小网页直接打开 index.html 就能预览，再把 JavaScript 语法检查和 Git 差异检查的命令写进去。有测试的项目，就填你实际使用的测试命令。
第三段最重要，改代码的规矩。比如：开始前先运行 git status，有没提交的改动，先停下来问我。这条接着上期，提醒它先确认你手里的改动。再比如：只改跟任务有关的文件，未经明确要求，不要修改 style.css。
第四段，改完要检查什么：打开网页，把改到的功能实际操作一遍。最后列出改了哪几个文件，每个文件一句话说明。
第五段，沟通习惯：用中文回复，需求不清楚就先问，不要自己猜。
记住，写具体的，别写空话。“注意代码质量”太笼统，换成“改完运行这条检查命令，全部通过再结束”，就有了能核对的动作。
写好保存，再把这个文件提交到 Git。以后规矩改了，也能查到记录。
实测：它到底读到没有
保存以后，新建一个对话再测。
先问它：总结一下你现在要遵守的项目说明。这里它把修改前检查、不要随意动样式文件，还有改完检查这些约定，都复述出来了。
再来一次真的。我先给 app.js 加一行注释，暂时不提交，然后让 Codex 把添加按钮改成蓝色。
它先运行了 git status，发现 app.js 有没提交的改动，就停下来问我是否继续。这次的行为跟规矩写的一样，文件也没有被它改动。
不过，AGENTS.md 是给它的说明，不是保证每次都照做的开关。重要的改动，还是要自己检查。
改了没生效怎么办
改了 AGENTS.md 好像没用？先新建一个对话再试。这次实测里，我把验证标记从 A 改成 B，原来的对话仍然回答 A，新对话才读到了 B。
还不行，就检查文件名和位置：名字是 AGENTS.md，放在项目根目录。再让它总结一次当前说明，核对有没有读到你刚改的内容。
规矩越写越多也不好。删掉空话，只留你确实需要它遵守、而且能够检查的约定。
片尾
完整模板和验证方法已经整理在配套文章里。你可以先给自己的项目写上这五段，再开一个新对话，检查它读到了哪些规矩。
这里是西楚极客，我们继续用 AI，把真正能运行的项目做出来。下期见。
Codex 新手必会
第1篇 · Codex 改坏了代码怎么办？ · 上期视频 ↗
第2篇 · 本期 AGENTS.md 教程 · 全部文章 →
