Codex AGENTS.md

AGENTS.md 是 Codex 的自定义指令文件，允许你为 Codex 设置全局指导和工作流规范。本节详细介绍如何创建和使用 AGENTS.md。

什么是 AGENTS.md？

AGENTS.md 是 Codex 在执行任何工作之前读取的指令文件，允许你：

  • 设置全局编码规范
  • 定义项目特定的工作流程
  • 为不同目录提供不同的指导
  • 标准化团队的开发实践
通过 AGENTS.md，你可以确保 Codex 在整个代码库中遵循一致的规范。

Codex 如何发现指南

Codex 按以下优先级构建指令链：

优先级顺序

  1. 全局范围：读取 ~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md
  2. 项目范围：从项目根目录到当前目录，逐层检查 AGENTS.override.md 和 AGENTS.md
  3. 就近优先：更接近当前目录的文件会覆盖之前的指导
靠近当前目录的指令会覆盖之前的指导，这样可以在子目录中为特定模块提供专门的规则。

创建全局指导

基础配置

创建全局 AGENTS.md

# 创建全局配置目录
mkdir -p ~/.codex

# 创建全局指导文件
touch ~/.codex/AGENTS.md

全局指导示例

全局指导内容

# Codex 全局指导

## 编码规范
- 使用 4 空格缩进
- 每行最多 100 个字符
- 始终使用 const/let，不使用 var

## 代码质量
- 所有导出的函数必须包含 JSDoc 注释
- 添加适当的错误处理
- 避免使用 console.log，使用项目中的日志库

## 测试要求
- 新功能必须包含测试
- 使用项目指定的测试框架

## Git 提交
- 使用 Conventional Commits 格式
- 提交信息必须描述性地说明"为什么"

临时覆盖

使用 ~/.codex/AGENTS.override.md 设置临时全局覆盖：

临时覆盖

# 临时覆盖 - 调试模式

## 特殊规则
- 启用详细日志输出
- 添加调试注释
- 跳过性能优化以加快迭代速度
AGENTS.override.md 用于临时覆盖，不会影响正常的 AGENTS.md 配置。

项目级指导

仓库级配置

在仓库根目录创建 AGENTS.md：

项目 AGENTS.md

# 项目编码规范

## 技术栈
- 前端：React + TypeScript
- 后端：Python FastAPI
- 数据库：PostgreSQL

## 前端规范
- 使用函数组件，不使用类组件
- 使用 Tailwind CSS 进行样式
- 组件文件以 .tsx 结尾

## 后端规范
- 使用 Pydantic 进行数据验证
- 所有 API 端点必须有类型注解
- 使用 async/await 处理异步操作

## 数据库
- 使用 SQLAlchemy ORM
- 避免原始 SQL 查询
- 所有表必须有 created_at 和 updated_at 字段

子目录覆盖

在子目录中创建 AGENTS.override.md 提供专门的规则：

子目录配置

# src/auth/ 模块特定规则

## 安全要求
- 所有密码必须 bcrypt 加密
- 实现速率限制
- 添加审计日志

## 额外审查
- 强制代码审查
- 检查 SQL 注入
- 验证认证流程
子目录的规则会覆盖父目录的规则，确保模块特定的规范优先。

自定义回退文件名

如果你的项目使用其他文件名，可以配置回退：

配置回退文件名

# 支持其他命名约定
project_doc_fallback_filenames = [
    "TEAM_GUIDE.md",
    "CONTRIBUTING.md",
    ".codex.md"
]

代码审查指南

在 AGENTS.md 中添加审查指南：

审查指南

## Review guidelines

- Don't log PII (个人身份信息)
- Verify that authentication middleware wraps every route
- Check for SQL injection vulnerabilities
- Ensure error messages don't leak sensitive information
- Treat documentation typos as P1 issues

问题优先级

优先级说明
P0严重问题 - 安全漏洞、崩溃、数据丢失
P1重要问题 - 功能错误、性能问题
P2次要问题 - 代码风格、文档问题
在 GitHub 集成中，Codex 默认只标记 P0 和 P1 问题。

验证与故障排除

验证配置

验证 AGENTS.md

# 测试 AGENTS.md 配置
codex --ask-for-approval never "Summarize the current instructions."

检查日志

查看 Codex 日志确认加载：

tail -f ~/.codex/log/codex-tui.log

常见问题

问题原因解决方案
指令不生效文件为空确保文件包含实际内容
被隐藏覆盖存在 override 文件检查 AGENTS.override.md
内容被截断超过 32 KiB 限制精简内容或拆分文件
Codex 默认会在组合大小达到 32 KiB 时停止读取。

最佳实践

  • 保持简洁：只包含必要的规则
  • 分层设计：全局 -> 项目 -> 模块
  • 团队同步：将项目 AGENTS.md 提交到版本控制
  • 定期审查：更新规则以适应项目变化
好的 AGENTS.md 配置可以让整个团队受益，确保 Codex 的行为符合团队期望。

常见问题

Q: AGENTS.md 文件多大合适？

建议控制在几 KB 以内，过大的文件会被截断（默认 32 KiB）。

Q: 可以禁用项目级 AGENTS.md 吗？

可以，使用 project_doc_fallback_filenames = [] 配置为空数组。

Q: 子目录和父目录的规则冲突怎么办？

子目录的规则会覆盖父目录的规则。

Q: 如何临时覆盖项目规则？

使用 AGENTS.override.md 文件进行临时覆盖。