【AI智能体】Harness Engineering 驾驭工程从使用到项目实战详解

目录

一、前言

[二、Harness Engineering 介绍](#二、Harness Engineering 介绍)

[2.1 Harness 基础概念](#2.1 Harness 基础概念)

[2.2 AI 工程范式三次跃迁](#2.2 AI 工程范式三次跃迁)

[2.3 Harness 实际价值](#2.3 Harness 实际价值)

[2.3.1 Harness 与传统框架的关系](#2.3.1 Harness 与传统框架的关系)

[2.3.2 Harness 解决了哪些问题](#2.3.2 Harness 解决了哪些问题)

[三、Harness 核心组件](#三、Harness 核心组件)

[3.1 上下文工程](#3.1 上下文工程)

[3.2 Agent 专业 (Agent Specialization)](#3.2 Agent 专业 (Agent Specialization))

[3.3 持久化记忆](#3.3 持久化记忆)

[3.4 结构化执行 (Structured Execution)](#3.4 结构化执行 (Structured Execution))

[3.5 架构约束(Architecture Constraints)](#3.5 架构约束(Architecture Constraints))

[3.6 反馈循环(Feedback Loop)--智能体审智能体](#3.6 反馈循环(Feedback Loop)--智能体审智能体)

[3.7 熵管理(Entropy Management)](#3.7 熵管理(Entropy Management))

[3.8 Harness 五大原则](#3.8 Harness 五大原则)

[3.9 Anthropic：长时间运行Agent 的有效 Harness](#3.9 Anthropic：长时间运行Agent 的有效 Harness)

[3.10 Harness 行业应用落地准则](#3.10 Harness 行业应用落地准则)

[四、Harness 开发项目实战](#四、Harness 开发项目实战)

[4.1 基于Harness 开发springboot 项目](#4.1 基于Harness 开发springboot 项目)

[4.1.1 开发前的准备](#4.1.1 开发前的准备)

[4.1.2 三阶段说明](#4.1.2 三阶段说明)

[4.1.3 生成项目文档](#4.1.3 生成项目文档)

[4.1.4 设计文档规范](#4.1.4 设计文档规范)

[4.1.5 生成标准工程包结构](#4.1.5 生成标准工程包结构)

[4.1.6 生成项目代码](#4.1.6 生成项目代码)

[4.1.7 阶段3 ：自动化层，Agent 自我验证和修复](#4.1.7 阶段3 ：自动化层，Agent 自我验证和修复)

[4.1.8 可观测性监控接入](#4.1.8 可观测性监控接入)

[4.1.9 增加配置文件](#4.1.9 增加配置文件)

[4.2 开源工具落地实施](#4.2 开源工具落地实施)

[4.3 SDD 规范驱动开发](#4.3 SDD 规范驱动开发)

[4.3.1 什么是规范驱动开发？](#4.3.1 什么是规范驱动开发？)

[4.3.2 合格的规范文档要求](#4.3.2 合格的规范文档要求)

[4.3.3 SDD核心理念](#4.3.3 SDD核心理念)

[4.4.4 SDD与多AI协同](#4.4.4 SDD与多AI协同)

五、写在文末

---

一、前言

2026年，AI编程的飞速发展带来了编程领域的大变革，借助AI编程，传统单靠人力编码的开发模式得到彻底重塑，一个程序员，借助AI编程，可以大大提升编码的效率和编码质量，甚至是快速进入一门全新的开发领域所需要的编程领域，但快速发展的同时，在众多的实践中也发现了诸多的问题，这些问题背后的核心焦点是，如何在借助AI编程高效完成开发的同时，也能限定AI写出来的代码是符合预期要求的，即在编码的质量上得到保证，基于这个核心痛点，业界注解形成了以Harness Engineering 理念为潮流的驾驭工程设计，本篇将详细介绍下驾驭工程的实践。

二、Harness Engineering 介绍

2.1 Harness 基础概念

AI大模型如今已经能产出100万行级别的代码，摆在我们面前的真正难题，不再是让它写的更聪明，而是如何让它稳定、可靠、不会脱缰的持续工作。

• 围绕AI智能体约束设计，反馈和控制系统的这一套方法论，正是2026年在工程圈迅速走红的新潮流，Harness Engineering （驾驭工程）。

• Harness Engineering(驾驭工程)是一种系统级工程实践，它聚焦于围绕 AI智能体搭建约束体

馈机制、流程编排和持续迭代闭环。

Harness engineering 学习指南：https://github.com/deusyu/harness-engineering

Hamness engineering 生态全貌：https://harness-engineering.ai/

2.2 AI 工程范式三次跃迁

要明白驾驭工程为何在这个节点出现，我们得先回头看一看，整个AI工程是怎么一步步走到今天

|--------|---------------|-----------------|-----------------|
| 范式 | 关注的问题 | 优化对象 | 互动方式 |
| 提示词工程 | 如何把话说明白 | Prompt的措辞、结构、范例 | 单轮问答 |
| 上下文工程 | 如何向AI喂料 | 文档、代码段、历史会话 | 注入信息 一 生成结果 |
| 驾驭工程 | 如何让Agent 可靠稳定 | 约束，反馈，控制系统 | 人类把握方向，Agent 干活 |

Harness 优化的对象不是模型本身，而是模型所在的运行环境，一句话总结：人类把握方向，智能体执行。

驾驭工程从来不是给AI带上紧箍咒削减其能力，而是给它打造一个最佳的执行环境，让它跑的飞快且不失控。

一个好记的类比:

• Prompt Engineering：对马喊话的技巧

• Context Engineering： 给马看的地图

• Harness Engineering： 给马造一条高速公路，配上护栏、限速牌和加油站

2.3 Harness 实际价值

2.3.1 Harness 与传统框架的关系

Harness 不是要替代SDK、脚手架或者Agent框架，而是在叠加在它们基础之上的一层：

• 传统框架回答的是怎么搭建出一个AI智能体，而驾驭工程处理的是怎么让这个智能体跑的快，跑得稳。

• 事实上，模型本身正在把框架80%左右的能力，智能体定义、消息分发、任务生命周期等逐步内化进去，但剩下的20%，比如持久化、可复现重放、成本管控、可观测性、错误自愈等，恰恰是驾驭层存在的重要意义。

2.3.2 Harness 解决了哪些问题

Anthropic 工程师在长期跑Agent实战过程中总结出3种常见的翻车姿势，恰好是驾驭工程需要正面回应的核心问题：

问题1：试图一步到位

Agent习惯在单个会话里把所有事情一次性搞定，结果就是上下文窗口被撑破，留下一堆没文档的半成品，等下一轮会话起来时，只能靠瞎猜上一次做了什么。

问题2：提前宣布胜利

在项目进展到后期，看到已经有部分功能跑起来了，Agent就会环顾一圈宣布任务完成，哪怕还有一大堆功能根本没有动。

问题3：没有验证就标记完成

如果没有明确指令，Agent写完代码就直接打钩，跳过端到端验证，要知道单元测试或者一条curl命令跑通，根本不等于功能真的好用。

除此之外，智能体还有一个值得警惕的特性，它很擅长依葫芦画瓢，代码仓里是什么风格，它就照单全收复刻并放大，包括一些糟糕的写法，换句话说，没有约束的Agent会以惊人的速度堆积技术债。

三、Harness 核心组件

下面介绍一下Harness 体系下的核心组件。

3.1 上下文工程

相当于新人入职手册，好比给新入职员工了一本上手指南，AGENTS.md就是AI智能体接入代码仓库时翻开的第一页。

• 但是决不能写成一本厚厚的静态说明书，上下文是宝贵的资源，一次性喂的太多会挤掉真正的该承载任务'代码和文档空间，最后沦为陈年规则的存档地。

• 更聪明的做法是：留一个小而稳定的入口，再训练Agent学会按当下任务自己去检索，按需拉取更多上下文。

实践建议：三层上下文体系

|--------------|------------------|-----------------------------|-----------|
| 层级 | 加载时机 | 内容示例 | 上下文占用 |
| Tier 1：会话常驻 | 每次会话自动加载 | AGENTS.md /CLAUDE.md，项目结构概览 | 最小 |
| Tier 2：按需加载 | 特定子Agent 或技能被调用时 | 专业化Agent的上下文、领域知识 | 中等 |
| Tier3：持久化知识库 | Agent主动查询时 | 研究文档、规格说明、历史会话 | 按需 |

3.2 Agent 专业 (Agent Specialization)

核心原则：专注于特定领域、拥有受限工具的Agent优于拥有全部权限的通用Agent。

• Carlini(Anthropic C编译器项目)将Agent 专业化为编译器核心、去重、性能优化和文档四类角色。

• Vasilopoulos 部署了19个领域特定 Agent。

• Huntley 使用子 Agent 来保持主 Agent 上下文的清洁。

专业化不仅是组织性的一-它本身就是上下文管理策略。每个专家因为携带更少的无关信息，所以运行在"Smart Zone'内。

实践中的角色分工：

|------------------|---------------|-----------------------|
| Agent 角色 | 职责范围 | 工具权限 |
| 研究Agent | 探索代码库、分析实现细节 | 只读 (Read, Grep, Glob) |
| 规划Agent | 将需求分解为结构化任务 | 只读，无写入权限 |
| 执行Agent | 实现单个具体任务 | 限定范围的读写权限 |
| 审查Agent | 审计完成的工作，标记问题 | 只读+标记权限 |
| 调试 Agent | 修复审查发现的问题 | 限定范围的修复权限 |
| 清理Agent | 对抗熵积累，清理低质量代码 | 读写权限 |

3.3 持久化记忆

核心原则：进度持久化在文件系统上，而非上下文窗口中。每次新Agent 会话从零开始，通过文件系统制品重建上下文。

Anthropic解决这一问题的方案堪称经典：

• 初始化 Agent：

  • 首次会话使用专门的prompt，要求模型建立初始环境-init.sh脚本、claude-progress.txt 进度文件和初始 git提交。

• 编码Agent：

  • 后续每次会话要求模型在做出增量进展的同时，留下结构化更新。

每个 编码 Agent的典型会话启动流程如下：

1. 运行pwd查看工作目录

2. 读取git log和进度文件，了解最近的工作

3. 读取featurelist文件，选择最高优先级的未完成功能

4. 启动开发服务器，运行基础端到端测试

5. 确认基本功能正常后，开始新功能开发

关键发现：使用JSON格式追踪feature 状态比 Markdown更有效，因为Agent 不太可能不恰当地修改或覆盖结构化数据。

3.4 结构化执行 (Structured Execution)

1. 核心原则：

   1. 将思考与执行分离。研究和规划在受控阶段进行，执行基于验证过的计划，验证通过自动化反馈(测试、Linter、CI)和人类审查完成。

2. 所有团队都施加了刻意的执行序列：

   1. 理解一规划一执行一验证。

OpenAI使用声明式prompt和反馈回路。轻量的计划用于小变更，复杂工作通过带有进度和决策日志的执行计划完成,并检入仓库。

• Huntley 将规划模式与构建模式分离。

• Horthy 的Research-Plan-Implement 工作流围绕上下文管理精心设计。

• 人工检查点的价值：审查计划远比审查代码快。当规格正确时，实现自然可靠。当规格有误时，可以在500行代码生成之前及时纠正。

3.5 架构约束(Architecture Constraints)

OpenAI团队建立了严格的层级依赖模型:

• Types -> Config -> Repo -> Service -> Runtime ->UI

• 下层不能反向依赖上层。所有架构规则被编码为自定义Linter规则，违反即CI阻止合并-无论代码是人写的还是AI写的。

有个关键细节：Linter的错误信息本身也是上下文工程。它不只说你违反了规则X，而是解释为什么这个规则存在、正确做法是什么，这样Agent读到错误后就能自我理解并修正，不需要人类介入。

3.6 反馈循环(Feedback Loop)--智能体审智能体

传统开发中，人类工程师负责代码审查(Code Review)。在驾驭工程中，这个工作变成了智能体对智能体的方式:Codex在本地审核自身更改，请求额外审查，循环往复直到通过。

反馈循环中的钩子可以运行预定义的测试套件，并在失败时带着错误信息循环回到模型，或者提示模型独立评估其代码。如果AI写的测试用例通过了带有Bug的代码，Harness就会判定测试无效，强迫它重新思考测试边界。

3.7 熵管理(Entropy Management)

随着时间推移，软件系统会逐渐混乱(熵增)，技术债务会积累。OpenAI采用持续小额偿还的策略，而不是等问题严重时集中处理-他们把这个方法形象地称为垃圾回收，并认为技术债务就像高息贷款。

具体措施:定期运行后台Codex任务扫描偏差、更新质量等级、发起针对性重构PR。此外还有一个专门的Doc-gardeningAgent(文档园丁代理)，在后台自动扫描文档与代码之间的不一致，发现过时内容就自动提交PR修复Agent为Agent 维护文档。

3.8 Harness 五大原则

1. 原则1:

   1. 设计环境，而非编写代码。工程师的工作转向为Agent准备高效运行的环境。当Agent卡住时，不是"更加努力"，而是诊断"缺少什么能力"并让Agent自己构建该能力。

2. 原则2:

   1. 机械化地执行架构约束。他们为每个领域定义了依赖方向-> Types-> Config-> Repo-> Service-> Runtime-> UI-> 并用自定义Linter和结构测试自动检测违规。文档中记录是不够的，如果不能机械化地强制执行，Agent 就会偏离。

3. 原则3:

   1. 将代码仓库作为唯一事实源。写在Slack讨论或Google Docs中的知识对Agent来说等于不存在。所有团队知识都作为版本控制的制品放置在仓库中。

4. 原则4:

   1. 将可观测性连接到Agent。他们将Chrome DevTools连接到运行时，使Agent 能够捕获DOM快照和截图。通过赋予查询日志和指标的能力，"将启动时间降至800ms以下"变成了可度量的目标。

5. 原则5:

   1. 对抗熵。最初团队每周五花20%的时间手动清理"AI Slop"(低质量生成物)。这后来被自动化为Codex运行的后台任务--清理吞吐量与代码生成吞吐量成正比扩展。

自定义Linter 的巧妙设计:当Agent违反架构约束时，错误消息不仅标记违规-还告诉Agent 如何修复。工具在Agent工作时同时"教会"它。

3.9 Anthropic：长时间运行Agent 的有效 Harness

Anthropic工程团队从另一个角度切入--跨上下文窗口的连续性问题--来研究Harness设计

核心痛点：长时间跑的Agent必须在一个个独立会话里工作，每次新会话启动时对前一次做了什么一无所知。就像一个项目组全是轮班工程师，每个人上岗时对之前的进展一脸懵。

两阶段解决方案:

• 初始化 Agent

  • 使用专门的 prompt 建立初始环境，包括init.sh 脚本、claude-progress.txt 进度日志和初始 git 提交。

• 编码Agent

  • 每次后续会话要求模型做出增量进展，然后留下结构化更新。

3.10 Harness 行业应用落地准则

综合 OpenAl、Anthropic、LangChain、Stripe、HashiCorp 等多个独立信息源，业界在以下六个方面已形成明确共识：

|--------|----------------|-----------------------------------------------------------|
| 编号 | 共识 | 核心观点 |
| 1 | 瓶颈在基础设施，不在模型智能 | 五个独立团队得出相同结论。仅改变Harness工具格式，就能让模型得分从6.7%跳至68.3% |
| 2 | 文档必须是活的反馈循环 | 静态文档是坟场，动态文档才有价值。让后台Agent 定期清理过时文档并提交PR |
| 3 | 思考与执行分离 | 复杂任务不可能在单个上下文窗口内完成，需要 Orchestrator+Worker 分层架构，状态持久化到外部存储 |
| 4 | 上下文不是越多越好 | 上下文是稀缺资源。巨大的指令文件会挤掉任务空间，应按需检索、动态注入 |
| 5 | 约束必须自动化 | 人工 Review 是瓶颈。护栏要编码为Linter、CI、类型系统，让机器来执行而非人 |
| 6 | 工程师角色在转变 | 从代码的编写者变成环境的建筑师。最大的工程挑战是设计让Agent 可靠工作的控制系统 |

四、Harness 开发项目实战

4.1 基于Harness 开发springboot 项目

4.1.1 开发前的准备

需求: 基于 Harness Engineering 从O到1开发一个Java项目

技术栈：Spring Boot 3.2.x + Java 17 + Maven 3.6.3

在开始之前，基于 Harness Engineering 的思想，先画清楚路线。Harness Engineering的落地不是"一把梭"，而是渐进式的，如下，针对本次的开发，给出下面3个阶段的规划：

注意：

• 不要一步到位。很多人失败就在于想一次性搭完所有基础设施。阶段1已经能带来显著提升，阶段2是质变点，阶段3是锦上添花。

4.1.2 三阶段说明

对上述规划的3个阶段的内容分别做详细的说明。

阶段1：信息层让Agent"看得懂"你的项目

• AGENTS.md:写地图，不写百科全书

• OpenAI用"地图模式",替代超长指令文件。这里给出可以直接拷贝使用的模板。

反面教材：

• 问题:挤占上下文窗口、难以维护、Agent很难定位需要的信息。

#X错误示范:把所有内容塞进一个文件
我d用 Spring Boot 2.7.18 + Java 1.8 + Maven 3.6.3 + MySQL 5.7...
类命名使用 PascalCase,方法用 camelCase,常量用 UPPER_SNAKE_CASE...
ORM 用 MyBatis-Plus，迁移用Flyway，缓存用 Caffeine...
(后面还有500行)

正确做法：

# AGENTS.md

# 项目简介
[一句话]这是一个面向中小企业的在线项目管理平台，基于SpringBoot 3.2.x+Java 17+MySQL8.0。

## 技术栈基线(不允许擅自升级)
- JDK:17,不可使用 Java 9+ 语法(record/var/text blocks)
- Spring Boot:3.2.x
- Maven:3.6.3,由 enforcer 强制
- 数据库:MySQL8.0(utf8mb4)
- 持久化:MyBatis-Plus 3.5.x (基于 MyBatis 3.5) + Flyway (含flyway-mysql 子模块)，不引入 JPA

## 快速导航
| 你想做什么 | 去哪里看 |
|-----------|---------|
| 了解系统架构 | docs/architecture/overview.md |
| 了解模块边界和依赖规则 | docs/architecture/boundaries.md |
| 了解编码规范 | docs/conventions/README.md |
| 了解当前迭代任务 | docs/plans/current-sprint.md |
| 了解 API 规范 |  docs/reference/api-spec.yaml |
| 了解错码 |  docs/reference/error-codes.md |
| 了解测试规范 | docs/conventions/testing.md |

## 硬性规则(必须遵守，CI会验证)
1、依赖方向: domain > config  mapper > service > controller
2、横切关注点(auth/log/telemetry)只能通过 Spring 注入，禁止 'new' 实例化
3、单文件(.java) ≤300 行;单方法≤50行
4、禁止 `System.out.println/ e.printStackTrace()`，统一使用 SLF4J `Logger`
5、禁止裸 RestTemplate/ HttpURLConnection，统一通过 ApiClient 抽象
6、禁止字段级 @Autowired，必须构造器注入(推荐Lombok @RequiredArgsConstructor2)或者@Resource注解
7、新增代码必须有对应JUnit5测试，行覆盖率≥80%

## 提交规范
- feat: 新功能
- fix: 修复
- refactor: 重构
- docs: 文档
- test: 测试

关键设计原则：

• AGENTS.md控制在50-100行。超过就说明你在写百科全书了

• "你想做什么一去哪里看"比" 这是什么"更有效--面向任务而非面向知识

• 硬性规则单独列出，这些是CI会强制验证的，不是"建议"

结构化知识库doc目录：

• 用于存放项目在长期运行、维护和迭代过程中沉淀下来的各种知识文档和文件

如下是一个参考的doc目录：

docs/
├── architecture/
│   ├── overview.md
│   ├── boundaries.md
│   └── data-flow.md
│
├── conventions/
│   ├── README.md
│   ├── naming.md
│   ├── error-handling.md
│   ├── testing.md
│   └── logging.md
│
├── design/
│   ├── feature-auth.md
│   ├── feature-search.md
│   └── feature-billing.md
│
├── plans/
│   ├── current-sprint.md
│   └── backlog.md
│
└── reference/
    ├── api-spec.yaml
    └── error-codes.md

4.1.3 生成项目文档

创建一个项目工程目录，这里以Codex 为例进行说明，在工程目录下创建.codex 目录，然后将上面的ANENTS.md文件放进去

在Codex 中打开项目目录可以看到规则文件已经加载进来了

然后让Codex 按照上面的知识库目录，为当前项目生成相应的文档

经过一段时间响应之后最终按照要求得到了相应的文件目录

每个文件目录下的文档模板也有了

为了方便后续文档的自动更新，再给每个文档头部增加下面的信息

4.1.4 设计文档规范

在后续Agent执行复杂功能前，先写设计文档。下面是一个规范模板，通过这个模板，可以让AI 每次开发功能之前，先出设计方案：

# Feature: [功能名称]

## Status: 📝 Draft | 📋 Approved | 🚧 In Progress | ✅ Implemented

## 目标
一句话描述这个功能要解决什么问题。

## 非目标
明确列出这次不做什么（防止 Agent 扩大范围）。

## 技术方案

### 涉及的模块
- domain/     : 新增 XXX 实体（@TableName）与 DTO
- mapper/     : 新增 XXXMapper extends BaseMapper<XXX>
- service/    : 新增 XXXService 业务逻辑
- controller/ : 新增 /api/xxx 端点

### 数据模型变更
```sql
-- 如有数据库变更，写在这里（Flyway 迁移脚本路径: src/main/resources/db/migration/V__xxx.sql）

为什么要这么做？

Agent拿到一个功能需求后，先填写这个模板(或人工填写)，审批通过后再动手写代码。这就是"明

确意图"的工程化实现。

4.1.5 生成标准工程包结构

为了让AI生成的代码是符合我们预期的工程规范要求的，定义下面的标准结构：

src/main/java/com/example/app/
├── domain/         # 领域模型与 DTO（不依赖任何业务包；纯 POJO + MyBatis-Plus Entity）
│   ├── model/      # MyBatis-Plus Entity（@TableName / @TableId / @TableField）/ Value 
│   └── dto/        # Request/Response/Command/Query（Java 17 用 Lombok @Value 模拟 record）
├── config/         # Spring 配置类、@ConfigurationProperties、@MapperScan、MybatisPlusInterceptor
├── mapper/         # MyBatis-Plus Mapper 接口（extends BaseMapper<T>; 只依赖 domain、config）
├── service/        # 业务逻辑（依赖 domain、config、mapper）
├── controller/     # REST Controller、@ControllerAdvice 全局异常处理
└── infrastructure/ # 横切关注点：ApiClient、日志、指标、安全

在当前的会话窗口中，让Codex 基于上面生成的规范文件，结合本次的工程规范要求，生成项目结构

4.1.6 生成项目代码

基于上面的项目模版，以及相关的规范文档，开始生成代码，给出下面的提示词

基于上面的工程目录结构，开始生成代码，第一版增加员工管理模块的功能，包括：员工的增删改查，参考当前的项目规范文档去做，生成完毕后，注意跑一下单元测试，pom文件中目前还没有引入依赖，整体的技术栈在AGENTS.md中有说明

通过输出日志可以看到，Codex 按照规范要求文档以及本次的说明，先导入依赖，然后写代码，最后做单元测试用例编写和验证

4.1.7 阶段3 ：自动化层，Agent 自我验证和修复

当项目持续往前推进过程中，随着时间的推移，承载的业务越来越多，文档也越来越多，有一些垃圾代码也会越来越多，在实际的项目中，需要定期对项目代码进行review ，对项目相关的文档进行定期更新维护，这个是一项非常大的工作量，现在有了AI之后，可以专门开启一个自动化任务Agent 来处理这件事，参考下面的编排提示词：

• 在Codex 中，做自动化任务编排很容易，只需要把下面的规则通过对话框输入，并加上一句：帮我每周3自动执行一次，并且输出报告，Codex 即可做成一个自动化任务定时执行

# 任务：代码库卫生清理

请执行以下检查，对每个发现的问题生成独立的修复 PR：

## 检查清单
1. **超长文件**：找出 src/main/java/ 下超过 300 行的 .java 文件，拆分为更小的类
2. **缺失测试**：找出 src/main/java/ 下没有对应 *Test.java 的类，补充基础测试
3. **未使用的 import**：清理所有未使用的 import 语句
4. **TODO/FIXME**：列出所有 TODO 和 FIXME，超过 30 天未处理则生成清理 PR
5. **重复代码**：找出高度相似的代码段（>10行），提取为共享工具类（infrastructure/）
6. **过时文档**：检查 docs/design/ 中状态为 Draft 但已超过 30 天的文档
7. **Checkstyle/SpotBugs 历史告警**：清理 mvn verify 中累积的非阻塞告警

## 约束
- 每个修复作为独立 PR，不要混在一起
- 每个 PR 修改后必须确保 `mvn -B clean verify` 通过
- PR 标题格式：`chore(cleanup): [具体描述]`
- 不允许使用 Java 9+ 语法（record/var/text blocks），保持 JDK 1.8 兼容
- 不允许升级 Spring Boot 主版本（保持 2.7.x）
- 如果不确定某个修改是否安全，跳过并在 PR 中标注原因

4.1.8 可观测性监控接入

有过线上项目运维经历的同学应该知道，为了有效监控服务发布在线上环境之后，服务的各项运行指标，是否监控运行，通常会将服务对接第三方监控平台，比如微服务领域经常对接的 prometheus + grafana ，下面是一个本地服务接入的容器服务编排文件

version: '3.8'

services:
  loki:
    image: grafana/loki:2.9.0
    ports: ["3100:3100"]

  promtail:
    image: grafana/promtail:2.9.0
    volumes:
      - ./logs:/var/log/app
      - ./promtail-config.yml:/etc/promtail/config.yml

  prometheus:
    image: prom/prometheus:latest
    ports: ["9090:9090"]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports: ["3001:3000"]
    depends_on: [loki, prometheus]

Spring Boot 项目中需开 Actuator + Micrometer Prometheus (已包含 actuator starter 中) ：

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  metrics:
    tags:
      application: ${spring.application.name}

4.1.9 增加配置文件

在初始化的项目中还没有配置文件，这些项目的配置信息，可以手动添加，也可以让AI基于生成的项目自己生成

总结：

Harness Engineering 的核心不是搭建一套复杂的基础设施，而是一个简单的闭环，约束 ->告知 -> 验证 -> 纠正，从AGENTS.md和一条ArchUnit 规则开始，比什么都不做强一百倍。

4.2 开源工具落地实施

在使用Harness 推进项目落地过程中，会涉及到使用各种开源工具的协同配合一起完成，以上述的springboot项目为例，在项目开发过程中会涉及到各种技术组件，比如JDK,maven，单元测试组件 junit ，可观测性组件Prometheus 等，这里就涉及到一个工具组合额选择和落地实践，下面这个全景图给出了一个参考：

┌───────────────────────────────────────────────────────────────┐
│        你的项目代码仓库（Spring Boot 2.7 / JDK8）              │
└───────────────────────────────┬───────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
┌───────▼────────┐      ┌───────▼────────┐      ┌───────▼────────┐
│ 阶段1：信息层  │      │ 阶段2：约束层  │      │ 阶段3：自动化层 │
│                │      │                │      │                │
│ • AGENTS.md    │      │ • ArchUnit     │      │ • Git Worktree │
│ • docs/ 结构   │      │ • Checkstyle 9.3│     │ • Actuator + Loki│
│ • Aider Repo Map│     │ • SpotBugs/JaCoCo│    │ • Prometheus    │
└───────┬────────┘      │ • maven-enforcer│     └───────┬────────┘
        │               └───────┬────────┘             │
        └───────────────────────┼───────────────────────┘
                                │
                         ┌──────▼──────┐
                         │ Agent 工具  │
                         │ （选一个）  │
                         │             │
                         │ Aider       │
                         │ Cline       │
                         │ Claude Code │
                         │ OpenHands   │
                         │ Cursor      │
                         │ Codex       │
                         └─────────────┘

Agent 工具对比与选型

|-------------|-----------|---------------|---------------------|-----------------|
| 工具 | Stars | 类型 | 最适合的场景 | Harness 友好度 |
| Aider | 30k+ | CLI 结对编程 | 个人开发者，终端党 | ⭐⭐⭐⭐⭐ |
| Cline | 40k+ | VS Code Agent | 小团队，需要 Plan/Act 模式 | ⭐⭐⭐⭐ |
| Claude Code | - | CLI Agent | 深度自主任务（6h+ 连续工作） | ⭐⭐⭐⭐⭐ |
| OpenHands | 50k+ | 平台 | 团队级部署，需要沙箱隔离 | ⭐⭐⭐⭐⭐ |
| SWE-agent | 15k+ | CLI Agent | 自动修复 GitHub Issue | ⭐⭐⭐ |
| Superpowers | 127k | 技能框架 | 强制 TDD + 子 Agent 模式 | ⭐⭐⭐⭐⭐ |

4.3 SDD 规范驱动开发

4.3.1 什么是规范驱动开发？

SDD(Specification Driven Development，规范驱动开发)是一种'先把说明书写清楚，再动手写代码"的开发方法、

换个生活化的角度理解SDD，可以想象你要盖一栋房子:

走传统路线(边干边想):

1、直接抄起砖头开砌

2、发现哪里不对就拆掉重来

3、不停返工，时间全耗在反复推倒上

走SDD路线(规范先行):

1、先把建筑图纸画详细-也就是spec.md规格文档

2、图纸里写明:房子尺寸、房间数量、水电走向等所有细节

3、照图纸施工，由A自动产出代码、测试和文档

1、和传统开发模式的对照

• 传统开发: 需求一> 设计一> 程序员于上般代码 一> 测试

• SDD开发：需求 -> 细致的规范（spec.md） -> AI自动生成 -> 体系化验证

2、三处根本差异

• 规范才是唯一的真理来源

• 代码不过是规范的副产品

• 质量由验证体系来兜底

3、SDD的四步工作链路

1. Specify（写规范）

   1. 用自然语言把要做的事情讲清楚

2. Plan（定方案）

   1. 设计技术路线和整体架构图

3. Tasks（拆任务）

   1. 切成一条条具体的待办清单

4. Implement（AI落实）

   1. AI 按照规范把代码生成出来

4.3.2 合格的规范文档要求

一份好的规范要具备如下5个要素：

1. 目标与价值

   1. 这件事到底解决什么问题

2. 上下文约束

   1. 技术栈是什么？性能要求？依赖关系...

3. 功能性需求

   1. 核心行为与关键特性

4. 非功能性需求

   1. 安全、性能、可扩展性

5. 验收口径

   1. 怎么判断这个事情真的做成了

一句话总结：

• 先把说明书（规范文档）写细致，再让AI产出代码，最后让质量闸门来把关。

4.3.3 SDD核心理念

SDD核心理念如下：

1. 设计走在前面

   1. 先用自然语言（中文/英文）把要做什么写清楚

   2. 规格文档（spec.md）是唯一的真理来源

2. 一切AI自动生成

   1. 代码自动产出、测试自动产出、技术文档自动产出

3. 文档会过期

   1. 传统开发里遇到的一个问题，代码改完了，文档常常忘了同步

   2. SDD模式：只需要更新spec.md，其余内容自动跟着变

实践中的几点启示：

• AI编程不能放任AI自由发挥，必须有规范行为约束

• 一份好的规格文档抵得过上千行代码，把要什么讲清楚远比讨论怎么做更重要

• 理想与现实需要平衡，SDD理念再美好，也得结合实际情况去执行

4.4.4 SDD与多AI协同

目前使用AI编程中要面对的核心问题：

1. 跑得太快容易跑偏，AI生成代码速度飞快，可结果往往对不上需求

2. 频繁返工：单个AI在面对复杂业务时能力捉襟见肘时，错误一抓一大把

3. 成本高，效率低，所有的事情都让最贵的模型去干，资源浪费严重

破局思路：SDD+多AI协同

1、SDD（规范驱动开发）的四阶段流程，把开发过程划成4步走，就像盖房子需要先画图：

Specify（写规范）：用中文把要做什么讲清楚（需求文档）
-> Plan (做规划)：设计怎么做（技术方案）
-> Tasks（拆任务）：列出每一步（任务清单）
-> Implement（写代码并校验）：让AI按步骤产出代码并完成自我校验

OpenSpec 工具：规范管理的好帮手

OpenSpec 是一款命令行工具，专门用来帮你打理整个开发流程，包含3个核心目录：

specs/       <- 已完成的功能规范（项目说明书）
changes/     <- 进行中的新功能（施工方案）
archive/     <- 已归档的历史变更（施工档案）

这套工具的工作流循环过程：

1. 起草提案（proposal.md），说明这次要变更什么

2. 写出任务清单（task.md）

3. AI 按清单把代码实现出来

4. 完成之后归档到 specs/ ，同步刷新项目规范

多AI协同：让每个模型都干自己擅长的事

Claude + Codex + Gemini的三模型协同方案，就像在组一支技术团队，充分利用不同模型的特长

|--------|-------|-------------------|---------------|
| AI 模型 | 担当角色 | 核心擅长 | 类比 |
| Claude | 项目经理 | 读懂复杂业务、协调和调度其他 AI | 既懂需求又会规划的产品经理 |
| Codex | 资深工程师 | 专注代码生成与重构 | 技术大牛，代码又快又稳 |
| Gemini | 文档分析师 | 大体量文档分析、多模态处理 | 什么资料都看得懂的助理 |

将上面的规范文档目录投递给Codex

打开项目目录，可以看到已经按照要求生成了几个规范文档和目录

五、写在文末

本文通过较大的篇幅详细介绍了Harness Engineering （驾驭工程）的使用，并且通过一个实际案例操作演示了如何在实际项目开发中基于Harness Engineering的思想进行规范落地，希望对看到的同学有帮助，本篇到此结束，感谢观看。