自学教程

Codex AGENTS.md

Codex 教程

AGENTS.md 是 Codex 项目级自然语言规则文件，放置在项目根目录，属于静态软性规则。它以 Markdown 文本描述项目背景、架构约束、编码规范、修改边界、输出格式，Codex 在会话初始化时读取全文，指导主代理、子代理在执行任务时遵守约定。它和 rules.toml 硬拦截规则互为补充：AGENTS.md 侧重行为指引，rules.toml 侧重强制拦截。

一、文件基础信息

1.1 存放位置与加载优先级

  • 路径：项目根目录 AGENTS.md，和 .codex 文件夹同级，可提交到Git仓库，团队共享。
  • 加载顺序：会话启动时自动读取，项目 AGENTS.md 优先级高于用户全局自然语言规则。
  • 生效范围：默认作用于主代理，派生的子代理默认继承这份规则；子代理配置可单独关闭继承，使用独立指令。

注意：AGENTS.md 是自然语言指引，不是强制拦截器。Codex 会尽力遵循，但不会自动阻断操作；高危文件保护、命令黑名单这类强制限制，需要写在 rules.toml。

1.2 AGENTS.md 适用场景

✅ 适合写入 AGENTS.md

  • 项目架构说明、技术栈介绍、目录结构说明
  • 编码规范、命名约定、注释要求、代码风格
  • 代码修改约束：哪些模块不能大幅重构、新增代码的规范
  • 输出格式约定：文档、报告、代码评审结果的输出模板
  • 业务背景、业务限制、数据库设计约定

❌ 不适合写在 AGENTS.md

  • 高危命令拦截、文件锁定保护（放到 rules.toml）
  • 事件触发脚本、自动化校验（放到 Hooks）
  • MCP服务、子代理配置（放到 .codex/config.toml 或对应toml文件）

二、标准 AGENTS.md 模板结构

推荐固定章节，方便团队维护，Codex 更容易理解和执行。

# AGENTS.md 项目代理规则
## 项目概述
简要描述项目用途、技术栈、核心模块，让Codex快速理解项目背景。## 架构约束
定义整体架构原则，禁止跨层调用、禁止随意修改核心底层模块等。
## 编码规范
语言、命名、注释、错误处理、单元测试相关要求。
## 文件修改限制
说明哪些目录仅可读，哪些文件修改需要额外说明。
## 输出格式规范
定义代码评审、文档、报告的输出格式。
## 任务执行约束
执行任务的行为准则：先检索代码，再修改；修改前说明变更范围等。

完整示例 AGENTS.md

# AGENTS.md
## 项目概述
前端项目，技术栈 Vue3 + TypeScript + Vite。项目包含业务页面、公共组件、工具函数。## 架构约束
1. 业务逻辑统一放在 composables，不要直接写在模板内。
2. 组件拆分遵循单一职责，禁止超大单文件组件。
3. 不要修改底层 src/core 模块，如需改动必须先说明理由。
## 编码规范
1. 变量、函数使用小驼峰命名，组件使用大驼峰。
2. 新增功能必须补充类型定义，尽量使用interface。
3. 新增组件/接口，需要编写基础注释。
## 文件修改限制
1. public/ 静态资源仅读取，不做删除操作。
2. 修改 .env 文件前，必须提示人工确认。
## 输出格式规范
代码修改完成后，输出变更清单：【文件路径】变更简述。
## 任务执行约束
1. 修改代码前，先检索相关文件，理解上下文。
2. 大规模重构任务，先输出重构方案，确认后再修改代码。
3. 不要自动删除代码，优先注释保留，附带说明。

三、关键语法与编写技巧

  1. 使用简短条目列表，不要大段长文本。Codex更容易读取、理解每条约束。
  2. 使用明确的动词：禁止、必须、应当、优先，减少模糊描述。
  3. 区分硬性约定和建议：“必须”代表强制要求；“建议”代表优化参考。
  4. 可以引用项目目录结构，指定目录范围，限制Codex的检索和修改边界。
  5. 支持引用项目内其他文档，例如 参考 docs/api.md，Codex会自动读取。

限制：文件不宜过长，建议控制在 2000 字符以内。过长会占用大量上下文，增加Token消耗，降低执行效率。

四、AGENTS.md 与子代理

默认情况下，由主代理派生的子代理自动继承 AGENTS.md 的全部规则。
在子代理配置 .codex/agents/xxx.toml 中，可以关闭继承：

name = "code-reviewer"
inherit_agents_md = false
developer_instructions = "独立评审规则，不继承项目AGENTS.md"

关闭继承后，该子代理不再读取根目录AGENTS.md，仅使用自身配置内的指令。

五、AGENTS.md 和 rules.toml 对比

项目AGENTS.mdrules.toml
文件类型Markdown自然语言TOML声明式配置
作用类型软性指引，行为规范硬性强制拦截
核心能力定义项目背景、编码风格、输出格式文件保护、命令黑名单、审批控制
执行时机会话初始化加载，作为系统提示一部分工具调用前校验，违规直接拦截
能否被子代理继承默认继承，可手动关闭默认继承，可单独覆盖

六、管理斜杆命令

Codex 内置命令，快速查看、校验、重载 AGENTS.md：

# 查看当前加载的 AGENTS.md 内容
/agents-md show校验AGENTS.md语法与长度，给出优化建议
/agents-md validate
修改文件后重载，无需重启会话
/agents-md reload

七、最佳实践

  1. 只写项目独有规则，通用编码规范尽量放到 Agent Skills，避免AGENTS.md臃肿。
  2. 定期精简，删除过时约束，控制文本长度，减少上下文开销。
  3. 敏感文件、高危命令保护，不要依赖AGENTS.md，必须在rules.toml配置强制拦截。
  4. 团队协作时，修改AGENTS.md如同修改代码，走代码评审流程。
  5. 测试验证：修改后执行 /agents-md validate，查看Codex识别效果。
  6. 非交互模式会自动加载AGENTS.md，跨平台环境下文件内容全平台通用。

八、常见问题

Q：修改 AGENTS.md 需要重启Codex会话吗？
A：不需要，执行 /agents-md reload 即可重新加载。

Q：AGENTS.md 可以在全局配置里定义吗？
A：全局可以设置全局自然语言规则，但项目根目录AGENTS.md优先级更高，适合项目专属约束。

Q：AGENTS.md 能否阻止Codex删除文件？
A：不能。AGENTS.md只是指引，Codex仍可执行删除操作。阻止文件删除必须配置 rules.toml 的 file_protection。

Q：非交互模式（codex exec）是否加载AGENTS.md？
A：会自动加载，和交互模式行为一致。

九、总结

AGENTS.md 是 Codex 项目的自然语言规则文件，用于描述项目背景、架构约束、编码规范与输出要求，作为软性指引约束主代理与子代理的行为。它和 rules.toml 配合使用，AGENTS.md负责“告诉代理怎么做”，rules.toml负责“拦截危险操作”。

文件跨平台通用，支持团队Git共享，支持子代理继承或单独关闭继承。编写时保持简洁清晰，避免写入强制拦截类规则，能够大幅提升Codex输出代码的一致性，贴合项目的开发规范。

标签：

0 条笔记