Agentsmd介绍
AGENTS.md 是项目给 Codex 的一份“工作说明书”。
它通常放在仓库根目录或某个子目录中，用来明确说明这个范围内代码的协作规则、实现约束、常见操作方式，以及在执行任务时应优先遵守的工程约定。
在多人协作项目中，人类成员会通过开发规范、目录约定、评审标准来降低沟通成本；而在引入 Codex 后，AGENTS.md 的作用就是把这些隐性经验显式化，让 Codex 在生成代码、修改文件、运行命令和编写文档时，尽量贴合团队的真实工作方式。
可以把 AGENTS.md 理解成“面向 Codex 的项目内操作手册”。它不是业务代码的一部分，但会直接影响 Codex 的输出质量和执行边界。
如果项目没有清晰的 AGENTS.md 约束，Codex 往往只能依据通用经验工作，这会带来几个典型问题：
-
实现风格不一致
比如项目要求不使用某个框架特性、必须沿用已有分层结构、接口命名需要遵循团队规范，但这些规则如果没有写出来，Codex 就可能给出“能跑但不符合团队习惯”的方案。 -
容易触碰隐性禁区
例如不能改动某些基础模块、不能直接执行破坏性命令、不能引入新依赖、不能修改数据库结构。如果这些约束只存在于团队口头约定中，Codex 无法稳定遵守。 -
重复解释成本高
每次都要重新告诉 Codex “这个项目不用 Lombok”“先读文档再改代码”“提交信息必须按某种格式写”，会显著增加交互成本，也不利于批量复用。 -
结果可控性不足
同样一个任务，不同轮次得到的结果可能差异较大。缺少稳定规则时，Codex 输出会更依赖即时上下文，而不是项目长期约定。
本质上，问题不是 Codex “不会做”，而是项目没有把“应该怎么做”描述清楚。
设计 AGENTS.md 的核心思想，不是罗列越多规则越好，而是把最影响结果质量的约束沉淀下来，让 Codex 在执行任务时形成稳定判断。
可以按下面三个层次来组织：
先告诉 Codex 什么能做、什么不能做，例如：
- 哪些目录可以修改，哪些目录禁止改动
- 是否允许新增依赖、修改数据库、执行脚本
- 是否必须先阅读某些文档或接口定义再开始改动
这一步的目标，是先保证“不要做错”。
在边界明确后，再补充项目的具体工程规则，例如：
- 代码分层和目录约定
- 命名规范、注释规范、提交规范
- 测试要求、文档要求、错误处理方式
这一步的目标，是让 Codex “按团队方式做对”。
当不同规则发生冲突时，需要明确优先顺序，例如：
- 先遵守安全和破坏性操作限制
- 再遵守项目编码规范
- 最后再考虑生成效率和简洁性
这一步的目标，是让 Codex 在复杂场景下也能稳定决策。
一个好的 AGENTS.md，重点不是“大而全”，而是“高频、关键、可执行”。优先写那些最容易出错、最影响交付质量、最值得长期复用的规则。