如果你经常重复告诉 Codex“沿用现有样式”“检查手机布局”“不要改接口字段”，可以把这些稳定约定整理到 AGENTS.md。把一条临时需求写进聊天，把跨任务都适用的规则写进项目说明，后续维护会更清楚。
AGENTS.md 的作用与位置
AGENTS.md 是 Codex 能识别的项目指导文件。官方文档说明了全局指导、项目目录指导与覆盖文件的发现方式：项目规则沿项目根目录到当前工作目录的路径组合，较具体的目录指导可覆盖上层约定；同一目录存在覆盖文件时，读取顺序也会改变。具体边界以官方说明为准。查看规则发现机制。
入门时可以先在项目根目录维护一份精简文件，不必立刻为每个目录建立规则。先观察有哪些约定真的反复出现，再拆分需要特殊处理的模块。
一个适合小型博客的示例
下面是本站设计的示例，请根据自己项目的真实命令和约定调整：
# 项目约定
## 页面与内容
- 使用当前项目已有的组件、字体和颜色变量。
- 文章详情需要检查空内容、长标题和手机宽度。
## 接口与数据
- 外部接口数据先校验再入库。
- 数据结构变更需要说明对现有数据的影响。
## 验证
- 从 package.json 确认项目实际支持的检查命令。
- 修复问题后，重新执行触发它的操作。
- 交付时说明已验证的结果与未验证的部分。这里没有假定所有项目都有相同的测试脚本，也没有规定所有改动必须跑一整套耗时检查。规则应帮助做决定，而不是让每次小修改都执行不相关的流程。
把模糊要求改成能检查的结果
“保证专业”“不要出错”很难直接验收。可以改为：“表单保存失败时展示错误原因，并保留用户输入”；“列表没有数据时展示空状态，提供恢复入口”。这样的规则能对应到实际页面和测试场景。
写之前可以问自己：这条规则解决过什么重复问题？是否能从代码或界面判断遵守情况？它是否只适用于一个任务？如果只适用本次需求，放在本次对话通常更合适。
如何确认规则被读取
在项目中开始一次任务时，可以先问：“请说明这次任务适用的项目指导文件，以及和本次修改相关的约定。”核对回答中的路径与内容。若规则不符，先检查工作目录、文件是否为空，以及是否有 AGENTS.override.md 等覆盖文件；不要盲目叠加相互矛盾的说明。
项目调整后也要更新过时的启动命令。失效的命令比缺少命令更容易让后续排查走偏。
哪些内容不适合放进去
- 密码、访问令牌、私钥和完整连接凭据。
- 每轮都会变化的日志和任务进度。
- 与项目无关的大段通用知识。
- 已经由格式化工具或现有检查自动保证、又没有额外解释价值的重复规则。
团队可以把文件与代码一起维护。每次修改规则时，说明它解决的实际问题，有助于避免约定无限膨胀。
常见问题
它等于长期记住所有聊天吗？
不是。它是文件中的明确指导。任务状态、讨论细节与代码事实仍应从当前项目和相关对话判断。
写得越长越好吗？
先保留真正影响行为的规则。官方机制存在文档读取大小限制，大量重复内容也会增加理解负担。
文件写完后还需要描述需求吗？
需要。文件保存长期约定，当前对话说明这次想实现什么、哪里有问题、怎样算完成。