Codex AGENTS.md 使用与规则优先级

AGENTS.md 并不是 Codex 的“永久记忆”，而是一份随项目保存、在任务启动时加载的指令文件。它适合记录项目目标、执行边界和验收标准，让 Codex 在不同任务中遵循一致规则，但不会自动保存聊天中的全部信息。

Codex 会按什么顺序读取

Codex 启动任务时，会查找相关指令文件并组合成一条规则链。

第一层是全局规则，默认位于 ~/.codex/ 目录：

• 如果存在非空的 AGENTS.override.md，优先读取该文件。
• 如果没有可用的覆盖文件，则读取 AGENTS.md。

第二层是项目规则。Codex 会从项目根目录开始，沿目录层级检查到当前工作目录，每个目录最多加载一份指令文件。距离当前目录越近的规则越晚加入，因此发生冲突时，局部规则可以覆盖上层的通用要求。

这种机制适合组织“全局习惯 + 项目约束 + 局部例外”。例如：

• 全局规则要求每次修改后运行测试。
• 项目根目录规定统一的品牌名称和交付格式。
• 特定子目录补充文件命名或内容格式要求。

需要注意的是，合并后的项目指令默认最多读取 32 KiB。如果文件内容过长，靠后的规则可能被截断。因此，关键要求应尽量简短、明确并且可以检查。

普通用户最值得写什么

即使不熟悉编程，也可以在项目根目录创建 AGENTS.md，优先记录以下四类信息：

1. 项目目标：说明项目面向谁、需要解决什么问题，以及最终交付什么。
2. 固定规则：约定命名方式、内容格式、使用语言和文件存放位置。
3. 安全边界：列出必须先询问的操作，以及任何情况下都不能执行的动作。
4. 完成标准：明确需要完成的检查、测试和记录。

例如，在内容运营项目中，可以规定对外品牌名称、文章保存目录和来源核验要求，并明确“只能保存草稿，禁止直接发布”。这样开启新任务时，就不必重复粘贴同一组提示词。

下面是一份精简示例：

# 项目目标
为内容团队整理并生成待审核文章草稿。

# 固定规则
- 使用简体中文。
- 草稿保存到 drafts 目录。
- 引用信息必须附带来源。

# 安全边界
- 删除文件前必须询问。
- 禁止发布、群发或设置定时发布。

# 完成标准
- 检查标题、链接和引用来源。
- 在任务记录中列出修改内容。

一次只读任务测试

原文记录了一次在项目根目录发起的新 Codex 只读任务。测试要求 Codex 不主动读取文件、不执行命令，只总结任务启动时已经加载的项目规则。

Codex 能够复述项目中的品牌使用要求、浏览器独立配置与端口约束，以及内容流程中的授权边界。这表明，项目根目录下的 AGENTS.md 会在新任务开始时进入指令上下文。

该测试未修改项目文件，也没有触发内容发布操作。不过，这类测试只能说明当前环境中的加载结果；实际使用时仍应结合 Codex 版本、运行目录和配置状态进行确认。

三个容易踩的坑

1. 不要保存敏感信息

不要把密码、Cookie、API Key、访问令牌或客户隐私写入 AGENTS.md。它是项目指令文件，不是凭据管理工具。敏感数据应交由环境变量或专门的密钥管理服务保存。

2. 避免规则冲突

不要在多个目录中堆叠大量互相矛盾的要求。如果 Codex 的行为不符合预期，应重点检查：

• 全局目录中是否存在 AGENTS.override.md。
• 项目上层目录是否定义了通用规则。
• 当前工作目录附近是否有覆盖文件。
• 关键规则是否因总长度超过限制而被截断。

3. 修改后重新启动任务

Codex 会在每次运行开始时重新构建指令链，通常不需要手动清理缓存。但已经启动的旧任务不一定自动采用刚修改的内容，因此更新规则后，建议新建任务或会话进行验证。

总结

AGENTS.md 的核心价值，不是让 AI 永久记住用户，而是把项目要求沉淀为一份可见、可修改、可审查的工作约定。将目标、规则、安全边界和完成标准写清楚，可以减少重复提示，并让 Codex 的执行过程更加稳定、可控。

来源说明

• OpenAI：Custom instructions with AGENTS.md
• 原文记录的本地只读测试日期：2026 年 9 月 2 日
• 原文记录的资料核验日期：2026 年 9 月 2 日