AGENTS.md：让你的Java代码库为AI代理就绪

2026 年，软件构建的方式已发生根本性转变。我们不再仅仅为人类阅读而编写代码；我们正在构建供 AI 编码代理（如 Cursor、GitHub Copilot Agent Mode、Claude Code 和自主 CLI 工具）导航、调试和扩展的系统。

作为 Java 开发者，我们拥有强大的工具集。如果你正在使用 Quarkus，你便拥有了一项超能力：超音速亚原子 Java，以及超快的开发者循环、持续测试和内置的 Dev Services。然而，AI 代理经常在企业级 Java 仓库中出错。它们会把简单架构复杂化，在需要响应式代码的地方编写阻塞代码，或者浪费 token 尝试手动启动 Docker 容器，而 Quarkus Dev Services 本可以开箱即用地完成这些工作。

解决办法是？AGENTS.md。让我们探索如何使用这一新兴的开放标准，使你的 Quarkus 应用能够被 AI 代理轻松理解。

什么是 AGENTS.md？

AGENTS.md 规范是一个与工具无关的开放标准（由 Agentic AI Foundation 首创），旨在放置在仓库的根目录。将你标准的 README.md 视为面向人类的入职文档：它包含高层架构叙述、徽章和项目理念。而 AGENTS.md 是面向 AI 的可执行运行时指令层。它简洁、确定、命令式，且结构明确，旨在避免“上下文窗口膨胀”，同时给予自主代理成功所需的精确边界和命令。

一个面向代理的 Quarkus 代码库的解剖结构

当 AI 代理在你的工作区初始化时，它会读取你的项目结构。由于 Quarkus 涵盖了命令式和响应式两种范式，一个未经过指导的 AI 代理常常会产生幻觉或混用模式。一个针对 Quarkus 生态系统的有效 AGENTS.md 必须明确定义三个支柱：

操作命令：运行、测试和热重载的精确 Maven/Gradle 序列。
架构边界：关于阻塞与非阻塞代码以及数据访问模式的严格规则。
基础设施管理：强制代理使用 Quarkus Dev Services，而不是配置外部数据库。

实践：终极 Quarkus AGENTS.md 模板

将这个精确的 AGENTS.md 文件放入你的 Quarkus 仓库根目录，可以大幅提升 AI 生成代码和自主重构任务的质量。

$ md

## 技术栈与生态系统上下文

- **运行时**：Java 25，Quarkus 3.x（超音速亚原子 Java）。
- **构建工具**：Maven（`mvnw` 包装器已存在）。
- **扩展**：REST，Hibernate ORM with Panache，Quarkus Dev Services。
- **数据库**：PostgreSQL（完全由 Dev Services 管理）。

## 关键操作命令

- **启动开发模式**：`./mvnw quarkus:dev`
- **执行所有测试**：`./mvnw test`
- **持续测试**：启动 `./mvnw quarkus:dev` 并按 `r` 开启后台测试。
- **生产打包**：`./mvnw package`

## 架构边界与编码标准

### 1. 响应式 vs 阻塞规则

- **默认使用 REST**：返回 `Uni<T>` 或 `Multi<T>` 的端点绝**不能**调用阻塞操作。
- 如果方法会阻塞，必须显式使用 `@Blocking` 注解。

### 2. 数据访问（Hibernate ORM with Panache）

- 使用 **Panache 主动记录模式**，继承 `PanacheEntity`。除非复杂业务逻辑需要，否则不要编写自定义仓库或显式 DAO 层。
- **事务管理**：对变更操作使用 `@Transactional` 注解。绝不手动管理事务。

```java
// 正确的代理输出示例：
@Entity
public class Developer extends PanacheEntity {
    public String name;
    public String specialty;
    public static Uni<Developer> findByName(String name) {
        return find("name", name).firstResult();
    }
}

新微服务脚手架生命周期

当搭建新的微服务时（例如，“为计费微服务搭建脚手架”），代理遵循以下确定性的生命周期：

1. 读取命令层

绕过手动配置：不要手动生成原始的 pom.xml 文本，这经常导致版本不匹配或缺少依赖管理块。
使用 Quarkus 工具：依赖官方的 Quarkus Maven 插件命令结构。

2. 执行工具

命令：在你的终端工作区内直接运行明确的 mvn io.quarkus.platform:quarkus-maven-plugin:create 命令。
示例：

$ bash

mvn io.quarkus.platform:quarkus-maven-plugin:3.x.x:create \
  -DprojectGroupId=com.example \
  -DprojectArtifactId=billing-service \
  -DclassName="com.example.billing.BillingResource" \
  -Dpath="/billing"

3. 应用核心扩展

从一开始就保证集成必要的扩展：
- hibernate-orm-panache 用于数据访问
- quarkus-rest 用于 REST 端点
在创建时添加扩展：