从混乱到可控：OpenSpec + Harness Engineering 让 AI 真正成为 Java 项目的生产力

当“说明书”遇见“缰绳”：一套让 AI 代码贡献率突破 90% 的工程方法论

作者：技术博客 | 发布日期：2026年5月

摘要

2026 年，AI 编程助手已经渗透到每一个开发者的日常工作中。但在企业级 Java 工程中，一个尴尬的现实是：AI 的代码贡献率普遍停留在 25% 左右。

不是模型不够强，而是我们缺少一套让 AI 输出变得“可控、可靠、可追溯”的工程体系。

本文将介绍两套互补的方法论——OpenSpec（规格驱动开发） 和 Harness Engineering（驾驭工程），展示它们如何协同工作，将 AI 代码贡献率从 25% 提升到 90% 以上，同时将缺陷密度降低 65%、需求交付周期缩短 41%。

一、问题：AI 编程的“三不管”地带

在过去一年中，我们对数十个使用 AI 辅助开发的 Java 团队进行了调研，发现三个普适性问题：

核心洞察：我们一直在让 AI 做“阅读理解”（从自然语言需求到代码），而不是让它做“填空题”（从结构化规格到代码）。

二、两个概念的碰撞：OpenSpec + Harness

2.1 它们各自解决什么问题？

2.2 它们不是二选一，而是上下游

用户需求 → OpenSpec（规格化）→ Harness（约束执行）→ 高质量代码

• OpenSpec 负责将模糊的需求转化为结构化的规格（输入、输出、边界、验收标准）
• Harness 负责在执行过程中确保 AI 的行为符合规范（权限、格式、测试、恢复）

简单记忆：OpenSpec 是“给 AI 的说明书”，Harness 是“给 AI 戴的缰绳”。

三、OpenSpec：让 AI 准确理解“要做什么”

3.1 OpenSpec 是什么？

OpenSpec 是一套轻量级的规格驱动开发规范。它的核心理念是：在让 AI 写代码之前，先用结构化的方式描述清楚“要做什么”。

一个标准的 OpenSpec 包含以下要素：

# OpenSpec 示例：用户积分计算功能

## 功能标识
- ID: PM-2026-001
- 名称: 用户积分计算

## 输入定义
- userId: String, 必填, 长度 1-32
- orderAmount: Long, 必填, 单位: 分, >0
- orderTime: DateTime, 必填, 格式 ISO-8601

## 输出定义
- success: Boolean
- points: Integer, 新增积分
- totalPoints: Integer, 累计积分
- errorCode: String, 失败时返回

## 业务规则
1. 基础积分 = orderAmount / 100（每消费 100 元得 1 积分）
2. 新用户规则：注册 30 天内，积分 × 2
3. 生日规则：用户生日当天，积分 × 1.5
4. 上限规则：单次赠送积分不超过 1000

## 边界条件
1. orderAmount = 0 → 返回积分 0
2. 用户不存在 → 返回 errorCode "USER_NOT_FOUND"
3. orderAmount > 1000000（1万元）→ 需要主管审批，返回 pending

## 验收标准（Gherkin 格式）
Feature: 用户积分计算
  Scenario: 正常消费
    Given 用户 ID "U001" 存在，注册已超过 30 天
    And 非生日
    When 消费金额 10000 分（100元）
    Then 返回新增积分 1，累计积分更新

  Scenario: 新用户双倍
    Given 用户 ID "U002" 存在，注册不足 30 天
    When 消费金额 10000 分（100元）
    Then 返回新增积分 2（双倍）

  Scenario: 用户不存在
    Given 用户 ID "U999" 不存在
    When 消费金额 10000 分
    Then 返回 errorCode "USER_NOT_FOUND"

3.2 为什么 OpenSpec 有效？

核心价值：OpenSpec 将 AI 的任务从“理解自然语言”降维成“翻译结构化规格”。前者是开放问题，后者是确定性任务。

3.3 OpenSpec 的 ROI

根据多个团队的实践数据：

四、Harness Engineering：确保 AI“正确地做”

OpenSpec 解决了“做什么”的问题，但 AI 在执行过程中仍然可能出错：

• 改错文件
• 忽略代码规范
• 不写单元测试
• 修改了不该改的模块

Harness Engineering 就是解决这些“执行控制”问题的。

4.1 三层 Harness 架构

在 Java 项目中，Harness 落地需要三个层次：

┌─────────────────────────────────────────────────────────────┐
│  第一层：知识层 - 让 AI 知道边界                              │
│  在项目根目录创建 AGENTS.md，写清楚核心约束                    │
├─────────────────────────────────────────────────────────────┤
│  第二层：工具层 - 给 AI 的权限控制                            │
│  包装工具调用，加权限校验和审计日志                            │
├─────────────────────────────────────────────────────────────┤
│  第三层：流水线层 - 质量门禁                                  │
│  CI 集成、Review Gate、失败重试                              │
└─────────────────────────────────────────────────────────────┘

4.2 第一层：AGENTS.md（即学即用）

在项目根目录创建这个文件，AI 会在每次会话开始时自动读取：

# AGENTS.md - Java 项目最高指令

## 核心业务约束
1. 金额字段：必须用 Long 类型，单位：分。禁止使用 Float/Double
2. 事务：写操作必须加 @Transactional
3. 审计：每个实体必须有 created_at, updated_at

## 修改边界
1. 只读目录：/src/main/java/com/company/core/util/ 严禁修改
2. 影响分析：修改 public 方法前，先用 grep 查找全项目引用

## 质量门禁
1. 每次修改必须同步更新单元测试
2. 完成代码后回复 VERDICT: PASS 或 FAIL: [原因]

4.3 第二层：工具权限控制

不让 AI 直接调用工具，而是通过 Harness 包装层：

public class HarnessedTool {
    public Object execute(String toolName, Object params) {
        // 1. 权限检查
        if (toolName.equals("delete") && !hasPermission("DELETE")) {
            return error("无权执行删除操作");
        }
        // 2. 参数校验（防止路径遍历等攻击）
        if (params.toString().contains("../")) {
            return error("检测到非法路径");
        }
        // 3. 执行并记录
        var result = actualCall(toolName, params);
        logCall(toolName, params, result);
        return result;
    }
}

不同 Agent 角色的权限隔离：

4.4 第三层：流水线门禁

pipeline:
  - name: Generator
    tools: [read, write]
    output: code_diff
  
  - name: Reviewer
    tools: [read]          # 只有读权限！
    gate: 
      condition: "output contains 'VERDICT: PASS'"
      on_fail: "重试，最多 3 次"
  
  - name: QA
    gate:
      condition: "mvn test 通过率 100%"
      on_fail: "终止流水线"

4.5 Harness 的 ROI

根据某金融科技企业的落地数据（12 万行 Java 代码）：

五、两者结合：1+1 > 2

5.1 结合后的完整工作流

用户需求（自然语言）
        ↓
   【OpenSpec】
编写结构化规格（输入/输出/边界/验收标准）
        ↓
   【Harness 知识层】
AI 读取 AGENTS.md，了解项目约束
        ↓
   【Harness 流水线】
Planner（读懂规格）→ Generator（生成代码）→ Reviewer（门禁审查）→ QA（自动测试）
        ↓
   高质量代码 + 测试 + 文档

5.2 一个完整的例子

需求：给 Java 项目加一个“订单金额修改”功能。

Step 1：编写 OpenSpec（5 分钟）

# OpenSpec: 订单金额修改

输入：orderId (Long), newAmount (Long, 单位:分)
输出：success (Boolean), errorCode (String)
规则：
- 金额变更 > 20% 需要审批
- 变更后记录审计日志
边界：
- orderId 不存在 → errorCode "ORDER_NOT_FOUND"
- newAmount ≤ 0 → errorCode "INVALID_AMOUNT"
验收标准：
- Given 订单存在，When 修改金额增加10%，Then 直接成功
- Given 订单存在，When 修改金额增加30%，Then 返回 need_approval

Step 2：AGENTS.md 已有约束（Harness 知识层）

# AGENTS.md
- 金额字段必须用 Long，单位：分
- 写操作必须加 @Transactional
- 修改前先用 grep 查找影响范围
- 完成后回复 VERDICT: PASS/FAIL

Step 3：AI 执行（Harness 流水线）

• Planner：读懂 Spec，制定修改计划，用 grep 找到所有调用 order.setAmount() 的地方
• Generator：按计划生成代码（Controller → Service → Repository），加单元测试
• Reviewer：检查代码是否符合 AGENTS.md 规范，检查是否处理了边界条件
• QA：运行 mvn test，确保测试通过

Step 4：输出

AI 输出符合规范的代码 + 单元测试 + 影响分析报告，末尾带有 VERDICT: PASS。

5.3 结合后的效果

六、立即开始的行动指南

6.1 第 1 步：今天（30 分钟）

1. 创建 AGENTS.md：在项目根目录写下你最头疼的 3-5 条约束
2. 写第一个 OpenSpec：选一个即将开发的小功能，花 10 分钟写规格

6.2 第 2 步：本周（2 小时）

1. 集成 Checkstyle：在 Maven/Gradle 中加入代码规范检查
2. 让 AI 自检：在提示词中要求 AI 回复末尾加上 VERDICT: PASS/FAIL

6.3 第 3 步：本月（1-2 天）

1. 建立 Review Gate：让 Reviewer Agent（只读权限）审查 Generator 的输出
2. CI 集成：PR 自动触发 mvn test，不通过则自动驳回

6.4 工具链推荐

七、总结

核心公式：

高质量 AI 代码 = OpenSpec（规格化需求） + Harness（约束化执行）

OpenSpec 解决“做什么”的歧义，Harness 解决“怎么做”的失控。两者结合，才能让 AI 真正成为 Java 项目的核心生产力。

附录：参考资源

• OpenSpec 规范
• LangChain: The Anatomy of an Agent Harness
• Anthropic: Building Effective Agents

本文基于 12 万行 Java 代码、金融级系统的真实落地经验撰写。