在与 Codex 协作的过程中，开发者经常面临一个挑战：每一个新的对话会话（Thread）都是一个完全空白的上下文。AI 默认并不了解您的项目构建流程、目录结构规范、文件修改禁区或团队特定的交付标准。AGENTS.md 正是为了解决这一“工程记忆断层”而设计的项目级指令规范。

核心定义：什么是 AGENTS.md？

AGENTS.md 是专门面向 Coding Agent (编程代理) 的项目操作手册。它不同于传统的 README.md（面向人类开发者），其核心目标是显式地定义 AI 助手在当前项目中的行为准则、环境约束和协作边界。通过将长期有效的规则固化在文件中，您可以确保 Codex 在任务启动的第一时间准确同步项目背景，从而极大地降低沟通成本和误操作风险。

为什么 AGENTS.md 是不可或缺的？

  • 工程经验固化：将“哪些目录禁止触碰”、“代码提交前必须运行的测试命令”等实战经验沉淀为可执行规则。
  • 消除上下文噪音：避免在每次发起任务时，重复输入繁琐的环境说明和项目背景。
  • 建立团队共识：确保团队内所有成员在使用 Codex 时，都能遵循一致的开发规范和质量验收流程。
  • 提高交付确定性：通过显式的边界定义，将 AI 的“随机性”转化为可预测的“工程行为”。

推荐写入的核心内容维度

为了让 AGENTS.md 发挥最大效用，建议从以下几个维度进行细化描述：

| 内容维度 | 核心作用与示例 |

| :--- | :--- |

| 项目概览 | 定义核心技术栈（如 Nuxt 3, Spring Boot 3.2）及项目核心业务定位。 |

| 关键目录索引 | 明确源码主入口、公共配置路径、静态资源存放点以及第三方库 vendor 目录。 |

| 工程命令集 | 列出真实有效的构建 (npm run build)、测试 (vitest) 及 Lint 格式化脚本。 |

| 修改边界约束 | 明确规定禁止 AI 自行修改的文件（如配置文件、锁文件）或不建议重构的遗留模块。 |

| 质量验收标准 | 规定交付前必须执行的自查流程、汇报格式（如 Diff 说明、风险评估报告）。 |

| 合规与安全红线 | 严禁 AI 访问敏感凭据目录，禁止将硬编码密钥写入代码逻辑。 |

严禁写入的内容避坑指南

为了保证安全性与效率，请务必避免在 AGENTS.md 中包含以下内容：

  • 敏感凭据：绝对禁止写入任何 API Key、Token、服务器 IP 或账号密码。
  • 临时性需求：针对某个特定 Bug 的修复方案或一次性功能需求，应留在当前对话中，不应进入长期规则文件。
  • 模糊指令：诸如“代码要写得好”这类无法量化验收的描述，应优化为“函数长度不应超过 50 行”等具体规则。
  • 运行环境配置：具体的模型 Provider、API 端点等信息属于 config.toml 的范畴，不应混入 AGENTS.md。

作用域优先级与目录层级

Codex 支持灵活的规则覆盖机制，允许您根据项目复杂度进行分层管理：

  1. 用户全局级 (~/.codex/AGENTS.md)：定义适用于您所有项目的通用开发偏好。

    2. 2. 项目根目录级 (/AGENTS.md)：定义当前仓库内全员共享的工程规则。

    3. 模块/目录级 (/src/legacy/AGENTS.md)：为特定高风险或特殊规范的子模块定义覆盖规则。

    规则合并逻辑：Codex 会自动由远及近地合并各级 AGENTS.md，离当前工作目录最近的文件拥有最高的执行优先级。

    编写与维护的最佳实践

    1. 先调研后定义：不要凭空构思规则。建议先让 Codex 对现有项目进行只读分析，识别出真实的脚本命令和目录结构后，再将其整理进 AGENTS.md。

      2. 2. 由简入繁，小步迭代：首个版本建议仅包含 5-8 条最核心的规则。随着协作深入，根据 AI 经常犯的错误持续完善规则库。

      3. 保持动态同步：每当项目技术栈升级或构建流程变更时，务必第一时间更新 AGENTS.md，避免 AI 助手陷入基于旧规则的错误尝试。

      ---

      下一篇推荐：config.toml 配置深度解析 —— 掌握如何全局优化 Codex 的运行效率与 Provider 行为。