Hermes Agent如何帮助从Java Web到AI Native：传统工程的AI化改造实战手册

发布于 2026-05-30 06:25

从Java Web到AI Native：传统工程的AI化改造实战手册

写给那些写了多年CRUD、被Spring Boot养大、如今看着AI浪潮不知从何下手的朋友们。

写在前面：AI Native到底在解决什么问题

不是往项目里加个ChatGPT弹窗就叫AI Native。

说个真实场景：一个写了5年Java的后端工程师张三，每次接到新需求都要做这些事：看现有代码理清逻辑、找相关表结构、和前端对齐接口格式、写Service和Controller、写SQL、写单元测试、自测、提测、修bug。这些环节里，至少有60%是重复性的体力活。

传统工程的运转方式是：人理解需求 -> 人写代码 -> 编译器编译 -> 机器执行 -> 人看日志排查问题。人的精力大量消耗在"写"和"排"上面。

AI Native工程的运转方式是：AI理解工程上下文 -> AI执行或辅助执行 -> 人做决策和验收。人的精力集中在"理解需求是否准确"和"验收结果是否正确"这两件事上。

这不是推倒重来。这是在你已有的Spring Boot工程上，逐步增加AI可读、AI可操作的层次，让AI真正成为你的工程合伙人而非玩具。

在动手之前，先确立一个核心原则：AI上下文即代码（AI-Context-as-Code）。所有AI能读懂、能使用的文件（AGENTS.md、Skill规范、Schema、参考文档）都应该是Java工程本身的一部分，存放在工程目录下，纳入Git版本控制。这样任何一个AI Agent（不局限于Hermes Agent）只要clone了这个工程，立刻就能获取完整的工程知识。AI上下文不是一次性的prompt，而是可复用、可传承的工程资产。

AI上下文文件的发现机制：不同Agent的加载方式不同

把文件放进工程只是第一步。更关键的问题是：AI Agent怎么知道这些文件在哪？ 不同Agent的发现机制不一样，需要分别处理。

第一类：自动扫描工作目录（无需配置）

以下文件名是各大AI Agent工具的约定约定，放在工程根目录（pom.xml同级）即可被自动发现：

文件名 支持的Agent工具
AGENTS.md Hermes Agent、Cursor、GitHub Copilot、Codeium
CLAUDE.md Claude Code、Claude in Cursor
.cursorrules Cursor IDE
.github/copilot-instructions.md GitHub Copilot

这些文件不需要任何配置，Agent启动时会自动从当前工作目录扫描并注入到上下文中。所以AGENTS.md放在工程根目录是最自然的做法，和Maven的pom.xml、Gradle的build.gradle享受同等待遇。

第二类：需要显式配置路径（Skill目录）

工程内 docs/skills/ 下的 SKILL.md 文件，不会被任何Agent自动发现。需要告诉Agent去哪里找。

以Hermes Agent为例，在 ~/.hermes/config.yaml 中配置 skills.external_dirs：

skills:
  external_dirs:
    - /mnt/d/workspace/xxx-order/docs/skills

配置后执行 hermes reload-skills 或重启Agent，这些Skill就会出现在 hermes skills list 中，可以通过 skill_view(name='java-spring-boot-dev') 加载使用。

对于没有 external_dirs 配置能力的Agent（如Cursor、GitHub Copilot），Skill文件无法像Hermes那样注册为可调用技能。但SKILL.md本身仍然是高质量的Markdown文档，可以通过以下方式利用：

  1. 在AGENTS.md中引用：告诉AI"编码规范详见 docs/skills/java-spring-boot-dev/SKILL.md"
  2. 直接拖拽到对话：Cursor等IDE支持把文件拖入对话窗口作为上下文
  3. 作为 .cursor/rules/ 的补充：把核心规范提炼到 .cursorrules 中，详细规范放在SKILL.md里按需引用

最佳实践：AGENTS.md作为总入口，Skill文件作为详细规范

AGENTS.md里写明工程概况和关键约定（简短、高频），同时用一行引用指向详细的Skill文件：

## 编码规范
详见 docs/skills/java-spring-boot-dev/SKILL.md
（包含分层规则、命名约定、测试要求、Commit Message格式）

## 数据库变更规范
详见 docs/skills/db-migration/SKILL.md
（包含Flyway版本命名、大表操作注意事项）

这样AGENTS.md保持精简（不浪费token），AI需要详细规范时再去读取对应的SKILL.md。

第1步：让AI能"读懂"你的工程（预计1-2天）

传统Java工程的知识散落在：程序员的脑子里、三年前的wiki里、组会上口口相传的潜规则里。AI什么都不知道。你的第一件事就是把这些知识结构化。

创建工程级AGENTS.md

在你的项目根目录（和pom.xml同级）创建AGENTS.md。这是AI Agent的"入职手册"。

建议的Java工程AI上下文目录结构：

xxx-order/                          <-- 工程根目录
  pom.xml
  AGENTS.md                         <-- 工程总入口，所有AI必读
  src/
    main/
      java/com/example/order/
        adapter/
        application/
        domain/
        infrastructure/
      resources/
        db/migration/               <-- Flyway SQL脚本（AI可读的Schema历史）
  docs/
    skills/
      java-spring-boot-dev/
        SKILL.md                      <-- Java编码规范Skill（Agent加载此文件）
        references/
          checkstyle-example.xml      <-- 可选：Checkstyle配置模板
      db-migration/
        SKILL.md                      <-- 数据库变更规范Skill
      crud-generator/
        SKILL.md                      <-- CRUD代码生成Skill
        templates/
          mapper.xml.tmpl             <-- 可选：MyBatis XML模板
    schema.sql                          <-- 当前最新Schema合集
    api.md                              <-- 接口文档（AI在新增接口时维护）
    domain-glossary.md                  <-- 领域术语表
    pitfalls.md                     <-- 踩坑记录
  .cursorrules                       <-- Cursor等IDE AI工具的配置
  .github/
    copilot-instructions.md         <-- GitHub Copilot的仓库级指令

关键点：AGENTS.md放在根目录，任何AI Agent打开工程第一眼就能看到。docs/skills/下的Skill文件夹遵循Agent Skill规范（SKILL.md作为入口），通过AGENTS.md中的引用行或config.yaml的external_dirs配置让Agent发现。

# 工程名称：XXX订单系统

## Git仓库
- 本工程仓库地址：git@git.company.com:xxx/xxx-order.git
- 默认分支：main
- 本地路径建议：~/workspace/xxx-order

### 关联工程（前后端一体化需要）
| 工程名 | 仓库地址 | 本地路径建议 |
|---|---|---|
| 前端管理后台 | git@git.company.com:xxx/xxx-admin.git | ~/workspace/xxx-admin |

### Clone命令
git clone git@git.company.com:xxx/xxx-order.git ~/workspace/xxx-order

## 技术栈
- Java 17 + Spring Boot 3.2.x
- MyBatis-Plus + MySQL 8.0
- Redis 7.x（缓存 + 分布式锁）
- 部署方式：Docker + K8s（JDK17基础镜像）

## 核心目录结构
adapter/         --- 对外接口层（Controller、MQ监听、定时任务）
application/     --- 应用服务层（业务编排、DTO转换、Assembler）
domain/          --- 领域层（实体、值对象、领域服务、仓储接口）
infrastructure/  --- 基础设施层（Mapper实现、外部API调用、缓存实现）

## 关键约定
- 所有金额用BigDecimal，单位为分（不是元）
- 订单状态流转：CREATED -> PAID -> DELIVERED -> COMPLETED，不可逆
- Controller统一返回Result<T>，错误码定义在ErrorCode枚举中
- 分页参数统一用MyBatis-Plus的Page对象，默认pageSize=20，最大不超过100

## 不可踩的坑
- OrderMapper的batchInsert必须配合@Transactional使用，否则自增ID不连续
- 价格计算严禁在SQL里做运算，必须在Java层用PricingDomainService
- 分布式锁的key命名规范：lock:{domain}:{bizId}，超时时间统一5秒
- 测试环境数据库：192.168.1.100:3306/test_db（不要连错）

## 常用操作命令
- 完整构建：./mvn clean package -DskipTests
- 本地启动：./mvn spring-boot:run -Dspring-boot.run.profiles=dev
- 单测：./mvn test -Dtest=OrderAppServiceTest
- 代码检查：./mvn checkstyle:check

## 详细规范（按需加载，避免AGENTS.md过长）

- 编码规范：docs/skills/java-spring-boot-dev/SKILL.md
  （分层规则、命名约定、测试要求、Commit Message格式）
- 数据库变更规范：docs/skills/db-migration/SKILL.md
  （Flyway版本命名、大表操作注意事项）

## Hermes Agent 配置（如果使用Hermes Agent）

在 ~/.hermes/config.yaml 中添加：
skills.external_dirs:
  - /mnt/d/workspace/xxx-order/docs/skills
然后执行 hermes reload-skills 加载。

## 前端工程（前后端一体化）

- 工程路径：../xxx-admin（相对本工程的路径）
- 前端AGENTS.md：../xxx-admin/AGENTS.md
- 前端工程使用Element Plus + TypeScript + Vue3
- API响应格式统一为 Result<T>
- 新增接口时必须在 docs/api.md 中同步更新接口文档（含请求示例和响应示例）

这份文档不是给人看的readme，是给AI看的操作手册。把你日常开发中"脑子里的规矩"全部写出来。坑点写得越具体，AI翻车越少。花一天时间整理这份文档，回报率极高。

数据库Schema即文档

把建表语句整理成文件，存放在 docs/schema.sql。AI理解业务最快的方式就是看表结构。

关键点：不要只给建表语句，必须加上注释。

CREATE TABLE `t_order` (
  `id`           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '订单ID，全局唯一',
  `order_no`     VARCHAR(32)     NOT NULL COMMENT '订单编号，业务唯一键，格式：O202501010001',
  `user_id`      BIGINT UNSIGNED NOT NULL COMMENT '下单用户ID',
  `total_amount` BIGINT          NOT NULL COMMENT '总金额，单位：分',
  `status`       TINYINT         NOT NULL DEFAULT 10
                 COMMENT '订单状态 10=已创建 20=已支付 30=已发货 40=已完成 90=已取消',
  `cancel_reason` VARCHAR(256)   DEFAULT NULL COMMENT '取消原因，可为空',
  `created_at`   DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at`   DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_order_no` (`order_no`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单主表';

第1步验收标准

找一个完全没有看过你项目的人（或者新开一个AI Agent对话），只通过AGENTS.md和schema.sql，看能不能回答这四个问题：

  1. 这个系统是干什么的？
  2. 有哪些核心模块，分别在哪个目录？
  3. 金额用什么类型？为什么？
  4. 订单状态怎么流转，哪个状态是终态？

答不出来，继续补AGENTS.md。这一步做到位了，后面每一步的难度都会降低。

第2步：让AI能"操作"你的工程（预计3-5天）

光读懂不够，AI得能动起来。这一阶段的核心是让AI能独立完成编码、测试、提交的完整链路。

创建可复用的Skill文件

Skill是AI Agent的操作手册。把你团队的最佳实践固化成Skill，AI每次执行任务时都会自动遵循这些规范。

在工程的 docs/skills/ 目录下创建 java-spring-boot-dev/SKILL.md：

---
name: java-spring-boot-dev
description: Java Spring Boot项目的开发规范，涵盖分层架构、命名约定、测试要求
---

# Java Spring Boot 开发规范

## 架构约束（禁止违反）

### 分层调用规则
adapter（Controller/MQ/Timer）
    v 只调用 application
application（业务编排）
    v 只调用 domain
domain（领域模型，定义仓储接口）
infrastructure（实现Mapper、Gateway、缓存）

红线：
- Controller里禁止写业务逻辑，禁止直接调Mapper
- application层禁止直接调外部HTTP接口（应通过infrastructure的Gateway）
- 跨domain通信只能通过AppService编排，不能直接调另一个DomainService

## 编码约定

### 类命名
Controller       -> OrderController
应用服务         -> OrderAppService
领域服务         -> PricingDomainService
Mapper           -> OrderMapper
外部服务适配器   -> PaymentGateway
领域事件         -> OrderCreatedEvent

### 方法命名
查询单条         -> getByXxx
查询列表         -> listByXxx
计数             -> countByXxx
创建             -> createXxx
更新             -> updateXxx
存在检查         -> existsByXxx

### 金额处理
- 类型：BigDecimal（禁止用double或float）
- 单位：分（入库和计算都用分，仅在返回前端时转元）
- 精度：setScale(0, RoundingMode.HALF_UP)

## 测试要求

必须写测试的场景：
1. 所有DomainService必须有纯单元测试（不启动Spring容器）
2. 所有AppService必须有集成测试（@SpringBootTest + Testcontainers）
3. Controller关键业务路径必须有接口测试

测试命名规范：
  方法名格式：被测方法名_场景描述_预期结果
  示例：createOrder_withInvalidProductCode_shouldThrowBusinessException

测试必须覆盖异常路径，不能只有happy path。

## Commit Message格式

type(scope): 简要描述

type取值：feat（新功能）、fix（修复）、refactor（重构）、test（测试）、docs（文档）、chore（杂项）
scope取值：order、user、payment、common、infra

示例：feat(order): 新增订单取消接口，支持全额退款

有了这个Skill，之后所有涉及Java开发的对话，AI都会自动遵循这些规范。你不需要每次都重复"Controller不能调Mapper"这种话。

第一个AI编码任务：订单取消功能

从一个独立的、边界清晰的小功能开始练手。不要上来就选核心交易链路。

给AI Agent的指令如下：

帮我实现"订单取消"功能，要求：

1. 在OrderController中新增 POST /api/orders/{id}/cancel 接口
2. 支持全额退款（调用PaymentGateway的refund方法）
3. 取消原因可选，存入t_order表的cancel_reason字段
4. 已取消的订单不能重复取消（抛BusinessException，用ErrorCode.ORDER_ALREADY_CANCELLED）
5. 已完成的订单不允许取消（抛BusinessException，用ErrorCode.ORDER_COMPLETED_CANNOT_CANCEL）
6. 写对应的DomainService单元测试和至少一个AppService集成测试

遵循AGENTS.md中的项目信息和java-spring-boot-dev规范。
按分层从domain开始逐步向外实现，每完成一层告诉我变更了哪些文件。

AI Agent的执行流程大致是这样的：

  1. 读取AGENTS.md，了解工程结构、包路径、命名规范、坑点
  2. 读取现有代码（OrderEntity、OrderMapper、PaymentGateway等）理解上下文
  3. 从domain层开始实现：在OrderDomainService中增加cancel方法
  4. 在application层：OrderAppService编排取消逻辑
  5. 在adapter层：OrderController新增接口
  6. 在infrastructure层：补全Mapper的updateStatus和PaymentGateway的refund实现
  7. 写测试
  8. 运行单测验证

你收到变更后做验收，重点关注：分层是否正确、命名是否符合规范、异常处理是否完备、测试是否有意义（不只是走个过场）。

建立AI编码验收清单

传统Code Review靠人脑记规范。AI编码Review靠清单。在AGENTS.md里补充：

## AI编码验收清单

每次AI提交代码后确认：
- [ ] 分层规则未被违反（不跨层调用）
- [ ] 金额字段类型正确（BigDecimal，单位为分）
- [ ] 抛出的业务异常有对应错误码（ErrorCode枚举中已定义）
- [ ] MyBatis XML中没有业务判断（状态流转逻辑在Java层）
- [ ] 新增Mapper方法在XML中有对应SQL
- [ ] 测试覆盖了异常路径（不只是正常流程）
- [ ] Commit Message符合格式规范

这个清单同时也是给AI的指示。你可以直接说：

把上次的代码变更对照AI编码验收清单过一遍，列出所有不符合项并修复。

第3步：让AI接管日常工程运维（持续积累）

编码只是工程师日常工作的一部分。还有大量重复性极高的运维事务，AI完全可以接管。

3.1 数据库变更管理自动化

每次加字段、加索引、加表，传统流程是：手写SQL -> 发给DBA -> DBA审核 -> 执行 -> 同步给团队。这个流程完全可以由AI来驱动。

在工程的 docs/skills/ 目录下创建 db-migration/SKILL.md：

---
name: db-migration
description: 数据库变更规范，使用Flyway管理版本，禁止直接执行DDL
---

# 数据库变更规范

## 变更流程
1. 变更文件位置：src/main/resources/db/migration/
2. 命名规范：V{版本号}__{描述}.sql
3. 示例：V1.0.3__add_cancel_reason_to_order.sql
4. 禁止执行DROP TABLE或DROP COLUMN操作
5. 新增NOT NULL字段必须同时指定默认值
6. 大表（超过100万行）加索引必须在低峰期执行，并使用CREATE INDEX ... ALGORITHM=INPLACE

## 提交前检查清单
- [ ] SQL已在本地Flyway环境中验证
- [ ] 大表的ALTER操作已评估执行时间
- [ ] 新增字段有对应Java实体类的修改

之后当你要做数据库变更时，只需告诉AI：

在t_order表中新增一个pay_time字段，记录支付时间，允许为空，
放在status字段后面，按照db-migration规范生成Flyway脚本。

AI会生成 V1.0.7__add_pay_time_to_order.sql，并同步修改对应的OrderEntity类。

3.2 定时任务：业务指标巡检

传统做法是写个Spring Boot定时任务轮询数据库、打印日志、发钉钉通知。用Hermes Agent的cron功能可以更灵活。

比如第二天早上9点自动生成前一天的业务日报：

创建cron任务，设置每天早上9点执行：

查询订单系统昨天的核心数据：
1. 按小时统计新订单数和GMV
2. 统计取消订单数和取消率
3. 环比前天的变化幅度
4. 如果有异常波动（取消率超过15%或GMV下降超过30%），重点标出

查询数据库（连接信息见AGENTS.md），
将分析结果以简洁的中文总结输出，保存到 docs/daily/ 目录。

好处是这个巡检任务不需要部署，不需要Java定时任务类，不需要写HTTP接口。一个cron表达式就搞定了。而且随时可以调整逻辑，不用改代码重新发布。

3.3 自动化文档更新

Java项目的文档过期是普遍现象。让AI在每次代码变更后自动更新文档。

在AGENTS.md里加上：

## 文档维护规则
每次涉及以下内容时，AI必须在提交前同步更新对应文档：
- 新增API接口 -> 更新 docs/api.md（字段说明、示例请求/响应）
- 新增领域概念 -> 更新 docs/domain-glossary.md（中文定义、归属聚合根）
- 修改状态流转逻辑 -> 更新 docs/order-state-diagram.md（Mermaid状态图）

第4步：让AI参与架构决策（进阶）

当AI已经能熟练使用你的工程后，可以让它参与更高层次的架构讨论。

给AI一段业务需求描述和现有的代码情况，问你真正关心的问题：

业务方想在订单系统里加入"拼团"功能：
- N人成团，成团前付款但冻结，不成团则退款
- 拼团有时效限制（24小时）
- 需要看到当前成团进度

现有工程是标准的分层架构，Order聚合根已经比较重了。
请分析三种方案：
1. 在现有Order聚合内扩展拼团字段和逻辑
2. 新建GroupBuy聚合，通过领域事件和Order交互
3. 创建独立的GroupBuy微服务，通过MQ和现有系统通信

从以下维度对比：代码侵入性、数据一致性风险、未来可维护性、实施工作量。
不要给结论，把分析列出来我来决策。

这种情况下AI的作用不是替你做决策，而是把架构选择的利弊用结构化的方式呈现出来，让你这个有经验的开发者做出更全面的判断。传统上你需要自己画架构图、写对比文档，AI帮你把这些准备工作做了。

第5步：打造工程级AI工具箱（长期维护）

5.1 整理工程专属Skill库

随着你和AI的协作越来越深入，把每一个反复使用的操作固化为Skill文件，存放在 docs/skills/ 目录下，随工程一起版本控制管理和演进：

Skill目录 触发场景
java-spring-boot-dev/SKILL.md 所有Java编码任务
db-migration/SKILL.md 数据库变更
crud-generator/SKILL.md 根据表结构生成标准增删改查代码
api-doc-update/SKILL.md 更新接口文档
performance-check/SKILL.md 分析慢SQL和接口耗时

每个Skill都是你和AI磨合经验的结晶。越积累越高效。更重要的是，这些Skill文件是工程资产：新来的开发者clone了工程，AI Agent加载这些文件就能立刻上手；其他团队的AI Agent（Cursor、GitHub Copilot、Codeium等）只要拿到同一个工程，也能复用同一套规范。

5.2 沉淀工程知识文档

把每次踩坑的经验更新到AGENTS.md或对应的参考文档中。比如：

## 踩坑记录

### 2025-01-15：分布式锁误用导致重复退款
现象：极端并发下同一订单被退款两次。
原因：分布式锁的key只用了orderId，没有区分操作类型（cancel和refund是不同的key）。
教训：后续所有涉及多步骤的操作，每个步骤的锁key必须包含操作类型前缀。
     格式更新为：lock:{domain}:{operation}:{bizId}

这些踩坑记录对新AI Agent来说是极其珍贵的知识，能让它避免在同一个地方摔跤。

5.3 定期回顾与优化

每个月花半天时间，和AI一起做工程健康度检查：

帮我分析一下工程当前的状况：
1. 找出测试覆盖率最低的三个类（高风险区）
2. 找出最近一个月变更最频繁的文件（不稳定区）
3. 检查AGENTS.md中的信息是否有过期内容（比如数据库地址变了、某个外部服务下线了）
4. 检查Flyway脚本中是否有可以合并的历史版本

输出一份简短的工程健康报告，列出需要关注的事项。

写在最后：一个务实的预期管理

AI Native转型不是银弹。以下是我对实际效果的诚实评估：

确实能显著提效的：

  • 重复性CRUD代码编写（减少60-80%的时间）
  • 单元测试编写（减少50%以上的时间）
  • 文档维护（减少70%的遗漏）
  • 数据库变更管理（减少流程上的扯皮）
  • 业务巡检和日常运维（完全自动化）

需要谨慎对待的：

  • 核心交易链路的新功能（AI能写，但你必须验证每一行）
  • 复杂的分布式事务场景（AI容易忽略边界条件）
  • 性能优化（AI能发现慢SQL，但缓存策略设计还得你来定）
  • 安全相关逻辑（认证鉴权、数据脱敏，必须人工审核）

转型的过程也不是一步到位的。建议按这个顺序推进：

读懂工程 -> 辅助编码 -> 自动化运维 -> 参与架构
  1-2天       1-2周       持续积累        随时可用

每一步都建立在上一步的基础上。跳过"读懂工程"直接让AI写代码，等同于招了一个不知道公司情况的新员工就直接让他改核心系统。结果一定是灾难性的。

但踏踏实实把第一步做好了，你会发现AI比大多数实习生更靠谱：它不会忘记你定的规范，不会因为情绪波动写出烂代码，不会因为"我以为你知道"就跳过关键信息。

它会成为你的工程合伙人。

本文基于多AI Agent协作实践经验编写，其中工程级AI上下文管理的思路适用于各类AI编码工具（Cursor、GitHub Copilot、Hermes Agent、Codeium等），不绑定任何特定Agent工具。

← 返回博客列表
文章信息

标题: Hermes Agent如何帮助从Java Web到AI Native：传统工程的AI化改造实战手册

发布时间: 2026-05-30 06:25