Appearance
AGENTS.md：把项目规则写清楚，而不是写一篇口号
每次开新任务，都要重复“别加依赖”“改完跑测试”？可以把这些固定约定放进项目的 AGENTS.md。下面沿用第 3 课的 codex-first-project 目录，写一份可以直接使用的规则。
写好后，新任务可以只说这次要做什么，把固定的项目命令和约定留在文件里。它是给 Agent 看的项目说明，不是另一种程序，也不是安全沙箱。
第一步：选出不想反复说的规则
| 内容 | 放哪里 | 原因 |
|---|---|---|
| 项目目录、测试命令、代码约定 | AGENTS.md | 多次任务都需要 |
| 本次优惠规则修改、当前故障现象 | 当前任务 | 不一定是长期规则 |
| 一套可重复的完整工作流程 | 先跑通，再考虑 Skill | 不把规则文件变成万能脚本 |
| 密钥、账号令牌、客户私人数据 | 不写进这些公开文件 | AGENTS.md 可能进入仓库与模型上下文 |
“代码要优雅、达到工业级”不能告诉 Agent 如何验收。用“修改 checkout.mjs 后执行这个测试命令，并报告结果”更明确。
第二步：把它保存到项目目录
对读项目练习，可下载 AGENTS.md 示例。保存到练习目录，确认实际文件名是 AGENTS.md，而不是 AGENTS.example.md 或 AGENTS.md.txt。
markdown
# 练习项目约定
- 先阅读 demo.mjs、catalog.mjs、checkout.mjs 和 checkout.test.mjs。
- 金额使用整数分，不新增第三方依赖。
- 如果任务只要求解释，不修改文件。
- 修改业务代码后运行 node --test checkout.test.mjs，报告真实结果。
- 不删除或弱化测试以掩盖失败；规则变化先说明理由。
- 完成时说明修改文件、测试结果和未覆盖的边界。只在练习目录使用这份文件。真实项目要换成自己实际使用的命令，不要让 Python 项目运行一个不存在的 Node.js 测试。
若目录里已经有 AGENTS.md，先阅读并补充，不要覆盖别人的约定。用编辑器修改比不加判断地重定向覆盖更安全。
第三步：启动新会话，检查规则来源
保存后，在 codex-first-project 目录启动新的 Codex 会话：
bash
codex --sandbox read-only --ask-for-approval on-request在对话里发送：
text
请列出当前生效的项目规则来源，并复述本项目测试命令。
只回答，不修改文件。先核对它是否提到了你刚保存的 AGENTS.md，测试命令是否为 node --test checkout.test.mjs。若答成 npm test，不要只补一句“请遵守规则”，先按下面的排障顺序检查目录和文件名。
接着用第 3 课的只读任务，让它解释为什么订单是 1300 分。看回答是否给出文件依据，并比较原始副本，确认输入没有变化。没有保留副本时，先在开始任务前复制一份；也可使用第 3 课的选做校验命令。
能复述规则，是检查的起点，不是遵守规则的保证。 只读沙箱也能阻止修改，所以“文件没变”不能单独证明规则生效。后续真正修改业务代码时，还要查看是否执行了正确的测试命令、结果是否符合要求。
进一层：规则为什么要放对位置
刚开始只需在项目根放一份。项目变大后，再根据工作目录分层：
- ① 个人默认约定全局 AGENTS.md例如：回答用中文
- ② 这个项目的约定项目 AGENTS.md例如：金额用整数分
- ③ 当前目录的细则子目录 AGENTS.md例如：使用该模块的测试命令
需要排查 override 或多层目录时，再看完整发现顺序
官方当前文档描述了两层：
- 全局：默认 Codex home 下按
AGENTS.override.md、AGENTS.md顺序，取首个非空文件。 - 项目：从项目根目录沿路径走到当前工作目录；找不到项目根时只检查当前目录。每层最多选择一个规则文件；同层优先 override，再是 AGENTS.md，再是配置的备用文件名。
规则按从上到下的顺序合并，离当前目录更近的规则可以覆盖前面的相关指导。不是“读取项目里所有子目录的 AGENTS.md”，也不是子目录文件会抹掉所有全局约定。
例如项目根有 AGENTS.md，checkout/ 下有更具体的规则：从根目录开始的会话与从 checkout/ 开始的会话，发现路径并不相同。不要只移动文件，然后假设已启动的会话自动重建全部规则链。官方建议重启目标目录中的会话再核查。
任意目录里放一个 .agent/AGENTS.md 也不必然自动加载。想引用其他说明文件，可以在已被发现的 AGENTS.md 中明确写出路径；有无实际读取仍需检查。
规则文件也有总长度限制，过长可能截断。不要把完整产品文档都粘贴进去；把常用命令和关键约定写在前面，再按需引用其他文件。
没生效时按这个顺序查
- 当前工作目录是否正确？用
pwd确认，不能只看编辑器打开了哪个窗口。 - 文件名和内容是否正确？空文件和错误扩展名不能充当有效规则。
- 同层是否有
AGENTS.override.md？它可能优先于你编辑的普通文件。 - 是否有更近目录的冲突约定？写出规则来源再判断。
- 修改后是否重启会话？不要用旧会话的行为证明新规则生效。
不要为了排障删除全局配置或登录文件。
最重要的边界：规则不是权限
“不要联网”“不要删除文件”是指导；系统沙箱、审批策略和工具权限才负责技术边界。不要因为写了十条禁止事项就授予不必要的全盘权限。
先保持规则短、具体、可验证。只有反复出现的错误才值得加入长期规则；很长的口号清单会让真正重要的约束更难找到。
把规则改成自己的
找一条“代码要专业”之类的规则，改成“什么情况下，执行什么检查，报告什么结果”。先在终端运行那条检查命令：如果命令或文件不存在，这条规则就不能直接交给 Agent。临时需求（例如本次优惠金额）不要写成长期规则。
参考资料
- Custom instructions with AGENTS.md：发现顺序、override、核验与排障。
- Best practices — Make guidance reusable：规则应实用、准确、保持简洁。