如果说：

• config.toml 是 Codex 的"操作系统配置"
• 那么 AGENTS.md 就是项目的"开发手册（Developer Guide）+ AI 操作说明书"。

很多人认为 AGENTS.md 就是几行提示词，其实不是。

对于大型 Java 项目（Spring Boot + Dubbo + MyBatis + Oracle + Redis），一个好的 AGENTS.md 往往有几百行甚至上千行。

---

一、AGENTS.md 的目的

官方设计 AGENTS.md 的目的只有一句话：

告诉 Codex（以及其他 AI Agent）如何理解这个项目、遵循什么规则、如何安全地工作。

它不是给人看的 README。

它是：

例如：

你说一句：

修复订单支付BUG

如果没有 AGENTS.md

Codex：

有 AGENTS.md

Codex：

效率会高很多。

---

二、AGENTS.md 可以理解成什么？

可以理解成：

所以：

AGENTS.md 就是 AI 的项目说明书。

---

三、一个大型 Java 项目的 AGENTS.md 一般有哪些内容？

下面是企业里面最常见的内容。

---

第一章：项目介绍

例如

目的：

告诉 AI：

这不是商城。

这是结算。

以后：

看到：

就是：

结算余额。

不是账户余额。

---

第二章：技术栈

例如：

目的：

Codex 不会：

建议：

Hibernate。

因为：

项目没有。

---

第三章：目录结构

例如：

告诉 AI：

模块职责。

例如：

DAO：

只能：

Controller：

只能：

---

第四章：模块职责

例如：

Codex：

不会：

把：

支付代码：

改到：

invoice。

---

第五章：代码规范

例如：

Codex：

以后：

全部按照这个写。

---

第六章：Spring 规范

例如：

---

第七章：MyBatis规范

例如：

Codex：

以后：

SQL：

都会：

遵守。

---

第八章：数据库规范（最重要）

例如：

例如：

之前：

Codex：

会直接：

执行。

以后：

它会：

先：

确认。

---

第九章：SQL规范

例如：

Codex：

生成 SQL：

会：

按规范。

---

第十章：Redis规范

例如：

以后：

Codex：

不会：

随便：

命名。

---

第十一章：Dubbo规范

例如：

以后：

生成：

Dubbo：

配置。

---

第十二章：Apollo规范

例如：

Codex：

不会：

写错：

Profile。

---

第十三章：日志规范

例如：

---

第十四章：异常规范

例如：

---

第十五章：Git规范

例如：

Codex：

以后：

自动：

生成。

---

第十六章：测试规范

例如：

---

第十七章：Maven规范

例如：

---

第十八章：Debug规范

例如：

Codex：

以后：

知道：

Debug：

怎么启动。

---

第十九章：数据库连接规范

例如：

---

第二十章：AI工作规则（重点）

例如：

这一章是专门告诉 AI：

哪些事情：

可以。

哪些：

不能。

---

四、真正企业里面最值钱的一章

其实不是：

Spring。

不是：

Redis。

而是：

项目业务知识

例如：

这一章：

非常重要。

AI：

以后：

不会：

把：

Bill

翻译成：

账单。

而知道：

这是：

结算单。

---

五、推荐的目录结构

一个大型 Java 项目可以按下面的结构组织 AGENTS.md：

---

六、对于你的项目，我建议增加的内容

根据之前的交流，你的项目涉及：

• Spring Boot
• Spring Cloud
• Dubbo
• Apollo
• Oracle
• OceanBase
• Redis
• RocketMQ
• MyBatis
• Maven 多模块
• 结算、开票、支付等业务

我建议把下面这些内容作为重点：

1. 业务术语词典：例如 Bill、Voucher、Settlement、Invoice 等术语的准确含义，避免 AI 误解业务。
2. 模块依赖关系：哪些模块可以依赖哪些模块，禁止跨层调用。
3. 数据库操作规则：默认只读、更新前必须先查询影响范围、禁止全表更新。
4. SQL 风格规范：索引使用、分页方式、禁止 SELECT *、复杂 SQL 的要求。
5. 调试与启动规范：固定的 JVM 参数（如 -Denv=fat、-Dspring.profiles.active=fat）、Maven 命令、Profile 说明。
6. 测试要求：修改 Service 必须补充单元测试，修改 Mapper 必须验证 SQL，修改接口必须说明兼容性。
7. AI 行为约束：修改完成后运行哪些检查、哪些操作必须征求确认（如 git push、数据库写操作）、哪些敏感文件不能读取或输出。

对于你这种企业级 Java 后端项目，一个维护良好的 AGENTS.md 往往比单纯优化提示词更能提升 Codex 的开发效率和修改质量。