添加 AGENTS.md 的目标不是堆砌冗长的说明，而是通过沉淀项目规则来提升 Codex 的工作效率与稳定性。建议遵循“只读分析 -> 生成草稿 -> 审查修改 -> 正式写入”的闭环流程。

准备工作

在开始前，请确保：

  • 已选择一个可用于练习的非核心项目。
  • 项目的 Git 状态是干净的。
  • 你已熟悉项目的基本目录结构与构建方式。

执行步骤

第一步：项目深度盘点

不要凭空猜测项目的命令。要求 Codex 优先读取 package.json、pom.xml 或 README.md，总结真实存在的脚本、主要技术栈及目录分布。

第二步：生成规则草稿

基于只读分析的结果，让 Codex 生成一份 AGENTS.md 草稿。草稿应聚焦于：

  • 项目概况：让 Codex 知道它在处理什么。
  • 核心命令：确保列出的检查与构建命令真实可用。
  • 修改禁区：明确告知哪些文件（如锁文件、生成物）不要随意更改。

第三步：人工审查（关键）

审查草稿时需重点关注：

  • 去空泛化：删除“代码要优雅”等模糊表述，改为“改动后需运行构建检查”。
  • 去猜测化：删除 Codex 推测但实际不存在的脚本。
  • 安全性：确保没有泄露任何敏感的 Token 或私有路径。

第四步：正式写入与验证

将确认无误的草稿写入项目根目录的 AGENTS.md。随后，尝试发布一个小任务（如文案修改），观察 Codex 是否能主动引用新建立的规则，并按要求的格式进行汇报。

常见误区

  • 过度设计：第一版就想写出万能规则。建议先从最核心的 5-10 条规则开始，逐步迭代。
  • 混淆配置：将模型 Provider 等运行参数写进 AGENTS.md。记住，这里只写项目规则。
  • 缺乏维护：项目脚本变更后未及时更新规则文件，导致 Codex 按照过时命令操作。

总结

一份合格的 AGENTS.md 应具备“短小、精准、可执行”的特点。它是你与 Codex 之间的“协作协议”，能够有效减少因上下文缺失导致的低级错误。