AGENTS.md文件详解

如果说：

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。

它是：

AI 的开发规范

例如：

你说一句：

修复订单支付BUG

如果没有 AGENTS.md

Codex：

开始搜索整个项目……
猜……
猜……

有 AGENTS.md

Codex：

订单模块：

payment-service

↓

DAO

↓

OrderMapper

↓

Dubbo

↓

OrderFacade

↓

RocketMQ

↓

修改以后执行：

mvn -pl payment-service test

效率会高很多。

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

可以理解成：

                    你
                     │
          "修复支付BUG"
                     │
                     ▼
                Codex
                     │
          查看 AGENTS.md
                     │
      ┌──────────────┼──────────────┐
      │              │              │
   项目结构      编码规范      数据库规则
      │              │              │
      └──────────────┼──────────────┘
                     │
               开始修改代码

所以：

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

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

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

第一章：项目介绍

例如

# Project Overview

项目名称：

BlueSpar

作用：

结算系统

主要模块：

payment

invoice

settlement

trade

risk

目的：

告诉 AI：

这不是商城。

这是结算。

以后：

看到：

Balance

就是：

结算余额。

不是账户余额。

第二章：技术栈

例如：

Java 17

Spring Boot

Spring Cloud

Dubbo

RocketMQ

MyBatis

Oracle

Redis

Apollo

目的：

Codex 不会：

建议：

Hibernate。

因为：

项目没有。

第三章：目录结构

例如：

bluespar

├── payment-service

├── payment-api

├── invoice-service

├── common

├── dao

├── web

告诉 AI：

模块职责。

例如：

DAO：

只能：

dao

Controller：

只能：

web

第四章：模块职责

例如：

payment-service

负责：

支付

--------

invoice-service

负责：

开票

--------

settlement-service

负责：

结算

Codex：

不会：

把：

支付代码：

改到：

invoice。

第五章：代码规范

例如：

必须：

使用 Lombok

禁止：

Getter Setter

统一：

@Slf4j

统一：

Builder

统一：

Optional

Codex：

以后：

全部按照这个写。

第六章：Spring 规范

例如：

禁止：

new Service()

全部：

@Autowired

事务：

@Service

@Transactional

第七章：MyBatis规范

例如：

Mapper

放：

dao.mapper

XML

放：

resources

禁止：

select *

必须：

resultMap

Codex：

以后：

SQL：

都会：

遵守。

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

例如：

禁止：

Delete

禁止：

Drop

禁止：

Truncate

Update

必须：

where

查询：

必须：

limit

例如：

UPDATE

之前：

Codex：

会直接：

执行。

以后：

它会：

先：

SELECT

确认。

第九章：SQL规范

例如：

禁止：

SELECT *

禁止：

IN ()

推荐：

EXISTS

JOIN

最多：

4张表

Codex：

生成 SQL：

会：

按规范。

第十章：Redis规范

例如：

Key：

统一：

faa:

TTL：

必须：

24小时

Value：

JSON

以后：

Codex：

不会：

随便：

命名。

第十一章：Dubbo规范

例如：

Provider：

service

Consumer：

api

Tag：

test

以后：

生成：

Dubbo：

配置。

第十二章：Apollo规范

例如：

开发：

fat

测试：

test

生产：

prod

Codex：

不会：

写错：

Profile。

第十三章：日志规范

例如：

禁止：

System.out

统一：

Slf4j

Error：

必须：

异常

第十四章：异常规范

例如：

统一：

BusinessException

统一：

ErrorCode

禁止：

RuntimeException

第十五章：Git规范

例如：

Commit

feat

fix

refactor

docs

Codex：

以后：

自动：

生成。

第十六章：测试规范

例如：

修改：

Service

必须：

新增：

JUnit

覆盖率：

80%

第十七章：Maven规范

例如：

统一：

./mvnw

禁止：

mvn install

开发：

mvn test

第十八章：Debug规范

例如：

VM：

-ea

-Denv=fat

-Dspring.profiles.active=fat

Codex：

以后：

知道：

Debug：

怎么启动。

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

例如：

只能：

测试库

禁止：

生产库

账号：

readonly

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

例如：

修改代码以后：

必须：

mvn test

不能：

git push

不能：

merge

不能：

删文件

不能：

改数据库

必须：

先Explain SQL

这一章是专门告诉 AI：

哪些事情：

可以。

哪些：

不能。

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

其实不是：

Spring。

不是：

Redis。

而是：

项目业务知识

例如：

Order

订单

Trade

交易

Bill

结算单

Invoice

发票

Balance

余额

Voucher

凭证

这一章：

非常重要。

AI：

以后：

不会：

把：

Bill

翻译成：

账单。

而知道：

这是：

结算单。

五、推荐的目录结构

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

AGENTS.md
├── 1. 项目概述
├── 2. 技术栈
├── 3. 模块结构
├── 4. 编码规范
├── 5. 包结构
├── 6. Spring 规范
├── 7. MyBatis 规范
├── 8. SQL 规范
├── 9. 数据库规范
├──10. Redis 规范
├──11. RocketMQ 规范
├──12. Dubbo 规范
├──13. Apollo 规范
├──14. 日志规范
├──15. 异常规范
├──16. Maven 构建规范
├──17. Debug 配置
├──18. 测试规范
├──19. Git 提交流程
├──20. AI 工作规则
├──21. 业务术语词典
├──22. 常见问题（FAQ）
├──23. 常用命令
├──24. 安全规范
└──25. 开发 Checklist

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

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

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

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

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

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

posted @ 2026-07-26 16:16 郭慕荣阅读(43) 评论(0) 收藏举报

刷新页面返回顶部

郭慕荣博客园

AGENTS.md文件详解

一、AGENTS.md 的目的

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

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

第一章：项目介绍

第二章：技术栈

第三章：目录结构

第四章：模块职责

第五章：代码规范

第六章：Spring 规范

第七章：MyBatis规范

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

第九章：SQL规范

第十章：Redis规范

第十一章：Dubbo规范

第十二章：Apollo规范

第十三章：日志规范

第十四章：异常规范

第十五章：Git规范

第十六章：测试规范

第十七章：Maven规范

第十八章：Debug规范

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

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

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

项目业务知识

五、推荐的目录结构

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

公告