Codex CLI-03-AGENTS.md 编写指南：让 AI 理解你的项目

🚀 AGENTS.md 编写指南：让 AI 理解你的项目

📅 更新于 2026年5月 | ✍️ 原创文章，转载请注明出处

本系列共12篇，本文是第3篇

📌 目录

1. 什么是 AGENTS.md
2. 为什么需要 AGENTS.md
3. AGENTS.md 基础语法
4. 完整结构模板
5. 各语言项目示例
6. 与 CLAUDE.md 对比
7. 最佳实践
8. 常见问题
9. 总结

1. 什么是 AGENTS.md

AGENTS.md是 Codex CLI 用来理解项目结构的配置文件，类似于 Claude Code 的CLAUDE.md。

当你在项目根目录放置AGENTS.md文件后，Codex 启动时会自动读取它，从而：

• 🔍理解项目结构— 知道哪些目录是做什么的
• 📝遵循编码规范— 按照你的风格写代码
• 🛠️知道常用命令— 直接运行正确的构建/测试命令
• ⚠️避免常见错误— 了解项目的坑和注意事项
• 🎯理解业务逻辑— 知道项目的领域知识

💡 工作原理

启动 Codex → 读取 AGENTS.md → 理解项目上下文 → 更精准地帮你

没有 AGENTS.md 时，Codex 需要：

1. 扫描目录结构
2. 猜测项目类型
3. 尝试各种命令
4. 可能犯错需要你纠正

有 AGENTS.md 后，Codex 直接知道：

1. 项目是什么
2. 怎么构建
3. 怎么测试
4. 什么不能改

2. 为什么需要 AGENTS.md

🎯 核心价值

📊 实际效果

场景1：运行测试

# 没有 AGENTS.md你：帮我运行测试 AI：我试试... pytest tests/ ❌ AI：那...npmtest❌ AI：还是... mvntest❌ 你：用这个命令！ ./gradlewtest# 有 AGENTS.md你：帮我运行测试 AI：好的，运行 ./gradlewtest✅

场景2：代码风格

# 没有 AGENTS.mdAI：我用 var 声明变量（Java10+ 语法） 你：我们项目不用 var，用显式类型# 有 AGENTS.md（已声明：禁止使用 var）AI：使用显式类型声明变量 ✅

✅ 什么时候需要

• ✅ 项目有特定的构建/测试命令
• ✅ 团队有编码规范
• ✅ 项目有复杂的目录结构
• ✅ 有敏感文件不能修改
• ✅ 有特定的 Git 工作流
• ✅ 有业务术语需要解释

❌ 什么时候不需要

• ❌ 简单的脚本项目
• ❌ 一次性项目
• ❌ 纯配置文件目录

3. AGENTS.md 基础语法

📝 文件格式

AGENTS.md 使用标准 Markdown 语法，Codex 会解析以下元素：

# 标题（H1） ## 章节（H2） ### 子章节（H3） - 列表项 - 列表项 **加粗** 用于强调 `代码` 用于命令 ```代码块```用于多行代码 | 表格 | 内容 | |------|------|

🏗️ 推荐结构

# 项目名称 > 简短描述 ## 项目画像 - 技术栈 - 目录结构 ## 常用命令 - 构建 - 测试 - 运行 ## 编码规范 - 命名规则 - 代码风格 - 禁止事项 ## 架构说明 - 分层设计 - 模块职责 ## 注意事项 - 已知问题 - 常见错误

🎨 格式技巧

1. 使用 emoji 增强可读性

## ✅ 推荐做法 - 使用构造器注入 - 编写单元测试 ## ❌ 禁止事项 - 禁止使用 System.out.println - 禁止在 Controller 处理业务逻辑 ## ⚠️ 注意事项 - 修改前先运行测试 - 提交前检查代码风格

2. 使用表格整理信息

## 命名约定 | 类型 | 规则 | 示例 | |------|------|------| | 类名 | PascalCase | UserService | | 方法名 | camelCase | getUserById | | 常量 | UPPER_SNAKE | MAX_RETRY_COUNT | | 包名 | 小写 | com.example.service |

3. 使用代码块展示命令

## 常用命令 ```bash # 构建 mvn clean package -DskipTests # 测试 mvn test # 运行 mvn spring-boot:run

--- ## 4. 完整结构模板 ### 📋 通用模板 ```markdown # 项目名称 > 一句话描述项目定位和核心功能 ## 📋 项目画像 - **项目名**: project-name - **定位**: [一句话说明] - **技术栈**: [主要技术] - **启动类/入口**: [文件路径] - **默认端口**: [端口号] ## 🏗️ 目录结构

project/
├── src/ # 源代码
│ ├── main/ # 主代码
│ └── test/ # 测试代码
├── docs/ # 文档
├── scripts/ # 脚本
└── config/ # 配置

## 🔧 常用命令 ```bash # 安装依赖 npm install # 构建 npm run build # 测试 npm test # 开发模式 npm run dev # 代码检查 npm run lint # 格式化 npm run format

📐 编码规范

✅ 推荐做法

• 使用 TypeScript 严格模式
• 优先使用 const，必要时用 let
• 函数不超过 50 行
• 文件不超过 300 行

❌ 禁止事项

• 禁止使用 any 类型
• 禁止使用 console.log（用 logger）
• 禁止直接修改 state
• 禁止在组件内发请求（用 hooks）

📏 命名约定

🏛️ 架构说明

分层架构

Controller → Service → Repository → Database ↓ DTO/VO

模块职责

• Controller: 接收请求，参数校验，调用 Service
• Service: 业务逻辑，事务管理
• Repository: 数据访问，SQL 操作
• DTO: 数据传输对象
• VO: 视图对象

⚠️ 注意事项

高风险区域

• src/core/— 核心模块，修改前必须运行全部测试
• config/production.yaml— 生产配置，禁止提交敏感信息
• database/migrations/— 数据库迁移，不可逆操作

已知问题

• Redis 连接在高并发下可能超时，已添加重试机制
• 文件上传大小限制 10MB，超过会返回 413

常见错误

错误1:Module not found

• 原因: 未安装依赖
• 解决:npm install

错误2:Permission denied

• 原因: 文件权限问题
• 解决:chmod +x script.sh

🔗 相关资源

• 项目文档
• API 文档
• 部署指南

--- ## 5. 各语言项目示例 ### ☕ Java/Spring Boot 项目 ```markdown # Bi-Platform > 数据资产平台 Java 后端，对接独立前端 ## 📋 项目画像 - **项目名**: bi-platform - **定位**: 数据资产平台 Java 后端 - **主包**: com.hxl.dataplatform - **启动类**: com.hxl.dataplatform.DataPlatformApplication - **技术栈**: Java 21, Spring Boot 3.3.5, MyBatis-Plus, MySQL, Redis, Kafka - **默认地址**: http://localhost:55133/bi-platform - **接口文档**: http://localhost:55133/bi-platform/doc.html ## 🔧 常用命令 ```bash # 编译 mvn clean package -DskipTests # 全量测试 mvn clean test # 单测某个类 mvn -Dtest=UserServiceTest test # 单测某个方法 mvn -Dtest=UserServiceTest#shouldCreateUser test # 本地启动 mvn spring-boot:run # 带调试启动 mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"

🏗️ 架构分层

com.hxl.dataplatform ├── auth # 认证鉴权 ├── common # 通用基础设施 │ ├── annotation # 自定义注解 │ ├── config # 配置类 │ ├── constants # 常量 │ ├── exception # 异常处理 │ └── utils # 工具类 ├── model # 数据模型核心 │ ├── controller # 控制器 │ ├── service # 服务层 │ ├── repository # 数据访问层 │ └── entity # 实体类 └── integration # 外部集成 └── feishu # 飞书集成

📐 编码规范

依赖注入

• 优先使用构造器注入
• 使用@RequiredArgsConstructor+private final

@Service@RequiredArgsConstructorpublicclassUserService{privatefinalUserRepositoryuserRepository;privatefinalRedisUtilredisUtil;}

日志规范

• 使用@Slf4j注解
• 禁止使用System.out.println

@Slf4j@ServicepublicclassUserService{publicvoidcreateUser(UserDTOdto){log.info("Creating user: {}",dto.getUsername());}}

异常处理

• 业务异常使用BusinessException
• 禁止在 Controller 吞异常

thrownewBusinessException(UserErrorCode.USER_NOT_FOUND);

JSON 规范

• 全局强制SNAKE_CASE
• Java 字段保持camelCase

⚠️ 注意事项

高风险模块

• model/service/operation/— 模型写操作，修改前必须运行测试
• auth/security/— 鉴权模块，涉及安全

环境变量

• BI_DB_URL,BI_DB_USERNAME,BI_DB_PASSWORD
• REDIS_URL_BI,REDIS_USERNAME_BI,REDIS_PASSWORD_BI
• FEISHU_APP_ID,FEISHU_APP_SECRET

禁止将凭证硬编码到代码中！

### 🐍 Python/Django 项目 ```markdown # My Django Project > 基于 Django 的 Web 应用 ## 📋 项目画像 - **技术栈**: Python 3.11, Django 5.0, PostgreSQL, Redis, Celery - **启动命令**: `python manage.py runserver` - **默认端口**: 8000 ## 🔧 常用命令 ```bash # 安装依赖 pip install -r requirements.txt # 数据库迁移 python manage.py makemigrations python manage.py migrate # 创建超级用户 python manage.py createsuperuser # 运行测试 python manage.py test # 运行 Celery celery -A myproject worker -l info # 代码检查 flake8 . black . isort .

📐 编码规范

命名约定

代码风格

• 遵循 PEP 8
• 使用 type hints
• 函数必须有 docstring
• 使用black格式化

禁止事项

• 禁止使用print()，用logging
• 禁止在视图中写业务逻辑
• 禁止硬编码配置

🏛️ 项目结构

myproject/ ├── apps/ # Django 应用 │ ├── users/ # 用户应用 │ ├── products/ # 产品应用 │ └── orders/ # 订单应用 ├── config/ # 项目配置 │ ├── settings/ # 环境配置 │ ├── urls.py # URL 路由 │ └── celery.py # Celery 配置 ├── utils/ # 工具函数 ├── templates/ # 模板文件 ├── static/ # 静态文件 └── docs/ # 项目文档

⚠️ 注意事项

• 修改模型后必须运行makemigrations
• 生产环境使用gunicorn而不是runserver
• 敏感配置使用环境变量

### ⚛️ React/TypeScript 项目 ```markdown # My React App > 基于 React 18 + TypeScript 的前端应用 ## 📋 项目画像 - **技术栈**: React 18, TypeScript 5, Vite, TailwindCSS, Zustand - **启动命令**: `npm run dev` - **默认端口**: 5173 ## 🔧 常用命令 ```bash # 安装依赖 npm install # 开发模式 npm run dev # 构建 npm run build # 预览构建结果 npm run preview # 测试 npm run test # 代码检查 npm run lint # 格式化 npm run format # 类型检查 npm run type-check

📐 编码规范

组件规范

// ✅ 推荐：函数组件 + TypeScriptinterfaceUserCardProps{user:TUser;onSelect:(id:string)=>void;}constUserCard:React.FC<UserCardProps>=({user,onSelect})=>{return(<div onClick={()=>onSelect(user.id)}>{user.name}</div>);};exportdefaultUserCard;

Hooks 规范

// ✅ 推荐：自定义 HookconstuseUser=(id:string)=>{const[user,setUser]=useState<TUser|null>(null);const[loading,setLoading]=useState(true);useEffect(()=>{fetchUser(id).then(setUser).finally(()=>setLoading(false));},[id]);return{user,loading};};

状态管理

// ✅ 推荐：ZustandinterfaceAuthState{user:TUser|null;login:(credentials:TCredentials)=>Promise<void>;logout:()=>void;}constuseAuthStore=create<AuthState>((set)=>({user:null,login:async(credentials)=>{constuser=awaitauthService.login(credentials);set({user});},logout:()=>set({user:null}),}));

命名约定

⚠️ 注意事项

• 禁止使用any类型
• 禁止使用console.log，用logger
• 组件不超过 200 行
• 使用 React.memo 优化渲染

### 🐹 Go 项目 ```markdown # My Go Service > 基于 Go 的微服务 ## 📋 项目画像 - **技术栈**: Go 1.22, Gin, GORM, PostgreSQL, Redis - **启动命令**: `go run main.go` - **默认端口**: 8080 ## 🔧 常用命令 ```bash # 安装依赖 go mod tidy # 运行 go run main.go # 构建 go build -o bin/app # 测试 go test ./... # 测试覆盖率 go test -cover ./... # 代码检查 golangci-lint run # 格式化 gofmt -w . # 生成文档 go doc ./...

📐 编码规范

项目结构

my-service/ ├── cmd/ # 入口 │ └── server/ │ └── main.go ├── internal/ # 私有代码 │ ├── handler/ # HTTP 处理器 │ ├── service/ # 业务逻辑 │ ├── repository/ # 数据访问 │ └── model/ # 数据模型 ├── pkg/ # 公共库 ├── api/ # API 定义 ├── configs/ # 配置文件 └── docs/ # 文档

命名约定

错误处理

// ✅ 推荐：包装错误iferr!=nil{returnfmt.Errorf("failed to get user: %w",err)}// ❌ 禁止：忽略错误user,_:=repo.GetUser(id)

⚠️ 注意事项

• 禁止使用panic处理业务错误
• 禁止在init()中做复杂操作
• 使用context传递请求上下文
• 数据库操作必须使用事务

--- ## 6. 与 CLAUDE.md 对比 ### 📊 对比表 | 特性 | AGENTS.md (Codex) | CLAUDE.md (Claude Code) | |------|-------------------|-------------------------| | **用途** | 让 Codex 理解项目 | 让 Claude Code 理解项目 | | **格式** | Markdown | Markdown | | **语法** | 基本相同 | 基本相同 | | **位置** | 项目根目录 | 项目根目录 | | **加载时机** | 启动时自动加载 | 启动时自动加载 | | **多文件支持** | 支持（子目录可覆盖） | 支持（子目录可覆盖） | ### 🔄 迁移指南 如果你已有 `CLAUDE.md`，迁移到 `AGENTS.md` 很简单： ```bash # 1. 复制文件 cp CLAUDE.md AGENTS.md # 2. 修改项目名称（如有） sed -i 's/Claude Code/Codex CLI/g' AGENTS.md # 3. 添加 Codex 特定配置（可选） # 如：审批模式、沙箱设置等

💡 共存方案

如果同时使用 Codex 和 Claude Code，可以：

# 方案1：维护两份文件（内容相同）CLAUDE.md AGENTS.md# 方案2：使用符号链接ln-sCLAUDE.md AGENTS.md# 方案3：使用公共文件# CLAUDE.md 和 AGENTS.md 都包含：# include: project-conventions.md

7. 最佳实践

✅ DO - 推荐做法

1. 保持简洁

   • 不要写成小说，精炼关键信息
   • 每个章节不超过 10 行

2. 突出重点

   • 使用 emoji 标记重要性
   • 加粗关键信息

3. 包含实用命令

   • 构建、测试、运行命令
   • 开发环境设置

4. 记录编码规范

   • 命名约定
   • 代码风格
   • 禁止事项

5. 说明架构

   • 目录结构
   • 模块职责
   • 数据流

6. 记录已知问题

   • 常见错误
   • 解决方案
   • 高风险区域

7. 定期更新

   • 项目演进时同步更新
   • 删除过时信息

❌ DON’T - 避免事项

1. 不要过于冗长

   • 不要把整个 README 复制进来
   • 不要包含安装教程（除非特殊）

2. 不要包含敏感信息

   • 密码、密钥、Token
   • 内部 IP 地址

3. 不要写临时任务

   • 不要把 TODO 列表放进来
   • 不要记录 sprint 任务

4. 不要重复文档

   • 详细文档放 docs/
   • AGENTS.md 只放关键信息

5. 不要忽略格式

   • 使用正确的 Markdown
   • 保持格式一致

📝 维护清单

• 项目名称和描述准确
• 技术栈版本是最新的
• 常用命令可以正常运行
• 编码规范反映当前实践
• 目录结构与实际一致
• 已知问题仍然存在
• 没有过时的信息

8. 常见问题

❓ Q1：AGENTS.md 必须放在根目录吗？

A：是的，Codex 默认读取项目根目录的AGENTS.md。

但你可以在子目录放置额外的 AGENTS.md，Codex 会合并它们：

project/ ├── AGENTS.md # 全局配置 ├── backend/ │ └── AGENTS.md # 后端特定配置 └── frontend/ └── AGENTS.md # 前端特定配置

❓ Q2：文件名必须是 AGENTS.md 吗？

A：是的，必须是AGENTS.md（大写）。其他名称如agents.md、Agents.md不会被识别。

❓ Q3：可以使用其他格式吗？

A：不支持。必须是 Markdown 格式（.md）。

❓ Q4：AGENTS.md 会被上传到 OpenAI 吗？

A：是的，Codex 会将 AGENTS.md 的内容发送到 OpenAI 服务器作为上下文。

安全建议：

• 不要包含密码、密钥等敏感信息
• 不要包含内部 IP、私有域名
• 企业用户考虑使用 Enterprise 版本

❓ Q5：AGENTS.md 多大合适？

A：建议控制在50-200 行。

• 太短（< 30 行）：信息不足
• 太长（> 500 行）：消耗过多上下文
• 最佳：100-150 行

❓ Q6：多久更新一次？

A：建议：

• 项目架构变更时
• 技术栈升级时
• 编码规范变更时
• 每月检查一次是否有过时信息

❓ Q7：可以多人协作维护吗？

A：可以，建议：

• 使用 Git 管理版本
• PR 审核变更
• 团队约定维护责任人

9. 总结

🎯 核心要点

1. AGENTS.md 是什么：让 Codex 理解项目的配置文件
2. 为什么需要：提升 AI 效率 3-5 倍
3. 怎么写：项目画像 + 常用命令 + 编码规范 + 注意事项
4. 最佳实践：简洁、实用、定期更新

📋 快速开始

1. 在项目根目录创建AGENTS.md
2. 复制上面的通用模板
3. 根据项目实际情况修改
4. 提交到 Git

📚 下一步

• 📖第4篇：[实战案例：10个真实开发场景手把手教学]
• 🔧实践：为你的项目创建 AGENTS.md
• 💬社区：分享你的 AGENTS.md 模板

📝 系列文章导航

• 上一篇：[第2篇 - Codex CLI 命令大全：CLI指令与斜杠命令速查手册]
• 下一篇：[第4篇 - 实战案例：10个真实开发场景手把手教学]
• 系列目录：[Codex CLI 中文官方手册与使用指南（12篇）]

💡遇到问题？欢迎在评论区留言，我会及时回复！

👍觉得有用？点赞收藏，帮助更多开发者！