跳转至

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

Ch05.040 从 Vibe Coding 到 Harness Engineering：小米 JDK21 升级中可控演进的 AI 工程实践

📊 Level ⭐⭐ | 15.1KB | entities/xiaomi-harness-engineering-jdk-upgrade.md

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

小米技术团队运用 Harness Engineering 方法论完成 JDK 21 + Spring Boot 3.5.3 升级的真实案例。核心框架：构建执行约束 → 沉淀工程经验 → 建立反馈闭环。

维护性工程（框架迁移、版本升级、安全修复）占工程团队大部分时间，传统 Vibe Coding 方式在处理这类任务时容易修改范围失控、依赖混乱、配置冲突。小米本次实践的核心洞察是：不是让 AI 更"聪明"，而是让工程体系能够持续约束、复用和进化 AI 的能力。

三部分框架

1. 执行约束

项目上下文构建：把隐性知识（Thrift 自动生成文件不可改、本地编译需 -Plocal 参数等）变成结构化规范。具体而言，团队产出了以下几类上下文资产： - 项目结构文档：描述模块划分、目录约定、文件归属规则 - 技术栈文档：明确 Java 版本约束、框架版本锁定、依赖管理策略 - 构建指南：编译参数、Profile 选择、环境变量要求 - 第三方集成约束：Thrift 接口访问规则、中间件客户端版本下限、禁止使用的 API 列表

工程工具编排：把工程动作封装为输入输出明确的工具，AI 只需调用。每个工具拥有清晰的签名、失败路径和预期输出，确保 AI 对不同项目的相同操作表现一致。工具包括但不限于：依赖树分析器、JVM 参数校验器、包名替换器、编译结果检查器。工具化的核心价值在于将"怎么做"从 AI 的推理过程中剥离，降低决策自由度，减少幻觉空间。

2. 经验沉淀（Skill 化）

jdk-upgrade Skill：5 步标准流程 + 6 条核心约束。标准流程覆盖了从构建工具链到最终验证的全链路：

  1. Maven 插件升级——目标使构建工具链支持 JDK 21 + JUnit 5，升级 Maven Compiler Plugin、Surefire Plugin 等核心插件
  2. Pom 依赖处理——完成 javax → Jakarta EE 迁移，处理包坐标变更（如 javax.servlet → jakarta.servlet）
  3. JVM 参数调整——移除 CMS 等 JDK 21 中废弃的 GC 参数，替换为 ZGC 或 G1GC 推荐配置
  4. 代码兼容修改——包名替换、import 语句更新、JUnit 4 → 5 迁移，含反馈闭环
  5. 验证——编译 + 测试双重验证，含反馈闭环

6 条核心约束确保 AI 不越界操作：禁止修改业务逻辑、禁止优化或重构、禁止添加新功能、禁止删除原有功能、仅做必要兼容修改、保持代码风格一致。

渐进式披露：SKILL.md 入口 + references/{maven,dependency,jvm,code}.md。这种分层知识组织方式避免 AI 一次性处理大量上下文导致注意力稀释。四个参考文件按执行阶段逐步加载——AI 先阅读入口文件理解全貌，在执行具体步骤时再按需查阅对应的 reference 文件。

jdk-upgrade-lessons Skill：升级完成后自动触发，5 维度经验总结 + 生成新版本 Skill。五个维度覆盖了升级工作的全部风险面：阻断性问题（导致编译失败的错误类型）、隐蔽陷阱（能编译但运行期出错的问题）、配置遗漏（被忽略但必需的非代码变更）、依赖冲突（版本兼容性和传递依赖问题）、代码迁移（API 变更和废弃方法替换）。总结完成后自动生成带版本号的演进版 Skill（如 jdk-upgrade-21），实现单次升级经验向下一轮的传递。

3. 反馈闭环

测试前置驱动验证：升级前 AI 撰写集成测试（@Timeout + 真实 Spring 上下文 + 结构化输出）→ 升级后重跑 → 失败则 AI 定位修复。

这一闭环的核心创新在于"测试先行"的策略——不是升级完成后才编写测试验证，而是在升级开始前就让 AI 产出测试套件。测试用例的设计遵循三个原则： - @Timeout：防止测试永远挂起，给 AI 一个明确的失败信号 - 真实 Spring 上下文：确保验证覆盖实际运行时行为而非仅编译层面 - 结构化输出：测试结果以机器可解析的格式输出，便于 AI 自动判断通过/失败

验证通过才确认升级成功，防止 AI "谎报结果"。这一机制从根本上解决了 AI 自主完成任务时的"乐观偏差"——AI 可能认为自己完成了正确修改，但只有真实运行的测试才具备最终裁定权。

效果数据

指标 结果
文件修改量 30+ 个文件 / 50+ 个依赖变更
一轮完成升级比例 70%（无人工介入单次完成）
CPU 使用率 平均降幅 22.5%
堆内存 同等负载下降约 23%
GC 停顿时间 降至 1ms 以下
P99 延迟 平均降幅 18.1%（最大 47%）
峰值 QPS 提升 30%+

70% 一轮完成率意味着在多数项目中，AI 无需人工介入即可独立完成整个升级流程。性能改善数据（CPU -22.5%、堆内存 -23%、P99 延迟 -18.1% 等）则说明，AI 严格按照 JDK 21 官方最佳实践进行的兼容性修改，不仅在功能层面无退化，还带来了客观的运行效率提升。值得注意的是，这些改善并非 AI 主动优化所致（约束禁止了优化行为），而是新版本 JDK + Spring Boot 自身的性能改进被顺利继承——这恰恰证明了"不做多余的事"这一约束的正确性。

核心贡献

  • 首次用 Harness Engineering 解决维护性工程（非新功能开发）——维护性工程占工程团队大部分时间，但此前 AI 辅助极少。本案例证明了将方法论文档化、工具化、Skill 化后，AI 在维护场景下的可靠性可以达到实用级别
  • 提出经验回流机制：通过 jdk-upgrade-lessons Skill 把一次升级经验反哺为下版本 Skill，形成"升级→总结→能力增强→升级"的递归增益循环
  • 验证"AI 文档的首要读者从人变为 AI"：规范不是为了约束人，而是为了约束 AI。项目文档、约束文件、工具定义的首要消费主体正在从开发者转变为 AI Agent
  • 确立渐进式知识披露模式：分层的 Skill 知识组织方式（入口 + 按需加载的 Ref）比起全量上下文更适合 AI 的工作模式，这一模式可迁移到其他维护性场景
  • "测试即合约"的创新实践：升级前的测试用例充当了 AI 执行的"合规检查合约"——通过才通过，不通过则必须在闭环中自我修复

深度分析

1. 从自由生成到约束执行：AI 工程化的范式转折

Vibe Coding 代表的是一种"高自由度、高依赖人工审查"的 AI 使用模式——AI 生成大量代码，开发者审查、修改、合并。但在维护性工程场景中，这种模式失效了：升级涉及大量跨文件的协调修改，任何一处遗漏都会导致编译失败或运行异常，人的逐行审查成本变得无法承受。Harness Engineering 提出的"构建约束先行"策略，本质上是把 AI 的工作方式从"自由生成→人工纠偏"转变为"预设边界→自动执行→自动验证"。小米的 JDK 升级案例是该范式转型的首个完整实证——它证明了在正确的约束体系内，AI 的可靠性能从"辅助工具"提升到"可信任的执行者"。

2. 维护性工程是 AI Agent 的理想场景

相比新功能开发（需求模糊、方案开放、创造性要求高），维护性工程具有天然适合 AI 执行的结构化特征：目标明确（某版本升至某版本）、路径已知（官方迁移文档、社区经验）、验证标准清晰（编译通过 + 测试通过）。本案例中的 70% 一轮完成率表明，当任务被充分结构化后，AI 的执行成功率可以达到工程可接受的水平。这与 从 Vibe Coding 到 Harness：大仓 AI 工程化 中的观察一致——工程化程度越高的任务，AI 表现越稳定。

3. 经验回流：知识复利的工程化实现

jdk-upgrade-lessons Skill 的设计将一次性的升级经验转化为可复用的组织资产，创造了知识复利效应。这一机制借鉴了软件工程中的"事后复盘"（Postmortem）实践，但将其自动化、结构化、Skill 化——每次升级完成后自动触发经验总结，生成下一版本的升级 Skill。这种递归增益循环意味着团队在 JDK 21 升级中积累的知识，将直接提升 JDK 22、JDK 23 升级的效率和质量。从组织学习角度看，这是将个体项目经验系统性地沉淀为组织能力的工程实践。

4. 反馈闭环是 AI 可靠性的最后一公里

本案例中最具实践价值的洞察之一是：AI 在执行复杂工程任务时，天然的"乐观偏差"需要通过工程机制来对抗。测试前置驱动验证将测试从"验证手段"提升为"合约执行器"——AI 在升级前就被告知"我会用这些测试来判定你是否成功"，这改变了 AI 的行为模式，使其更谨慎地执行修改。Regression Tax 研究 表明，缺乏闭环验证的 AI 技能会随使用次数增加而退化，而本案例中的反馈闭环正是对抗这种退化的有效手段。

5. 开发者角色的根本性转变

本案例中，小米开发者的核心工作不是写升级代码（这部分由 AI 执行），而是：定义约束边界、设计工具接口、编排执行流程、设计验证机制、总结升级经验。这验证了 Agent Skill 规范、构建与设计模式 中提出的"开发者从代码编写者转变为约束设计者"的预判。当 AI 承担执行层后，人的核心价值是定义"什么能做、什么不能做、做到什么程度"——工程规范正在成为比代码更重要的资产。

实践启示

1. 为 AI 写文档，而不是为人类写文档

工程规范、项目约束、升级指南的首要读者正在从开发者转变为 AI Agent。这意味着文档的结构化程度、精确性、机器可解析性比文笔优美更重要——使用结构化 Markdown、明确的 if-then 规则、可执行的约束断言，而非散文体的"最佳实践建议"。本案例中的 SKILL.md + references/ 体系提供了一个可直接复用的模板。

2. 测试即合约，让 AI 对其输出负责

升级前编写测试，比升级后编写测试更有价值。前置测试充当了"可执行的验收合约"——AI 知道自己的输出将被自动化测试检验，因此会更谨慎地避免越界修改。这一模式可以推广到任何 AI 执行的工程变更场景，包括依赖升级、框架迁移、配置变更等。

3. Skill 是组织工程记忆的载体

将升级流程封装为版本化、可复用的 Skill，使工程经验从"存在于个别开发者的脑中"转变为"存储在仓库中的可执行知识"。结合 技能治理与 AI 注册中心 中的思路，团队可以建立 Skill 的注册、发现、版本管理机制，让 AI 在执行任务时自动选择最匹配的 Skill 版本。

4. 渐进式披露优于全量上下文

AI 的上下文窗口有限，一次性输入所有约束和参考信息会导致注意力分散。分层的知识组织（入口概览 → 按需加载的深度参考）更符合 AI 的工作模式。本案例中的"SKILL.md 入口 + references/ 分阶段加载"模式，为构建可扩展的 AI 工程知识库提供了参考。

5. 量化 AI 工程实践的收益

小米团队不仅报告了"升级完成了"，还量化了性能改善数据（CPU、内存、延迟、吞吐量）。这为 AI 工程实践的价值论证提供了有力支撑——当管理者看到 AI 驱动的升级带来 22.5% CPU 下降和 30%+ QPS 提升时，"为什么要用 AI 做维护"的回答就变得清晰。建议其他团队在推进类似实践时，也建立量化指标体系来追踪 AI 工程化的收益。

相关实体