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

[🚀 AGENTS.md 编写指南：让 AI 理解你的项目](#🚀 AGENTS.md 编写指南：让 AI 理解你的项目)
- [📌 目录](#📌 目录)
- [1. 什么是 AGENTS.md](#1. 什么是 AGENTS.md)
- - [💡 工作原理](#💡 工作原理)
- [2. 为什么需要 AGENTS.md](#2. 为什么需要 AGENTS.md)
- - [🎯 核心价值](#🎯 核心价值)
  - [📊 实际效果](#📊 实际效果)
  - [✅ 什么时候需要](#✅ 什么时候需要)
  - [❌ 什么时候不需要](#❌ 什么时候不需要)
- [3. AGENTS.md 基础语法](#3. AGENTS.md 基础语法)
- - [📝 文件格式](#📝 文件格式)
  - [🏗️ 推荐结构](#🏗️ 推荐结构)
  - [🎨 格式技巧](#🎨 格式技巧)
  - - [1. 使用 emoji 增强可读性](#1. 使用 emoji 增强可读性)
    - [2. 使用表格整理信息](#2. 使用表格整理信息)
    - [3. 使用代码块展示命令](#3. 使用代码块展示命令)
- [📐 编码规范](#📐 编码规范)
- - [✅ 推荐做法](#✅ 推荐做法)
  - [❌ 禁止事项](#❌ 禁止事项)
  - [📏 命名约定](#📏 命名约定)
- [🏛️ 架构说明](#🏛️ 架构说明)
- - 分层架构
  - 模块职责
- [⚠️ 注意事项](#⚠️ 注意事项)
- - 高风险区域
  - 已知问题
  - 常见错误
- [🔗 相关资源](#🔗 相关资源)
- [🏗️ 架构分层](#🏗️ 架构分层)
- [📐 编码规范](#📐 编码规范)
- - 依赖注入
  - 日志规范
  - 异常处理
  - [JSON 规范](#JSON 规范)
- [⚠️ 注意事项](#⚠️ 注意事项)
- - 高风险模块
  - 环境变量
- [📐 编码规范](#📐 编码规范)
- - 命名约定
  - 代码风格
  - 禁止事项
- [🏛️ 项目结构](#🏛️ 项目结构)
- [⚠️ 注意事项](#⚠️ 注意事项)
- [📐 编码规范](#📐 编码规范)
- - 组件规范
  - [Hooks 规范](#Hooks 规范)
  - 状态管理
  - 命名约定
- [⚠️ 注意事项](#⚠️ 注意事项)
- [📐 编码规范](#📐 编码规范)
- - 项目结构
  - 命名约定
  - 错误处理
- [⚠️ 注意事项](#⚠️ 注意事项)
- - [💡 共存方案](#💡 共存方案)
- [7. 最佳实践](#7. 最佳实践)
- - [✅ DO - 推荐做法](#✅ DO - 推荐做法)
  - [❌ DON'T - 避免事项](#❌ DON'T - 避免事项)
  - [📝 维护清单](#📝 维护清单)
- [8. 常见问题](#8. 常见问题)
- - [❓ Q1：AGENTS.md 必须放在根目录吗？](#❓ Q1：AGENTS.md 必须放在根目录吗？)
  - [❓ Q2：文件名必须是 AGENTS.md 吗？](#❓ Q2：文件名必须是 AGENTS.md 吗？)
  - [❓ Q3：可以使用其他格式吗？](#❓ Q3：可以使用其他格式吗？)
  - [❓ Q4：AGENTS.md 会被上传到 OpenAI 吗？](#❓ Q4：AGENTS.md 会被上传到 OpenAI 吗？)
  - [❓ Q5：AGENTS.md 多大合适？](#❓ Q5：AGENTS.md 多大合适？)
  - [❓ Q6：多久更新一次？](#❓ Q6：多久更新一次？)
  - [❓ Q7：可以多人协作维护吗？](#❓ Q7：可以多人协作维护吗？)
- [9. 总结](#9. 总结)
- - [🎯 核心要点](#🎯 核心要点)
  - [📋 快速开始](#📋 快速开始)
  - [📚 下一步](#📚 下一步)
- [📝 系列文章导航](#📝 系列文章导航)

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

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

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

📌 目录

[什么是 AGENTS.md](#什么是 AGENTS.md)
[为什么需要 AGENTS.md](#为什么需要 AGENTS.md)
[AGENTS.md 基础语法](#AGENTS.md 基础语法)
完整结构模板
各语言项目示例
[与 CLAUDE.md 对比](#与 CLAUDE.md 对比)
最佳实践
常见问题
总结

1. 什么是 AGENTS.md

AGENTS.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.md
AI 需要探索项目	AI 直接理解项目
可能用错命令	知道正确命令
可能破坏约定	遵循编码规范
每次都要解释	一次配置永久生效
效率较低	效率提升 3-5 倍

📊 实际效果

场景1：运行测试

bash 复制代码

# 没有 AGENTS.md
你：帮我运行测试
AI：我试试... pytest tests/ ❌
AI：那... npm test ❌
AI：还是... mvn test ❌
你：用这个命令！ ./gradlew test

# 有 AGENTS.md
你：帮我运行测试
AI：好的，运行 ./gradlew test ✅

场景2：代码风格

bash 复制代码

# 没有 AGENTS.md
AI：我用 var 声明变量（Java 10+ 语法）
你：我们项目不用 var，用显式类型

# 有 AGENTS.md（已声明：禁止使用 var）
AI：使用显式类型声明变量 ✅

✅ 什么时候需要

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

❌ 什么时候不需要

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

3. AGENTS.md 基础语法

📝 文件格式

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

markdown 复制代码

# 标题（H1）

## 章节（H2）

### 子章节（H3）

- 列表项
- 列表项

**加粗** 用于强调

`代码` 用于命令

```代码块```用于多行代码

| 表格 | 内容 |
|------|------|

🏗️ 推荐结构

markdown 复制代码

# 项目名称

> 简短描述

## 项目画像
- 技术栈
- 目录结构

## 常用命令
- 构建
- 测试
- 运行

## 编码规范
- 命名规则
- 代码风格
- 禁止事项

## 架构说明
- 分层设计
- 模块职责

## 注意事项
- 已知问题
- 常见错误

🎨 格式技巧

1. 使用 emoji 增强可读性

markdown 复制代码

## ✅ 推荐做法
- 使用构造器注入
- 编写单元测试

## ❌ 禁止事项
- 禁止使用 System.out.println
- 禁止在 Controller 处理业务逻辑

## ⚠️ 注意事项
- 修改前先运行测试
- 提交前检查代码风格

2. 使用表格整理信息

markdown 复制代码

## 命名约定

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

3. 使用代码块展示命令

markdown 复制代码

## 常用命令

```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）

📏 命名约定

类型	规则	示例
组件	PascalCase	UserProfile.tsx
hooks	camelCase, use 前缀	useAuth.ts
工具函数	camelCase	formatDate.ts
常量	UPPER_SNAKE	API_BASE_URL
类型	PascalCase, T 前缀	TUserState

🏛️ 架构说明

分层架构

复制代码

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

java 复制代码

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;
    private final RedisUtil redisUtil;
}

日志规范

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

java 复制代码

@Slf4j
@Service
public class UserService {
    public void createUser(UserDTO dto) {
        log.info("Creating user: {}", dto.getUsername());
    }
}

异常处理

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

java 复制代码

throw new BusinessException(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 .

📐 编码规范

命名约定

类型	规则	示例
模型	PascalCase	UserProfile
视图函数	snake_case	get_user_list
模板	snake_case	user_list.html
URL	kebab-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

📐 编码规范

组件规范

typescript 复制代码

// ✅ 推荐：函数组件 + TypeScript
interface UserCardProps {
  user: TUser;
  onSelect: (id: string) => void;
}

const UserCard: React.FC<UserCardProps> = ({ user, onSelect }) => {
  return (
    <div onClick={() => onSelect(user.id)}>
      {user.name}
    </div>
  );
};

export default UserCard;

Hooks 规范

typescript 复制代码

// ✅ 推荐：自定义 Hook
const useUser = (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 };
};

状态管理

typescript 复制代码

// ✅ 推荐：Zustand
interface AuthState {
  user: TUser | null;
  login: (credentials: TCredentials) => Promise<void>;
  logout: () => void;
}

const useAuthStore = create<AuthState>((set) => ({
  user: null,
  login: async (credentials) => {
    const user = await authService.login(credentials);
    set({ user });
  },
  logout: () => set({ user: null }),
}));

命名约定

类型	规则	示例
组件文件	PascalCase	UserCard.tsx
Hook 文件	camelCase, use 前缀	useAuth.ts
工具文件	camelCase	formatDate.ts
类型文件	PascalCase, T 前缀	TUser.ts
常量文件	UPPER_SNAKE	API_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
结构体	PascalCase	UserService
函数	PascalCase（导出）	GetUser
变量	camelCase	userID

错误处理

go 复制代码

// ✅ 推荐：包装错误
if err != nil {
    return fmt.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，可以：

bash 复制代码

# 方案1：维护两份文件（内容相同）
CLAUDE.md
AGENTS.md

# 方案2：使用符号链接
ln -s CLAUDE.md AGENTS.md

# 方案3：使用公共文件
# CLAUDE.md 和 AGENTS.md 都包含：
# include: project-conventions.md

7. 最佳实践

✅ DO - 推荐做法

保持简洁
- 不要写成小说，精炼关键信息
- 每个章节不超过 10 行
突出重点
- 使用 emoji 标记重要性
- 加粗关键信息
包含实用命令
- 构建、测试、运行命令
- 开发环境设置
记录编码规范
- 命名约定
- 代码风格
- 禁止事项
说明架构
- 目录结构
- 模块职责
- 数据流
记录已知问题
- 常见错误
- 解决方案
- 高风险区域
定期更新
- 项目演进时同步更新
- 删除过时信息

❌ DON'T - 避免事项

不要过于冗长
- 不要把整个 README 复制进来
- 不要包含安装教程（除非特殊）
不要包含敏感信息
- 密码、密钥、Token
- 内部 IP 地址
不要写临时任务
- 不要把 TODO 列表放进来
- 不要记录 sprint 任务
不要重复文档
- 详细文档放 docs/
- AGENTS.md 只放关键信息
不要忽略格式
- 使用正确的 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. 总结

🎯 核心要点

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

📋 快速开始

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

📚 下一步

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

📝 系列文章导航

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

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

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