目录 AGENTS.md 编写指南让 AI 理解你的项目 目录1. 什么是 AGENTS.md 工作原理2. 为什么需要 AGENTS.md 核心价值 实际效果✅ 什么时候需要❌ 什么时候不需要3. AGENTS.md 基础语法 文件格式️ 推荐结构 格式技巧1. 使用 emoji 增强可读性2. 使用表格整理信息3. 使用代码块展示命令 编码规范✅ 推荐做法❌ 禁止事项 命名约定️ 架构说明分层架构模块职责⚠️ 注意事项高风险区域已知问题常见错误 相关资源️ 架构分层 编码规范依赖注入日志规范异常处理JSON 规范⚠️ 注意事项高风险模块环境变量 编码规范命名约定代码风格禁止事项️ 项目结构⚠️ 注意事项 编码规范组件规范Hooks 规范状态管理命名约定⚠️ 注意事项 编码规范项目结构命名约定错误处理⚠️ 注意事项 共存方案7. 最佳实践✅ DO - 推荐做法❌ DONT - 避免事项 维护清单8. 常见问题❓ Q1AGENTS.md 必须放在根目录吗❓ Q2文件名必须是 AGENTS.md 吗❓ Q3可以使用其他格式吗❓ Q4AGENTS.md 会被上传到 OpenAI 吗❓ Q5AGENTS.md 多大合适❓ Q6多久更新一次❓ Q7可以多人协作维护吗9. 总结 核心要点 快速开始 下一步 系列文章导航 AGENTS.md 编写指南让 AI 理解你的项目 更新于 2026年5月 | ✍️ 原创文章转载请注明出处本系列共12篇本文是第3篇 目录什么是 AGENTS.md为什么需要 AGENTS.mdAGENTS.md 基础语法完整结构模板各语言项目示例与 CLAUDE.md 对比最佳实践常见问题总结1. 什么是 AGENTS.mdAGENTS.md是 Codex CLI 用来理解项目结构的配置文件类似于 Claude Code 的CLAUDE.md。当你在项目根目录放置AGENTS.md文件后Codex 启动时会自动读取它从而理解项目结构— 知道哪些目录是做什么的遵循编码规范— 按照你的风格写代码️知道常用命令— 直接运行正确的构建/测试命令⚠️避免常见错误— 了解项目的坑和注意事项理解业务逻辑— 知道项目的领域知识 工作原理启动 Codex → 读取 AGENTS.md → 理解项目上下文 → 更精准地帮你没有 AGENTS.md 时Codex 需要扫描目录结构猜测项目类型尝试各种命令可能犯错需要你纠正有 AGENTS.md 后Codex 直接知道项目是什么怎么构建怎么测试什么不能改2. 为什么需要 AGENTS.md 核心价值没有 AGENTS.md有 AGENTS.mdAI 需要探索项目AI 直接理解项目可能用错命令知道正确命令可能破坏约定遵循编码规范每次都要解释一次配置永久生效效率较低效率提升 3-5 倍 实际效果场景1运行测试# 没有 AGENTS.md你帮我运行测试 AI我试试... pytest tests/ ❌ AI那...npmtest❌ AI还是... mvntest❌ 你用这个命令 ./gradlewtest# 有 AGENTS.md你帮我运行测试 AI好的运行 ./gradlewtest✅场景2代码风格# 没有 AGENTS.mdAI我用 var 声明变量Java10 语法 你我们项目不用 var用显式类型# 有 AGENTS.md已声明禁止使用 varAI使用显式类型声明变量 ✅✅ 什么时候需要✅ 项目有特定的构建/测试命令✅ 团队有编码规范✅ 项目有复杂的目录结构✅ 有敏感文件不能修改✅ 有特定的 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 命名约定类型规则示例组件PascalCaseUserProfile.tsxhookscamelCase, use 前缀useAuth.ts工具函数camelCaseformatDate.ts常量UPPER_SNAKEAPI_BASE_URL类型PascalCase, T 前缀TUserState️ 架构说明分层架构Controller → Service → Repository → Database ↓ DTO/VO模块职责Controller: 接收请求参数校验调用 ServiceService: 业务逻辑事务管理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 -DtestUserServiceTest test # 单测某个方法 mvn -DtestUserServiceTest#shouldCreateUser test # 本地启动 mvn spring-boot:run # 带调试启动 mvn spring-boot:run -Dspring-boot.run.jvmArguments-agentlib:jdwptransportdt_socket,servery,suspendn,address5005️ 架构分层com.hxl.dataplatform ├── auth # 认证鉴权 ├── common # 通用基础设施 │ ├── annotation # 自定义注解 │ ├── config # 配置类 │ ├── constants # 常量 │ ├── exception # 异常处理 │ └── utils # 工具类 ├── model # 数据模型核心 │ ├── controller # 控制器 │ ├── service # 服务层 │ ├── repository # 数据访问层 │ └── entity # 实体类 └── integration # 外部集成 └── feishu # 飞书集成 编码规范依赖注入优先使用构造器注入使用RequiredArgsConstructorprivate finalServiceRequiredArgsConstructorpublicclassUserService{privatefinalUserRepositoryuserRepository;privatefinalRedisUtilredisUtil;}日志规范使用Slf4j注解禁止使用System.out.printlnSlf4jServicepublicclassUserService{publicvoidcreateUser(UserDTOdto){log.info(Creating user: {},dto.getUsername());}}异常处理业务异常使用BusinessException禁止在 Controller 吞异常thrownewBusinessException(UserErrorCode.USER_NOT_FOUND);JSON 规范全局强制SNAKE_CASEJava 字段保持camelCase⚠️ 注意事项高风险模块model/service/operation/— 模型写操作修改前必须运行测试auth/security/— 鉴权模块涉及安全环境变量BI_DB_URL,BI_DB_USERNAME,BI_DB_PASSWORDREDIS_URL_BI,REDIS_USERNAME_BI,REDIS_PASSWORD_BIFEISHU_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 . 编码规范命名约定类型规则示例模型PascalCaseUserProfile视图函数snake_caseget_user_list模板snake_caseuser_list.htmlURLkebab-case/api/user-profile/代码风格遵循 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.FCUserCardProps({user,onSelect}){return(div onClick{()onSelect(user.id)}{user.name}/div);};exportdefaultUserCard;Hooks 规范// ✅ 推荐自定义 HookconstuseUser(id:string){const[user,setUser]useStateTUser|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)Promisevoid;logout:()void;}constuseAuthStorecreateAuthState((set)({user:null,login:async(credentials){constuserawaitauthService.login(credentials);set({user});},logout:()set({user:null}),}));命名约定类型规则示例组件文件PascalCaseUserCard.tsxHook 文件camelCase, use 前缀useAuth.ts工具文件camelCaseformatDate.ts类型文件PascalCase, T 前缀TUser.ts常量文件UPPER_SNAKEAPI_ROUTES.ts⚠️ 注意事项禁止使用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/ # 文档命名约定类型规则示例包名小写单词user, order接口-er 后缀Reader, Writer结构体PascalCaseUserService函数PascalCase导出GetUser变量camelCaseuserID错误处理// ✅ 推荐包装错误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.md7. 最佳实践✅ DO - 推荐做法保持简洁不要写成小说精炼关键信息每个章节不超过 10 行突出重点使用 emoji 标记重要性加粗关键信息包含实用命令构建、测试、运行命令开发环境设置记录编码规范命名约定代码风格禁止事项说明架构目录结构模块职责数据流记录已知问题常见错误解决方案高风险区域定期更新项目演进时同步更新删除过时信息❌ DON’T - 避免事项不要过于冗长不要把整个 README 复制进来不要包含安装教程除非特殊不要包含敏感信息密码、密钥、Token内部 IP 地址不要写临时任务不要把 TODO 列表放进来不要记录 sprint 任务不要重复文档详细文档放 docs/AGENTS.md 只放关键信息不要忽略格式使用正确的 Markdown保持格式一致 维护清单项目名称和描述准确技术栈版本是最新的常用命令可以正常运行编码规范反映当前实践目录结构与实际一致已知问题仍然存在没有过时的信息8. 常见问题❓ Q1AGENTS.md 必须放在根目录吗A是的Codex 默认读取项目根目录的AGENTS.md。但你可以在子目录放置额外的 AGENTS.mdCodex 会合并它们project/ ├── AGENTS.md # 全局配置 ├── backend/ │ └── AGENTS.md # 后端特定配置 └── frontend/ └── AGENTS.md # 前端特定配置❓ Q2文件名必须是 AGENTS.md 吗A是的必须是AGENTS.md大写。其他名称如agents.md、Agents.md不会被识别。❓ Q3可以使用其他格式吗A不支持。必须是 Markdown 格式.md。❓ Q4AGENTS.md 会被上传到 OpenAI 吗A是的Codex 会将 AGENTS.md 的内容发送到 OpenAI 服务器作为上下文。安全建议不要包含密码、密钥等敏感信息不要包含内部 IP、私有域名企业用户考虑使用 Enterprise 版本❓ Q5AGENTS.md 多大合适A建议控制在50-200 行。太短 30 行信息不足太长 500 行消耗过多上下文最佳100-150 行❓ Q6多久更新一次A建议项目架构变更时技术栈升级时编码规范变更时每月检查一次是否有过时信息❓ Q7可以多人协作维护吗A可以建议使用 Git 管理版本PR 审核变更团队约定维护责任人9. 总结 核心要点AGENTS.md 是什么让 Codex 理解项目的配置文件为什么需要提升 AI 效率 3-5 倍怎么写项目画像 常用命令 编码规范 注意事项最佳实践简洁、实用、定期更新 快速开始在项目根目录创建AGENTS.md复制上面的通用模板根据项目实际情况修改提交到 Git 下一步第4篇[实战案例10个真实开发场景手把手教学]实践为你的项目创建 AGENTS.md社区分享你的 AGENTS.md 模板 系列文章导航上一篇[第2篇 - Codex CLI 命令大全CLI指令与斜杠命令速查手册]下一篇[第4篇 - 实战案例10个真实开发场景手把手教学]系列目录[Codex CLI 中文官方手册与使用指南12篇]遇到问题欢迎在评论区留言我会及时回复觉得有用点赞收藏帮助更多开发者