传统 Java/Vue 系统如何一步步接入 AI 维护

这篇不讲概念，专门讲落地：如果手上已经有一个传统 Java / Vue / Spring Boot 系统，想让 AI 帮忙长期维护，应该先做什么、后做什么、做到什么程度就够用。

---

核心原则

传统系统接入 AI 维护，不是先搭一个复杂 AI 平台，也不是一开始写完所有 spec、rules、skills、harness。

正确做法是：

先让 AI 不迷路，再让 AI 不乱写，再让 AI 不乱猜业务，最后把重复任务封装成 skill。

落地顺序：

1. CLAUDE.md / AGENTS.md：让 AI 不迷路
2. rules/：让 AI 不乱写
3. specs/：让 AI 不乱猜业务
4. skills/：让 AI 不重复低质量劳动
5. 每次维护后反哺：越用越稳

---

第一步：先写项目入口文件

最小起点是项目根目录写一个：

CLAUDE.md

或者为了兼容更多 Agent，写：

AGENTS.md

它是 AI 进入项目后的第一入口。

最小模板

# 项目 AI 工作规范

## 项目说明
这是一个 XXX 系统，主要用于 XXX。

## 技术栈
- 后端：Java 17 / Spring Boot / MyBatis Plus / MySQL
- 前端：Vue 3 / Vite / Element Plus
- 缓存：Redis
- 消息队列：RabbitMQ

## 目录结构
- backend/ 后端服务
- frontend/ 前端项目
- docs/ 项目文档
- specs/ 模块规格说明
- rules/ AI 开发规则
- skills/ 可复用 AI 任务能力

## 常用命令
- 后端测试：mvn test
- 前端安装：pnpm install
- 前端构建：pnpm build

## AI 工作规则
1. 修改代码前必须先阅读相关模块 spec。
2. 不允许凭空猜接口、字段、表名。
3. 不允许大范围重构无关代码。
4. 修 bug 必须先说明根因，再改代码。
5. 完成后必须运行对应测试或说明无法运行的原因。
6. 涉及数据库变更，必须同步 migration 和文档。

这一步解决的是：

AI 不知道项目是什么
AI 不知道从哪启动
AI 不知道该读哪些文件
AI 改错目录
AI 没验证就说完成

---

第二步：建立最小目录结构

不需要复杂，先这样就够：

your-project/
├── CLAUDE.md
├── specs/
│   ├── README.md
│   └── core-business.md
├── rules/
│   ├── backend.md
│   ├── frontend.md
│   ├── database.md
│   └── testing.md
└── skills/
    └── systematic-debugging.md

如果是纯后端项目，可以更简单：

your-project/
├── CLAUDE.md
├── specs/
├── rules/
│   ├── backend.md
│   └── database.md
└── skills/
    └── systematic-debugging.md

目录含义：

目录/文件	作用
CLAUDE.md	AI 工作入口和最小 harness
specs/	模块业务说明和验收标准
rules/	项目开发规范
skills/	高频任务标准流程

---

第三步：先写 rules，让 AI 不乱写

传统系统里，AI 最容易犯的第一个错误是"不符合项目写法"。

所以 rules 优先级很高。

rules/backend.md

# 后端开发规则

## 分层规则
1. Controller 只负责参数接收和响应返回，不写业务逻辑。
2. Service 负责业务编排和事务控制。
3. Mapper 只负责数据库访问。
4. DTO/VO/Entity 不混用。

## 接口规则
1. 新增接口必须定义 Request 和 Response 对象。
2. 查询列表必须分页。
3. 不允许直接返回 Entity 给前端。
4. 参数校验使用 Bean Validation。

## 事务规则
1. 多表写入必须确认事务边界。
2. 支付、库存、订单状态变更必须考虑幂等。
3. 不允许在事务中调用慢外部接口。

## 安全规则
1. 禁止字符串拼接 SQL。
2. 禁止日志打印密码、token、身份证等敏感信息。
3. 权限校验必须走统一注解或统一拦截器。

## AI 修改规则
1. 不允许顺手重构无关代码。
2. 不允许删除已有逻辑，除非 spec 明确要求。
3. 修 bug 必须先说明根因。
4. 完成后必须说明验证方式。

rules/database.md

# 数据库规则

1. 所有业务表必须有 id、created_at、updated_at。
2. 删除优先使用软删除字段 deleted。
3. 金额字段使用 decimal，不使用 float/double。
4. 状态字段必须有明确枚举说明。
5. 新增索引必须说明查询场景。
6. 涉及线上表结构变更必须提供 migration。
7. 不允许 AI 猜表名、字段名，必须从 schema 或代码中确认。

rules/frontend.md

# 前端开发规则

1. 页面必须放在对应业务模块目录下。
2. 列表页必须使用项目统一表格组件。
3. 表单校验必须使用统一校验规则。
4. 接口请求必须走统一 request 封装。
5. 不允许绕过权限控制直接展示按钮。
6. 不允许直接渲染不可信 HTML。
7. 不允许为了当前功能重构公共组件。

Rules 写到这个程度，AI 的乱写概率会明显下降。

---

第四步：补核心模块 Spec，让 AI 不乱猜业务

不要一开始写全系统 spec。

先选最容易出错、最核心、最常维护的模块。

例如：

specs/order.md
specs/payment.md
specs/inventory.md
specs/approval.md
specs/permission.md

模块 Spec 模板

# XXX 模块 Spec

## 1. 模块职责
这个模块负责什么，不负责什么。

## 2. 核心实体/字段
关键表、字段、对象。

## 3. 核心业务规则
最不能被改错的规则。

## 4. 状态流转/关键流程
状态机、审批流、支付流、库存流等。

## 5. 常见坑
历史 bug、线上踩坑、容易漏的边界。

## 6. AI 修改注意事项
明确禁止猜字段、禁止绕过流程、禁止改无关模块。

订单模块示例

# 订单模块 Spec

## 1. 模块职责
负责用户下单、支付、取消、发货、完成。

## 2. 核心实体/字段
- 订单：订单编号、用户、金额、状态、创建时间
- 订单明细：商品、数量、单价
- 支付记录：支付渠道、支付流水号、支付状态

## 3. 核心业务规则
1. 已支付订单不能直接取消。
2. 支付回调必须幂等。
3. 订单金额以后端计算为准，不能信任前端传入。

## 4. 状态流转
CREATED -> PAID -> SHIPPED -> FINISHED
CREATED -> CANCELLED

## 5. 常见坑
- 支付平台可能重复回调。
- 库存扣减和订单状态更新可能出现不一致。
- 用户刷新页面可能重复提交订单。

## 6. AI 修改注意事项
1. 不能绕过订单状态机。
2. 涉及金额必须使用 BigDecimal。
3. 涉及支付回调必须检查幂等逻辑。
4. 不允许顺手修改库存模块核心逻辑。

---

第五步：先沉淀一个 Debugging Skill

传统系统维护里最高频的 AI 任务通常不是新功能，而是修 bug。

所以第一个 skill 建议写：

skills/systematic-debugging.md

内容：

# Systematic Debugging Skill

## 适用场景
当用户要求修复 bug、排查异常、解决线上问题时使用。

## 输入要求
- 错误日志
- 复现步骤
- 相关接口或页面
- 最近变更
- 期望行为和实际行为

## 执行流程
1. 先复述问题现象。
2. 定位相关代码路径。
3. 阅读代码，不允许直接猜测。
4. 提出 1-3 个可能原因。
5. 用日志、代码、测试验证假设。
6. 确认根因后，只做最小修复。
7. 运行验证。
8. 输出根因、改动、验证结果。

## 禁止事项
1. 禁止未定位根因就改代码。
2. 禁止大范围重构。
3. 禁止用吞异常、加空判断掩盖问题。
4. 禁止没有验证就说修好了。

这个 skill 的价值非常高，因为它能阻止 AI 最常见的问题：猜测式修复。

---

第六步：以后给 AI 任务要用规范模板

不要再只说：

帮我加个订单导出功能。

改成：

## 任务
给订单管理模块新增 Excel 导出功能。

## 必读上下文
- CLAUDE.md
- specs/order.md
- rules/backend.md
- rules/frontend.md
- rules/database.md

## 要求
1. 导出字段与订单列表一致。
2. 支持按当前查询条件导出。
3. 只允许导出当前用户有权限的数据。
4. 不允许改动无关模块。
5. 完成后运行后端测试和前端构建。

## 交付
1. 改动文件列表。
2. 核心实现说明。
3. 验证结果。
4. 如果无法验证，说明原因。

这样 AI 才是在明确上下文和边界里做事。

---

第七步：每次维护后反哺资产

AI 维护传统系统，不是一次性建完规则就结束，而是每次任务后沉淀。

反哺规则：

业务规则不清 → 更新 specs/
AI 写法不符合项目规范 → 更新 rules/
同类任务重复出现 → 更新 skills/
执行流程失控 → 更新 CLAUDE.md / AGENTS.md
验证方式不清 → 更新 testing rules 或 checklist

例如：

这次发现的问题	应该反哺到哪里
AI 不知道订单状态不能跳转	specs/order.md
AI 又忘了金额用 BigDecimal	rules/backend.md
AI 修 bug 没找根因	skills/systematic-debugging.md
AI 修改前没读 spec	CLAUDE.md
AI 不知道要跑什么测试	rules/testing.md

核心闭环：

任务 → spec → rules → skill → 修改 → 验证 → 反哺

---

推荐成熟度路线

阶段 1：AI 能读懂项目

产物：

CLAUDE.md

目标：

让 AI 不迷路

阶段 2：AI 能按规范改代码

产物：

rules/backend.md
rules/frontend.md
rules/database.md
rules/testing.md

目标：

让 AI 不乱写

阶段 3：AI 能理解业务模块

产物：

specs/order.md
specs/payment.md
specs/inventory.md
specs/approval.md

目标：

让 AI 不乱猜业务

阶段 4：AI 能稳定做重复任务

产物：

skills/systematic-debugging.md
skills/crud-module.md
skills/code-review.md
skills/test-generation.md

目标：

让 AI 不重复低质量劳动

---

不要踩的坑

1. 不要一开始写全系统 Spec

太重，容易烂尾。

正确做法：

改哪个模块，补哪个模块。

2. 不要把 rules 写成一篇超长文档

AI 不容易抓重点。

正确做法：

backend.md
frontend.md
database.md
testing.md
security.md

按任务加载。

3. 不要什么都封装成 skill

低频任务不用封装。

正确做法：

重复三次以上、流程固定、容易出错、价值高，再封装。

4. 不要让 AI 自己猜上下文

每次任务最好明确告诉它读哪些文件。

5. 不要相信"完成了"三个字

必须看验证证据。

测试通过
构建通过
接口调用成功
页面操作成功
SQL migration 已执行
无法验证的原因说明

---

最小可执行清单

如果今天就要开始，可以只做这 5 件事：

1. 写 CLAUDE.md
2. 写 rules/backend.md
3. 写 rules/database.md
4. 写 specs/core-business.md
5. 写 skills/systematic-debugging.md

这套最小资产已经能显著提升 AI 维护传统系统的稳定性。

---

结论

传统系统接入 AI 维护的关键不是"大模型有多聪明"，而是项目有没有给 AI 提供足够清晰的上下文和边界。

最小落地路径：

CLAUDE.md 让 AI 不迷路
rules 让 AI 不乱写
specs 让 AI 不乱猜业务
skills 让 AI 不重复低质量劳动
每次维护后反哺，让系统越来越适合 AI 维护

最终目标是：

让 AI 在有图纸、有规矩、有流程、有验证的环境里稳定维护传统系统。