AGENTS.md 完全指南：如何让 Codex 真正理解你的项目

前两篇我们分别介绍了：

第一篇
→ Codex CLI 是什么、怎么使用

第二篇
→ Codex CLI 常用命令和基本工作流

当真正开始把 Codex 用到日常项目以后，会遇到一个非常现实的问题：

每开一个新 Session，
难道都要重新告诉 Codex：

我们用 Java 17
我们用 Spring Boot
金额必须使用 BigDecimal
Controller 不能返回 Entity
不要执行 git push
修改完成必须运行测试
……

显然不应该。

这就是：

AGENTS.md

存在的意义。

可以先记住一句话：

AGENTS.md 是写给 Coding Agent 的项目开发说明。

如果：

README.md
→ 告诉开发者这个项目是什么

那么：

AGENTS.md
→ 告诉 Agent 在这个项目里应该怎么工作

一个维护良好的 AGENTS.md，可以显著减少重复 Prompt，让 Codex 更快理解项目结构、开发规范、测试方式和安全边界。

这一篇就专门讲清楚：

AGENTS.md 应该写什么？
不应该写什么？
放在哪里？
多模块项目怎么组织？
哪些规则最值得写进去？

---

1. 为什么需要 AGENTS.md？

假设现在有一个 Spring Boot 项目：

xxx-server
├── xxx-api
├── xxx-business
├── xxx-common
├── xxx-framework
├── pom.xml
└── README.md

你第一次让 Codex 修改代码：

增加用户余额查询接口。

Codex 可以自己阅读项目，然后推断：

Controller 在哪里
Service 在哪里
Mapper 在哪里
项目使用什么 ORM
返回值大概是什么格式

但是很多项目规则，并不能仅仅通过代码可靠推断出来。

例如：

金额必须使用 BigDecimal

Controller 禁止直接返回 Entity

所有接口统一返回 AjaxResult

数据库字段不能直接删除

修改表结构必须提供 migration SQL

生产配置禁止修改

未经允许不能 git push

修改完成必须运行 Maven 测试

这些规则通常存在于：

团队经验
开发规范
口头约定
历史事故
业务约束

而不是某一个 Java 文件里。

如果没有明确告诉 Agent，它只能：

猜

而 Coding Agent 最危险的情况之一就是：

代码写得没问题
但不符合你的项目规则

所以需要一个固定位置，把这些规则告诉它。

这就是：

AGENTS.md

---

2. AGENTS.md 可以理解成什么？

可以把一个项目想象成公司。

开发者入职以后，一般需要知道：

技术栈是什么
目录怎么组织
代码规范是什么
怎么运行项目
怎么执行测试
哪些事情不能做
提交代码有什么要求

Coding Agent 进入项目其实也一样。

所以：

AGENTS.md

很像：

Coding Agent 入职手册

它不是用来解释所有业务代码。

而是告诉 Agent：

你进入这个项目以后，
应该遵守哪些长期稳定的规则。

---

3. README.md 和 AGENTS.md 有什么区别？

这是最常见的问题。

README 通常写：

项目介绍
功能说明
安装方式
启动方法
部署方式
API 文档入口

例如：

# xxx-server

用户中心服务。

## Start

mvn spring-boot:run

这些内容主要是：

给人看

而 AGENTS.md 更关注：

Agent 修改代码时应该怎么做

例如：

# Project Instructions

## Coding Rules

- Java 使用 17
- 金额统一使用 BigDecimal
- Controller 不允许直接返回 Entity
- ServiceImpl 放在 service.impl

## Safety

- 不允许执行 git push
- 不允许修改生产配置
- 不允许连接生产数据库

可以简单记：

README.md
→ 项目使用说明

AGENTS.md
→ Agent 工作说明

两者可以有部分重复，但目标不同。

---

4. AGENTS.md 应该放在哪里？

最常见的方式是放在项目根目录：

xxx-server/
├── AGENTS.md
├── pom.xml
├── README.md
├── xxx-api/
├── xxx-business/
└── xxx-common/

这样它可以描述整个 Repository 的通用规则。

例如：

# Project Instructions

## Technology

- Java 17
- Spring Boot
- Maven
- MyBatis-Plus
- MySQL
- Redis

这种规则通常对整个项目都有效。

---

5. 怎么确认 Codex 识别到了 AGENTS.md？

进入项目：

cd xxx-server
codex

然后：

/status

如果当前版本会在状态中展示 Agent 指令信息，可以检查类似：

Agents.md: AGENTS.md

如果看到：

Agents.md: <none>

就需要检查：

① 当前 Directory 是否正确
② AGENTS.md 是否放在项目目录
③ 文件名是否正确
④ 当前 Codex 版本如何展示项目指令

所以使用 Codex 时，一个很好的习惯是：

cd project
   ↓
codex
   ↓
/status
   ↓
确认 Directory
   ↓
确认 AGENTS.md

---

6. 可以使用 /init 生成 AGENTS.md

如果项目里还没有：

AGENTS.md

可以使用 Codex 当前版本提供的初始化能力。

例如：

/init

它可以帮助分析当前 Repository，并生成一份初始的项目说明。

这个功能很适合：

第一次给老项目接入 Codex

因为 Codex 可以从现有代码中识别很多信息：

Java / Node.js / Python
Maven / Gradle / npm
Spring Boot
测试框架
目录结构
代码风格

但是需要特别注意：

/init 生成的内容更适合作为草稿，而不是最终版本。

---

7. 为什么不能完全依赖 /init？

因为有些信息可以从代码中发现：

Java 17
Spring Boot
MyBatis-Plus
Maven
JUnit

但有些规则只有团队自己知道：

旧 App 仍然依赖这个接口

这张表历史原因不能直接修改

这个字段虽然没使用但不能删除

生产环境配置禁止修改

某个 MQ Consumer 必须保证幂等

金额计算必须保留 8 位

数据库变更必须向后兼容

Codex 很难仅通过代码准确知道这些规则。

所以正确流程应该是：

/init
   ↓
生成初始 AGENTS.md
   ↓
开发者 Review
   ↓
补充业务规则
   ↓
补充安全规则
   ↓
补充测试规则
   ↓
长期维护

---

8. AGENTS.md 最应该写什么？

一个比较实用的 AGENTS.md，通常可以分成几类：

Project
Technology
Architecture
Coding Style
Database
Testing
Git
Safety
Business Rules

可以理解成：

AGENTS.md
│
├── 项目背景
├── 技术栈
├── 架构规则
├── 编码规范
├── 数据库规范
├── 测试规范
├── Git 规范
├── 安全边界
└── 关键业务规则

不一定每个项目都需要全部写。

应该根据项目实际情况调整。

---

9. Project：先告诉 Agent 这是什么项目

开头可以非常简单：

# Project Instructions

This repository is a Spring Boot backend service.

Main business modules:

- user
- wallet
- payment
- order
- notification

或者中文：

# 项目说明

这是一个 Spring Boot 后端项目。

主要业务模块：

- 用户
- 钱包
- 支付
- 订单
- 消息通知

目的不是写产品介绍。

而是帮助 Agent 快速建立：

Repository Mental Model

也就是：

这个仓库大概是干什么的？

---

10. Technology：明确技术栈

这是最适合写入 AGENTS.md 的内容之一。

例如：

## Technology

- Java 17
- Spring Boot
- Maven
- MyBatis-Plus
- MySQL
- Redis
- RabbitMQ
- JUnit 5

为什么需要写？

因为 Agent 在实现功能时会根据技术栈做选择。

例如缓存：

Redis

消息：

RabbitMQ

ORM：

MyBatis-Plus

如果没有明确说明，Agent 可能：

引入不需要的新框架
使用项目没有采用的技术
按照另一套技术习惯生成代码

---

11. Architecture：告诉 Agent 项目怎么分层

对于 Java 项目尤其重要。

例如：

## Architecture

项目采用：

Controller
→ Service
→ Mapper
→ Database

规则：

- Controller 只负责参数校验和调用 Service
- 业务逻辑必须放在 Service
- Mapper 只负责数据库访问
- Controller 不允许直接调用 Mapper
- Entity 不允许直接返回给客户端

这样 Codex 在增加接口时，就更容易生成符合项目结构的代码。

否则它可能直接：

Controller
   ↓
Mapper

虽然能运行，但破坏了项目分层。

---

12. Coding Style：把长期代码规范写进去

例如：

## Coding Style

- 使用 Java 17
- 优先使用构造器注入
- 金额统一使用 BigDecimal
- 时间统一使用 LocalDateTime
- 不新增 Lombok @Data
- Service 实现类统一放在 service.impl
- Controller 统一返回 AjaxResult
- Entity 不直接暴露给 API
- 新增公共方法必须有清晰命名

这类规则特别适合：

AGENTS.md

因为它们：

长期稳定
+
大量任务都会用到

如果每个 Prompt 都重新说一次，会非常浪费。

---

13. Database：数据库规则一定要写清楚

数据库属于 Coding Agent 修改项目时风险较高的区域。

例如：

## Database

- 数据库使用 MySQL
- ORM 使用 MyBatis-Plus
- 金额字段 Java 类型统一使用 BigDecimal
- 修改数据库结构必须提供 migration SQL
- 不允许直接删除已有字段
- 不允许修改历史 migration
- 新增索引前先检查是否已有相同或等价索引
- 数据库修改必须考虑向后兼容

如果项目对生产数据非常敏感，还可以加入：

- 不允许连接生产数据库
- 不允许执行 DROP TABLE
- 不允许执行 TRUNCATE
- 不允许在未经确认的情况下批量 UPDATE / DELETE

这样能明显减少高风险操作。

---

14. Testing：告诉 Codex 怎么验证修改

Coding Agent 最大的优势之一是：

不仅写代码
还可以自己验证

所以一定要告诉它：

测试应该怎么跑

例如：

## Testing

修改 Java 代码后优先执行：

```bash
mvn test

如果只修改单模块：

mvn -pl module-name test

提交结果前：

1. 确认项目可以编译
2. 运行相关单元测试
3. 检查 git diff

如果项目测试非常慢，也可以写：

```markdown
- 不要默认执行所有集成测试
- 优先运行与修改模块相关的测试
- 如果完整测试预计耗时较长，先运行目标模块测试

这样 Agent 的行为会更加符合项目实际情况。

---

15. Git：告诉 Agent 哪些 Git 操作可以做

Codex 很适合使用：

git status
git diff
git log

这些命令帮助理解项目和检查修改。

但一些 Git 命令风险明显更高。

因此可以明确：

## Git

允许：

- git status
- git diff
- git log
- git show

未经明确授权禁止：

- git commit
- git push
- git reset --hard
- git clean -fd
- git rebase
- 强制修改远程分支

这里的核心原则是：

读取型 Git 操作
→ 通常可以

破坏性 / 外部写入操作
→ 明确限制

---

16. Safety：建议每个生产项目都写

例如：

## Safety

未经明确授权：

- 不允许访问生产数据库
- 不允许修改生产环境配置
- 不允许执行 kubectl apply
- 不允许执行 kubectl delete
- 不允许部署服务
- 不允许调用生产环境写接口
- 不允许执行 git push
- 不允许删除文件或目录

这一部分可以理解成：

Agent Guardrails

也就是：

Agent 的护栏

权限系统负责：

Codex 技术上能不能做

而 AGENTS.md 负责：

这个项目里应该不应该做

两者不是完全一样的东西。

---

17. Business Rules：真正有价值的部分

技术栈其实 Codex 很容易从代码里识别。

真正能提高 Agent 质量的，往往是：

业务规则

例如钱包项目：

## Wallet Business Rules

- 所有余额变更必须生成 wallet_transaction
- 余额扣减必须保证幂等
- amount 必须使用 BigDecimal
- 禁止使用 double 计算金额
- 提现扣款和提现订单创建必须保证事务一致性
- 重复 sourceId 不允许重复入账

支付项目：

## Payment Business Rules

- paymentNo 是支付业务唯一标识
- 回调接口必须支持重复通知
- 支付成功状态不可回退
- 第三方回调必须先验签
- 金额比较必须使用 BigDecimal.compareTo

这种规则非常有价值。

因为 Agent 单纯读代码，可能只能看到：

现在是怎么实现的

而业务规则告诉它：

必须保证什么

这两者完全不同。

---

18. 一个 Spring Boot 项目的完整示例

下面给一个比较实用的版本。

# Project Instructions

## Project

这是一个 Java Spring Boot 后端项目。

主要模块：

- user
- wallet
- payment
- order

## Technology

- Java 17
- Spring Boot
- Maven
- MyBatis-Plus
- MySQL
- Redis
- RabbitMQ
- JUnit 5

## Architecture

项目采用：

Controller
→ Service
→ Mapper
→ Database

规则：

- Controller 只处理 API 层逻辑
- 业务逻辑放在 Service
- Controller 不直接调用 Mapper
- Entity 不直接返回给客户端
- DTO / VO 根据现有项目风格定义

## Coding Style

- 金额统一使用 BigDecimal
- 禁止使用 double 处理金额
- 时间优先使用 LocalDateTime
- 不新增 Lombok @Data
- 保持现有包结构
- 不进行与当前任务无关的重构

## Database

- ORM 使用 MyBatis-Plus
- 修改表结构必须提供 migration SQL
- 不修改历史 migration
- 不直接删除已有字段
- 数据库变更必须考虑向后兼容

## Testing

修改完成后：

1. 编译相关模块
2. 运行相关单元测试
3. 检查 git diff

优先：

```bash
mvn test
```

单模块：

```bash
mvn -pl module-name test
```

## Git

允许：

- git status
- git diff
- git log
- git show

未经明确授权禁止：

- git commit
- git push
- git reset --hard
- git clean -fd

## Safety

未经明确授权：

- 不访问生产数据库
- 不修改生产配置
- 不执行生产部署
- 不执行 kubectl 修改命令
- 不调用生产写接口

## Wallet Rules

- 所有余额变化必须记录流水
- 余额操作必须考虑幂等
- sourceId 用于业务去重
- 金额必须使用 BigDecimal
- 不允许出现负余额

这个版本已经可以覆盖很多真实项目。

---

19. AGENTS.md 是不是越长越好？

不是。

这是非常重要的一点。

很多人发现 AGENTS.md 有用以后，会开始疯狂往里面加东西：

数据库所有表结构
所有 API
所有业务流程
所有类说明
所有历史 Bug
所有部署命令
所有需求文档

最后变成：

几万行 AGENTS.md

这通常不是好事情。

因为 Agent 真正需要的是：

高价值
稳定
长期有效
与开发行为直接相关

的信息。

不是把整个项目文档全部塞进去。

---

20. 什么内容不建议写进 AGENTS.md？

例如：

今天临时修改某个接口
某个一次性需求
当前 Sprint 的任务
某个临时 Bug
某次线上事故日志
完整数据库 DDL
几十页 API 文档
大量可以直接从代码发现的信息

这些内容要么：

很快过期

要么：

Codex 自己可以读取

所以没有必要全部放进去。

---

21. 判断一条规则该不该写进去

可以问自己三个问题：

① 这条规则未来还会用到吗？

② Codex 能不能轻易从代码里知道？

③ 如果 Codex 不知道，会不会容易做错？

例如：

项目使用 Java 17

长期有效：

是

容易从代码发现：

是

但写进去成本很低，所以可以保留。

再例如：

余额变更必须生成流水

长期有效：

是

Codex 能否可靠推断：

不一定

不知道是否容易出问题：

非常容易

这种就非常值得写。

---

22. 推荐优先写“不能做错”的规则

如果 AGENTS.md 不想写得太长，可以优先写：

违反以后代价最大的规则

例如：

金额不能使用 double

不能访问生产数据库

不能直接删除数据库字段

支付回调必须幂等

余额变更必须记录流水

不能 git push

不能破坏现有 API

这类规则比：

变量名最好简洁

重要得多。

所以：

AGENTS.md

不是普通的：

代码 Style Guide

它更应该优先表达：

关键约束

---

23. Monorepo 怎么写 AGENTS.md？

假设项目是：

project/
├── AGENTS.md
├── backend/
│   ├── pom.xml
│   └── src/
├── admin-web/
│   ├── package.json
│   └── src/
└── app/
    └── src/

三个模块技术栈完全不同：

backend
→ Java

admin-web
→ Vue

app
→ Flutter

如果把所有规则都放在根目录：

AGENTS.md

会越来越混乱。

更合理的是：

project/
├── AGENTS.md
├── backend/
│   ├── AGENTS.md
│   └── ...
├── admin-web/
│   ├── AGENTS.md
│   └── ...
└── app/
    ├── AGENTS.md
    └── ...

根目录负责：

全局规则

子目录负责：

模块规则

---

24. 根 AGENTS.md 应该写什么？

例如：

# Repository Instructions

这是一个 Monorepo。

目录：

- backend：Java 后端
- admin-web：Vue 管理后台
- app：移动客户端

全局规则：

- 不修改生产配置
- 不执行 git push
- 不进行与任务无关的重构
- 修改必须保持向后兼容

这些规则：

所有模块都适用

所以应该放在根目录。

---

25. backend/AGENTS.md 应该写什么？

例如：

# Backend Instructions

## Technology

- Java 17
- Spring Boot
- MyBatis-Plus
- MySQL
- Redis

## Rules

- Controller 不直接调用 Mapper
- 金额使用 BigDecimal
- 修改数据库必须提供 migration
- 修改完成运行 Maven 测试

这些只对：

backend

有效。

---

26. admin-web/AGENTS.md 应该写什么？

例如：

# Admin Web Instructions

## Technology

- Vue 3
- TypeScript
- Vite

## Rules

- 使用 Composition API
- 新代码使用 TypeScript
- API 请求统一放在 api 目录
- 不在组件中直接拼接后端 URL
- 修改完成运行 lint 和 build

这样 Codex 修改：

backend

和：

admin-web

时，就可以遵守不同的规则。

---

27. 为什么分层 AGENTS.md 很重要？

因为大型 Repository 经常存在：

不同语言
不同框架
不同测试方式
不同代码规范

如果全部写成：

一个巨大 AGENTS.md

Agent 每次处理一个小模块，也要面对大量无关规则。

分层以后：

Root Rules
    ↓
Module Rules
    ↓
Task

会更加清晰。

可以理解成：

全局配置
+
局部配置

---

28. AGENTS.md 和 Prompt 谁优先？

可以从用途上理解：

AGENTS.md
→ 长期规则

Prompt
→ 当前任务

例如 AGENTS.md 写：

金额统一使用 BigDecimal
禁止 git push
数据库修改必须提供 migration

当前 Prompt：

增加用户冻结余额功能。

要求：

1. 增加 frozenBalance
2. 增加 freeze 和 unfreeze 方法
3. 保持旧 API 不变
4. 增加单元测试

两者组合起来就是：

长期项目规则
+
当前任务要求

所以不要把当前需求全部写入 AGENTS.md。

也不要每次 Prompt 都重复整个项目规范。

---

29. 一个好的 Prompt 应该利用 AGENTS.md

没有 AGENTS.md 时，Prompt 可能是：

增加用户余额冻结功能。

项目使用 Java17、Spring Boot、MyBatis-Plus。

金额必须使用 BigDecimal。

Controller 不允许调用 Mapper。

修改数据库要提供 migration。

不能 git push。

修改完成运行测试。

有了 AGENTS.md 以后，可以变成：

增加用户余额冻结功能。

要求：

1. 增加冻结和解冻能力
2. 保持现有 API 兼容
3. 操作必须幂等
4. 增加相关测试

遵循项目 AGENTS.md。

Prompt 明显更干净。

这也是 AGENTS.md 最大的价值之一：

减少重复上下文

---

30. AGENTS.md 不是绝对安全机制

这一点一定要注意。

即使写了：

不要执行 git push

也不能把它理解成：

系统级权限控制

AGENTS.md 本质上仍然是：

给 Agent 的工作指令

真正的安全还应该依赖：

Codex Permissions
操作确认
Git
测试环境
数据库权限
基础设施权限
人工 Review

正确思路应该是：

AGENTS.md
+
Permissions
+
Git
+
Environment Isolation
+
Developer Review

而不是：

写了 AGENTS.md
→ 什么都安全了

---

31. AGENTS.md 也需要维护

项目会变化。

例如：

Java 17
→ Java 21

RabbitMQ
→ Kafka

旧 Mapper
→ 新 Repository

测试命令发生变化

目录结构重构

如果 AGENTS.md 一直不更新，就会产生：

代码已经是新的
AGENTS.md 还是旧的

这时候反而会误导 Agent。

所以建议：

架构变化
技术栈变化
开发规范变化
安全规则变化
测试流程变化

时同步更新：

AGENTS.md

---

32. 可以把 AGENTS.md 放进 Git 吗？

如果里面是团队通用项目规则，通常很适合：

纳入 Git

这样整个团队使用 Coding Agent 时，都可以共享同一套规则。

例如：

Developer A
Developer B
Developer C
Codex

看到的是同一份：

项目开发约束

这比每个人自己维护一份 Prompt 更容易保持一致。

但要注意：

不要在 AGENTS.md 中写密码、Token、密钥等敏感信息。

例如绝对不要写：

Production DB Password = xxx
OpenAI API Key = xxx
AWS Secret = xxx

项目规则可以进 Git。

Secrets 不应该。

---

33. 一个更推荐的 AGENTS.md 编写原则

可以记住：

少
但重要

短
但明确

稳定
而不是临时

规则
而不是百科全书

如果一条内容可以写成：

金额统一使用 BigDecimal，禁止使用 double。

就没必要写五百字解释：

为什么 Java double 存在 IEEE 754 精度问题……

Agent 需要的是：

约束

而不是重新上一遍 Java 基础课。

---

34. 推荐的 AGENTS.md 模板

最后给一个可以直接作为项目起点的模板。

# Project Instructions

## Project

简要说明项目用途和主要模块。

## Technology

- Language:
- Framework:
- Build:
- Database:
- Cache:
- MQ:
- Test:

## Architecture

- Controller:
- Service:
- Repository / Mapper:
- DTO / VO:
- Module boundaries:

## Coding Style

- 命名规则
- 类型规则
- 金额规则
- 时间规则
- 异常处理规则
- 日志规则

## Database

- ORM:
- Migration:
- Schema 修改规则:
- 数据兼容规则:

## Testing

修改完成后：

1. 编译
2. 运行相关测试
3. 检查 git diff

常用命令：

```bash
<test command>
```

## Git

允许：

- git status
- git diff
- git log

未经明确授权禁止：

- git commit
- git push
- git reset --hard
- git clean -fd

## Safety

未经明确授权：

- 不访问生产数据库
- 不修改生产配置
- 不部署生产环境
- 不执行破坏性命令

## Business Rules

在这里写最重要、最容易被 Agent 误解的业务约束。

不需要第一次就把所有内容写满。

可以：

先写最重要的
   ↓
使用 Codex
   ↓
发现 Agent 经常犯某类错误
   ↓
把对应规则加入 AGENTS.md
   ↓
继续迭代

这其实是最实际的维护方式。

---

35. 最后怎么理解 AGENTS.md？

如果只记一句话：

AGENTS.md
=
Coding Agent 的项目工作手册

它最适合保存：

长期规则
技术栈
架构边界
编码规范
测试方式
安全限制
关键业务约束

而当前需求应该继续放在：

Prompt

可以简单理解成：

AGENTS.md
→ 在这个项目里应该怎么工作

Prompt
→ 这一次具体要做什么

Permissions
→ 技术上允许做到什么

三者组合：

AGENTS.md
      +
Prompt
      +
Permissions
      ↓
Codex Agent Behavior

对于真正长期使用 Codex 的项目来说：

Prompt 写得好

当然重要。

但更进一步应该做到：

让项目本身就对 Agent 友好

而 AGENTS.md，就是其中最重要的基础设施之一。

最终目标不是每次都写一个几百行 Prompt。

而是让 Codex 进入项目以后，很快知道：

这是什么项目
用什么技术
代码应该写在哪里
哪些规则必须遵守
哪些事情绝对不能做
修改完成以后怎么验证

当这些信息逐渐沉淀到 Repository 中以后，Coding Agent 才会真正从：

临时的 AI 助手

变成：

能够长期参与项目开发的工程 Agent