1. 为什么 Java SQL 项目更需要一份 Agents.mdAgents.md 是放在项目根目录、用来给 AI 编程工具立规矩的说明文件。它本质上是一份写给模型看的工程约定代码风格怎么定、SQL 写到什么程度算合格、Lombok 注解什么时候用、哪些操作绝对禁止。你把它放进仓库AI 在补全、改代码、生成 SQL 时就会优先参考这份文件而不是凭它自己的默认习惯乱写。它适合谁适合正在用 Cursor、Claude Code、通义灵码这类工具写 Java 后端的人尤其是项目里已经用了 Lombok、MyBatis、分页插件团队又有一套自己的规范。没有 Agents.md 的时候你会发现 AI 每次生成的代码风格都不一样这次用Data下次手写 getter这次 SQL 三表 join下次在 Java 里 for 循环查库。你反复在对话里纠正换个工作区又得重来。我试过在一个 Spring Boot MyBatis 项目里加 Agents.md最直观的变化是 AI 生成的 Service 层代码开始主动用常量替代魔法值SQL 也不再动不动就三表关联。这篇就按从零搭骨架 → 声明规范 → 在工具里加载 → 验证结果的顺序给你一份可以直接抄的配置。2. 前置准备TaoToken 与项目环境要让 Agents.md 真正生效得先有一个能稳定调用模型的入口。TaoToken 提供统一的 API 接入官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的作用是让你在 AI 编程工具里填一个兼容的 base_url 和 key就能调用背后的模型不用自己折腾多套凭证。你需要准备三样东西第一一个可用的 API Key。登录后到控制台创建地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完记得复制保存页面关掉就看不到了。Key 的管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二一个 Java 项目。Maven 或 Gradle 都行JDK 8 以上最好已经引入 Lombok 和 MyBatis或 MyBatis-Plus。没有的话新建一个空 Spring Boot 工程也能跟着做。第三一个支持读取项目文件的 AI 编程工具。Cursor、Claude Code、Cline 这类都行它们会在你提问时把根目录的 Agents.md 一起带进上下文。注意Agents.md 的命名和位置很关键。放在项目根目录文件名严格写成Agents.md首字母大写部分工具也识别AGENTS.md建议两个都建或者按你所用工具的文档来。如果你还没确定用哪个模型可以先去模型对话页试一下效果地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 确认模型能理解你的规范描述再写进文件。3. 从零搭出可复制的 Agents.md 骨架3.1 文件结构与全局声明先在项目根目录建Agents.md。开头用一段全局声明告诉 AI 这份规范的适用范围避免它在每个新工作区都要你重复交代。# Agents.md ## 全局开发规范 除非项目中存在更具体的约束否则以下规则适用于所有工作区。 本文件优先级高于模型默认习惯冲突时以本文件为准。这段优先级声明很重要。AI 工具有时会同时读到多个配置文件明确写清优先级能减少它选择性忽略的情况。3.2 代码风格与 Lombok 约定Java 项目最容易失控的就是 Lombok 用法和注释风格。下面这段可以直接抄按你团队习惯微调。## 代码规范 - 非必要不要修改其他人编写的代码。 - 不要使用魔法值应定义常量或枚举。 - 不要在代码行末尾添加注释。 - 方法级注释和行内注释使用中文日志内容使用英文。 - 打印日志尽量使用 debug 级别错误日志使用 error 级别。 - 请求 DTO 字段可能存在空值语义时应避免使用 Java 基本数据类型。 - 初始化对象时优先使用无参构造方法。 - 如果类中已经使用 Data 等 Lombok 注解不要重复手写 Getter 和 Setter。 - 仅在实体和 DTO 上使用 DataService、Controller 等业务类不要用 Data。 - 需要链式调用时用 Accessors(chain true)不要手写 builder。 - 批量更新和批量删除必须分批处理批次大小通过配置项控制默认 1000。 - 建议在方法上方添加简洁的 Javadoc 风格注释。关于 Lombok这里有个细节值得展开。很多 AI 默认会在任何类上都加Data包括 Service。但 Service 加Data会生成一堆无意义的 equals/hashCode还可能引发循环依赖问题。所以在 Agents.md 里明确业务类不要用 Data能省掉后面大量 review 时间。Javadoc 的写法也给个示例让模型有参照/** * 根据用户 ID 查询订单列表。 */ public ListOrderVO listByUserId(Long userId) { // ... }3.3 SQL 规范与数据库安全SQL 部分是重点。AI 生成 SQL 时最常见的毛病是 join 太多、在 Java 里过滤数据、分页参数乱造。## SQL 规范 - SQL 尽量简单避免复杂慢 SQL。 - 不要使用三个表及以上的 join。 - 数据库查询条件和过滤逻辑应放在 SQL 中不要先查询大量数据再在 Java 中过滤。 - 批量操作必须分批禁止一次性 IN 上千个 ID。 - 分页使用项目已有的分页参数和分页结果类型不要自造 Page 对象。 ## 数据库访问安全 - 测试环境和生产环境数据库连接严格限制为只读。 - 只允许执行数据查询。 - 禁止新增、更新、删除、清空、修改表结构或以其他方式修改数据及数据库对象。最后那条只读约束是给 AI 划红线。有些工具在调试时会尝试执行 DDL 或 DELETE写清楚能避免误操作。3.4 包结构与分支约定## 包结构规范 - DTO 和 VO 默认不要放在 common 模块中应优先放在对应服务所属的业务模块中。 ## 分支选择 - 除非用户明确指定其他分支否则在该工作区之前指定的分支上进行开发。 - 修改代码前确认当前分支与工作区指定的开发分支一致。 - 不要仅因为工作区被外部切换就在另一个分支上继续开发。到这里一份完整的骨架就搭好了。整份文件控制在 60 行以内太长反而会让模型抓不住重点。4. 在 AI 编程工具中加载并验证4.1 配置工具读取 Agents.md以 Cursor 为例它默认会读取根目录的规则文件。如果你用的是通过 API 接入的方式需要在设置里填好 base_url 和 key{ baseUrl: https://taotoken.net/api, apiKey: 你的_API_KEY, model: 你选择的模型 }Claude Code 的话在项目根目录放好 Agents.md 后它会在会话开始时自动加载。你也可以在对话里显式提醒请参考根目录 Agents.md 的规范。4.2 用一次真实请求验证配置完别急着写业务先做一次验证。在 AI 工具里输入请根据 Agents.md 的规范为 OrderService 写一个根据用户 ID 查询订单列表的方法 要求使用项目已有分页类型SQL 放在 Mapper XML 中不要三表 join。然后检查生成结果。合格的输出应该满足Service 类没有Data方法上方有中文 Javadoc没有魔法值SQL 是单表或两表查询分页用的是你项目里的类型。如果生成结果不符合说明 Agents.md 没被读到或者描述不够明确。可以回到文件里把对应条款写得更具体比如把使用项目已有分页类型改成分页参数使用PageQuery返回使用PageResultT。4.3 用模型对话快速验证规范理解有时候你只想确认模型有没有读懂规范不想动代码。可以到模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 把 Agents.md 内容贴进去问它根据这份规范下面这段代码有哪些违规然后贴一段故意写错的代码看它能不能准确指出 Lombok 滥用、魔法值、三表 join 这些问题。这一步能帮你快速判断规范描述是否清晰。5. 本篇常见错排查Agents.md 没生效AI 还是乱写。先确认文件名和位置。必须是项目根目录文件名大小写要对。有些工具只认AGENTS.md可以两个都建内容保持一致。另外确认工具版本支持读取项目文件部分轻量插件不会自动加载。规范写了但模型选择性忽略。通常是条款太笼统。把SQL 要简单改成不要使用三个表及以上的 join把注意 Lombok 用法改成Service 类不要用 Data越具体越容易被遵守。另外可以在文件开头加一句以下规则为强制约束违反视为错误。生成的 SQL 仍然在 Java 里过滤数据。检查 Agents.md 里那条查询条件和过滤逻辑应放在 SQL 中是否写在了 SQL 规范段落内。模型对段落归属比较敏感放在代码规范里它可能不往 SQL 上联想。Lombok 注解冲突编译报错。常见于Data和手写 getter 同时存在。在 Agents.md 里补一条如果类中已使用 Data禁止手写 Getter/Setter并让 AI 在改代码前先检查现有注解。批量操作把内存打爆。说明分批条款没被执行。把批次大小写成明确配置项例如批次大小读取batch.size配置默认 1000并在 Agents.md 里注明禁止一次性传入超过批次大小的集合。工具报 401 或连接失败。检查 API Key 是否复制完整base_url 是否写成https://taotoken.net/api不要多加路径。Key 可以在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成。6. 把规范沉淀成长期资产Agents.md 最大的价值不是写一次而是持续迭代。每次你在 review 时发现 AI 又犯了同样的错就把那条规则补进去。比如发现它总爱在 for 循环里查数据库就加一条尽量不要在 for 循环中查询数据库发现它总把 DTO 塞进 common 模块就把包结构规范写死。如果你打算长期用 AI 做编码和 Agent 任务可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频、长周期的编码场景。接入细节和参数说明可以查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关配置在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后给个实用建议把 Agents.md 纳入代码仓库的版本管理和代码一起 review。规范变了就提交一次团队成员拉下来就同步了。这样 AI 生成的代码风格才能真正和团队保持一致而不是每个人各写各的。