从 Vibe Coding 到 Harness Engineering： JDK 升级中可控演进的 AI 工程实践

过去一年，AI Coding 从代码补全工具逐渐发展为能理解项目、规划任务并执行开发的工程助手。但在真实软件工程中，它更多仍用于新功能开发。

实践中我们发现，真正消耗工程时间的并不是“写新代码”，而是框架迁移、版本升级、安全修复等维护性工程。这类工作的核心难点，也不在生成代码，而在于如何把系统安全、稳定地改正确。

本文结合一次 JDK21 升级实践，分享我们在 AI 辅助维护性工程中的工程化思路，如何通过 Harness Engineering，让 AI 在复杂约束下稳定完成系统升级。

01

AI 擅长写代码，工程却不止是写代码

如果只看新功能开发，AI Coding 已经足够优秀。

无论是生成一个模块、补全一个函数，还是快速完成原型验证，如今的大模型都已经能够胜任。Vibe Coding 之所以曾流行，也正是因为这种“边想边写、快速迭代”的开发方式，在探索性开发中拥有极高效率。

但真正的软件工程，很少只有新代码。

工程团队的大部分时间，其实并不花在开发新功能，而是花在框架迁移、安全补丁、版本升级、依赖治理、代码重构等维护性工程。而这类工作的特点，恰恰不是“写出来”，而是“改得对”。

JDK 升级就是其中最典型的一类。从 旧版本升级到 JDK 21，看起来只是改一个版本号，实际上往往牵一发而动全身：Spring 框架兼容性、第三方依赖、编译插件、JVM 参数、启动脚本、测试用例，任何一个环节出问题，都可能导致服务无法启动。

一个典型的场景是：团队每季度都会讨论一次 JDK 升级，它几乎每个季度都会被提上技术规划，但真正启动的次数却很少。不是不知道该做，而是投入与风险之间的账始终很难算清。两三个开发者投入数周时间，承担升级风险，换来的只是版本号更新。

维护性工程真正困难的地方，也正在这里。写代码关注的是“能不能实现”，维护工程关注的是“能不能安全实现”。一个修改不仅要满足需求，还要遵守项目规范，通过编译、能够启动、通过测试，并且不破坏已有系统。这些约束，往往都藏在项目历史和开发经验里，而不是代码本身。

开始先尝试直接用 Vibe Coding 的方式完成这类工作。AI 确实能够完成部分修改，但在面对复杂依赖关系和长链路验证时，很容易逐渐偏离目标，出现如下问题：

JDK 升级是一个 系统工程 ，涉及：

• 依赖版本联动（传递依赖、内部 SDK）

• 配置多层级（父 POM、子模块、启动脚本、配置文件）

• 运行期行为变化（GC 策略、模块系统、日志框架）

  
  

AI 缺少一套能够约束工程执行过程的方法，最终导致修改范围失控、依赖关系混乱、配置相互冲突，只能终止升级。于是，我们开始思考：如何让 AI 在复杂工程中，也能像成熟工程团队一样稳定工作？

02

答案不在模型能力上，在系统设计上。我们实践使用 Harness Engineering 的方式，它的解决思路是：不过分依赖模型能力，而是通过系统设计约束 AI 的行为。如果把开发过程比作装修，Vibe Coding 更像告诉施工人员“你看着办”；Harness Engineering 则先给出施工图，把边界、规范和流程提前定义清楚，让执行过程尽可能减少猜测。

这套体系主要包括三部分：首先构建执行约束，让 AI 在明确边界内工作；随后沉淀工程经验，将一次实践转化为长期可复用能力；最后建立反馈闭环，让系统在实践中持续进化。三者串起来，就是一条“约束执行 → 经验复用 → 反馈进化”的链路。

▍构建执行约束：让 AI 在正确的边界内工作

项目上下文构建

回顾 Vibe Coding 的失败，我们发现，第一个急需解决的问题，并不是 AI 不知道如何升级 JDK，而是 AI 在不了解项目约束的情况下，就已经开始修改代码。

它不知道哪些文件由 Thrift 自动生成不能修改，不知道本地编译需加 -Plocal 参数，不知道 JVM 启动参数需要从 start.sh 脚本中提取。这些原本散落在资深开发者经验中的隐性知识，对 AI 来说就是看不见的暗礁。我们的第一步，就是把这些知识变成 AI 可消费的结构化规范——这就是 Harness Engineering 的起点：上下文工程。

核心是动态组装 Agent 每步所需的精确信息，避免过多或过少。我们构建了知识规范层，它们在其他场景也是通用的：

工程工具编排

有了上下文，AI 知道了项目边界。但紧接着第二个问题就来了：JDK 升级涉及的工程动作非常多样——扫描依赖树、解析冲突链路、执行集成测试、读取测试结果——如果每一项都让 AI 临场发挥，结果仍然不可控。于是我们构建了工具编排层：把工程动作封装成输入输出明确、失败路径清晰的可调用工具，让 AI 只需要视情况决定“调用哪个工具”，保证对固定问题表现稳定。

▍沉淀工程经验：把一次升级变成长期能力

每次升级，AI 都像从零开始，升级经验散落在对话、文档和开发者脑中，没有被结构化为 AI 能用的格式。因此，我们把执行过程中积累的工程经验沉淀成可复用的 Skill：jdk-upgrade。它是输入输出明确、可以长期复用的能力模块。 它回答以下问题：什么时候使用、任务的专家知识、不能做什么，按什么步骤做，什么时候结束。

## 【核心约束规范】> **所有升级操作必须严格遵守以下约束，违反任一条均属超出升级范围。**1. **禁止修改业务逻辑代码**。2. **禁止优化或重构业务方法**。3. **禁止添加新的业务功能**。4. **禁止删除或废弃原有功能**。5. **禁止修改接口的输入输出格式**。6. **仅进行必要的兼容性修改**，确保代码在 JDK 21 + Spring Boot 3.5.3 环境下正常编译和运行。

jdk-upgrade/├── SKILL.md                    # 主技能文档（概览 + 约束 + 执行步骤）└── references/    ├── maven.md                # Maven 插件升级详细配置    ├── dependency.md           # Pom 依赖处理详细列表    ├── jvm.md                  # JVM 参数调整详细方案    └── code.md                 # 代码兼容修改详细映射

### Step 1 — Maven 插件升级**目标**：使构建工具链支持 JDK 21 编译和 JUnit 5 测试。操作要点示例：- `maven-compiler-plugin` 升级至 `3.12.1+`，设置 `source/target=21`- `spring-boot-maven-plugin` 升级至 `3.5.3`- `maven-surefire-plugin` 升级至 `3.2.5+`### Step 2 — Pom 依赖处理**目标**：清除 javax 时代依赖，迁移至 Jakarta EE 体系。操作要点示例：- **移除**：`javax.annotation-api`、`javax.validation:validation-api`、`junit:junit`- **替换**：`javax.*` → `jakarta.*`- **升级**：`spring-boot-starter` → `3.5.3`、`lombok` → `1.18.32+`### Step 3 — JVM 参数调整**目标**：移除已废弃参数，适配模块系统和新 GC 体系。操作要点示例：- **移除**：所有 CMS 相关参数、旧版 GC 日志参数、PermGen 参数- **新增**：`--add-opens` 模块权限参数组、G1GC 或 ZGC 参数### Step 4 — 代码兼容修改**目标**：消除所有 `javax.*` 引用，迁移测试框架至 JUnit 5。操作要点示例：- **包名替换**：`javax.annotation` → `jakarta.annotation` 等- **JUnit 4 → JUnit 5 迁移**：`@Before/@After` → `@BeforeEach/@AfterEach`-(反馈闭环) 若编译失败，排查Step1到Step4可能存在的错误。### Step 5 — 验证- mvn clean compile -pl module>- mvn test -pl module>(反馈闭环) 若测试结论为不通过，基于测试报告的分析结果进行排查处理。

验证反馈循环是 Harness Engineering 中 ROI 最高的机制。它的核心是：每步操作后进行检查，防止错误传播。实践表明，验证循环可显著提升任务完成率，无需改模型或提示词。

在 JDK 升级场景中，我们采用了测试前置驱动的验证策略。

升级前：撰写集成测试。

我们要求 AI 针对项目的主要功能组件撰写集成测试，具体覆盖：

• 核心业务逻辑的链路验证。

• 关键依赖的兼容性验证。

• 关键组件的功能可用性验证。

测试撰写遵循严格的规范：

• 每个测试方法必须配置 @Timeout 注解，防止测试挂起。

• 每个测试必须真实完整加载 Spring 上下文，避免 mock 导致的假性通过。

• 每个测试必须能结构化的输出通过/不通过，和不通过时的错误原因，便于 AI 分析排查。

  
  

升级后：重新执行测试

升级完毕后，再次执行相同的测试集。如果测试通过，说明升级没有破坏已有功能；如果测试失败，AI 需要根据失败信息定位问题并修复。这种“测试前置 + 升级后验证”的循环，确保了升级的可验证性。AI 不再能够“谎报结果”——编译通过不代表升级成功，必须通过测试验证。

验证循环的另一个关键作用是防止错误传播。在升级过程中，AI 可能会做出错误的修改（如注释掉某个组件的注册）。如果没有验证循环，这些错误会一直累积，直到部署时才暴露。通过测试前置，我们能够在升级过程中及时发现并纠正这些错误。更重要的是，这套验证机制并不限于 JDK 升级，而是适用于绝大多数软件工程任务。一旦建立，便能够持续复用。

经验回流机制

验证循环保证了一次升级能够顺利完成，但 Harness Engineering 并不止于完成当前任务。更重要的是，如何把这次升级过程中积累的经验，转化为下一次升级可以直接复用的能力。

jdk-upgrade 解决了“如何执行升级”的问题，但还有一个问题：如何让每次升级的经验都能反哺下一次升级？因此设计了 jdk-upgrade-lessons Skill，这是一个经验沉淀 Hook。当 JDK 升级任务完成后，它会主动触发，总结升级过程中遇到的问题，生成结构化的经验文档，并基于这些经验生成新版本的升级 Skill。

1. 触发时机：当用户完成 JDK 升级任务后，Skill 会主动询问：JDK 升级已完成，是否需要回顾本次升级过程中遇到的问题，沉淀经验供后续参考？

2. 执行流程：Skill 自动按照 5 个步骤引导经验沉淀：

• 收集升级上下文：总结升级目标版本、项目类型、升级范围、升级耗时

• 引导经验回顾：按 5 个维度逐一整理——阻断性问题、隐蔽陷阱、配置遗漏、依赖冲突、代码迁移

• 生成经验文档：将收集到的经验整理为结构化文档，保存到项目目录

• 生成新版本技能：基于本次升级经验，生成优化后的新版本技能（如 jdk-upgrade-21）

• 确认与归档：向用户展示生成的经验文档，确认后归档

  
  

• SKILL 示例：

上述方法并非理论设计，而是在真实项目中持续验证。下面以一次典型的 JDK 升级为例。目标：从一个旧的 JDK 版本升级到 JDK 21+Spring Boot 3.5.3。

单个项目整体涉及 30+ 个文件修改、50+ 个依赖升级/新增/移除和大量的配置、启动参数修改。AI 承担了绝大部分工作：从项目分析、任务规划，到代码修改、编译调试和自动修复大部分启动错误。人工只需最终代码 Review 核验变更质量。

一轮对话完成升级比例”指在无人工介入的情况下，AI 单次对话即完成整个升级任务的比例。70% 的项目可一轮完成，剩余 30% 超过循环次数需要在关键节点人工介入。

升级完成后，多个服务的 CPU 使用率平均降幅约 22.5%；同等负载下堆内存平均下降约 23%。GC 改善尤为显著——每分钟 GC 停顿时间降至 1ms 以下，业务几乎无感。接口延迟方面，P99 平均降幅 18.1%，尾部延迟最大降幅达到 47%（548ms→288ms）。在 60% CPU 负载下，主要 Web 服务峰值 QPS 提升超过 30%（以上数据基于内部多个项目升级前后的生产环境监控对比）。

对于 JDK 升级这类长期积压的技术债，Harness Engineering 改变的不只是执行效率，更是成本结构。过去需要投入大量人力、反复评估 ROI，如今 AI 已经能够承担绝大部分工程工作，团队只需在关键节点进行决策和审查。这意味着，许多过去“知道应该做、却一直没有时间做”的工程优化，可以进入常态化执行。AI 的价值也从一次性的编码助手，真正演进为可持续的工程生产力。

03