Harness工程：赋能AI交付完整项目的实战指南

Q: Harness工程和提示词工程有什么区别？

提示词工程专注于编写正确的指令让AI理解单个任务。Harness工程是围绕AI开发的更广泛系统——包括上下文架构（AGENTS.md、项目文档）、任务编排（计划模式、子代理）、工具配置、自动化测试管道和架构护栏。可以理解为：提示词工程告诉AI做什么；Harness工程确保AI可靠地交付完整结果。

Q: 小项目需要Harness工程吗？

需要，但要适度调整。对于周末项目，一个简单的AGENTS.md（包含技术栈和编码标准）加上提交前运行npm test就足够了。完整的Harness（自定义检查器、预提交钩子、子代理编排）适用于构建生产系统、团队协作或让AI长时间无人值守工作的情况。从最小化开始，随项目增长逐步添加组件。

Q: Harness工程如何与Codex CLI等AI编程代理配合使用？

Harness工程和AI编程代理是互补的。像Codex CLI这样的代理提供执行引擎——读取代码、编写文件、运行命令。Harness工程提供其周围的结构：AGENTS.md告诉代理你的项目约定，计划模式强制它在编码前思考，自动化测试验证其输出，架构护栏防止它引入技术债务。它们共同构成了完整的AI驱动开发管道——代理处理实现，Harness确保质量和一致性。

在AI编程领域，很多开发者都遇到过令人沮丧的场景：让AI微调一个页面的样式，结果它把整个布局都改了；明确说单个文件不要超过200行代码，几轮交互后AI却忘记了这个约束，生成了一个1000行的庞然大物；让AI修复一个bug，结果它引入了三个新bug，代码库一片混乱。虽然提示词工程和上下文工程可以解决前两个问题，但第三个问题需要一种更系统的方法——Harness工程。

什么是Harness工程？

把AI模型想象成一匹马。正如马需要缰绳、路线和围栏才能发挥最佳表现一样，AI模型需要结构化的环境和工作流才能可靠地交付端到端项目成果。这个包含规则文件、工具配置、任务编排和测试流程的环境，就是我们所说的Harness。

Harness工程之所以受到关注，是因为有令人信服的证据。例如，LangChain的实验表明，优化AI模型周围的Harness（保持模型本身不变）将编码准确率排名从30名开外提升到了前5名。OpenAI也展示了其威力——一个小团队利用Harness引导AI生成了数百万行代码，产出的产品现已内部使用。业界如今认识到，AI编程的瓶颈不是模型的智能，而是周围Harness的质量。

AI工程的演进与Harness的角色

Harness工程不是突然的创新，它建立在AI工程的前两个阶段之上：

提示词工程（Prompt Engineering）：专注于编写提示词让AI理解指令。技术包括角色设定、少样本示例和思维链提示。
上下文工程（Context Engineering）：通过在正确的时间为AI提供正确的信息来增强提示词工程。包括规则文件（如AGENTS.md）、检索增强生成（RAG）获取外部数据，以及跨对话记忆机制。
Harness工程：更进一步，专注于AI如何可靠地完成完整任务。涵盖工具配置、任务分解、自我验证和架构防护。关系是分层的：提示词 < 上下文 < Harness。

提示词工程示例：

你是一位资深React开发者。请按照Airbnb风格指南，使用hooks重构以下组件。

上下文工程示例（AGENTS.md片段）：

# 项目：视频下载器
- 技术栈：Python, React, FastAPI
- 代码风格：Python用PEP8，React用Airbnb
- 文档：前端规范见docs/frontend.md，安全指南见docs/security.md

Harness的五大核心组件

要构建有效的Harness，重点关注这五个组件：

1. 上下文架构：定义项目规则和背景

正如任何项目都从需求和规范开始，AI项目需要AGENTS.md文件来概述项目的技术栈、代码标准和禁止事项。由于AI的上下文容量有限，将AGENTS.md视为索引，把详细文档放在docs/文件夹中并在AGENTS.md中引用。

project/
├── AGENTS.md
└── docs/
    ├── frontend.md
    ├── security.md
    └── architecture.md

2. 执行能力：为AI配备工具

AI模型默认只能输出文本。要启用实际操作，需要为其配备工具：

终端访问：让AI执行命令（如mkdir、git commit）。
文件系统访问：允许AI读写文件。
浏览器控制：通过Puppeteer等工具让AI测试Web界面。
MCP（多能力提供者）：扩展功能，如数据库操作或网页抓取。

{
  "tools": [
    {
      "name": "Terminal",
      "description": "执行shell命令",
      "parameters": { "command": "ls -la" }
    },
    {
      "name": "Browser",
      "description": "与网页交互",
      "parameters": { "url": "https://example.com", "action": "click", "selector": "#download-btn" }
    }
  ]
}

3. 任务编排：分解和管理工作

AI在大型模糊任务上表现不佳。将其分解为小型可验证单元：

计划模式：让AI在编码前起草项目计划。
子代理：并行处理独立子任务（如前端和后端开发）。
文档检查点：每完成一个功能，让AI写总结文档并提交到Git，作为项目的"存档点"。

担任技术项目经理。为使用React和Python构建视频下载器制定分步计划。包括里程碑和交付物。

4. 反馈机制：让AI验证自己的工作

不能信任AI自我声明任务完成。实施验证：

代码检查：使用pylint（Python）或eslint（JavaScript）检查代码风格。
自动化测试：运行单元/集成测试。
浏览器测试：让AI通过无头浏览器与应用交互。

pylint src/ --disable=C0114,C0115

def test_download_function():
    result = download_video("https://example.com/video")
    assert result.status == "success"

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('http://localhost:3000');
  await page.type('#video-url', 'https://example.com/video');
  await page.click('#download-btn');
  await page.waitForSelector('.success-message');
  await browser.close();
})();

5. 架构护栏：防止技术债务

AI可能会复制不良编码模式。强制执行架构规则：

自定义检查器：编写检查器检测反模式（如UI层直接访问数据库）。
预提交钩子：使用Husky等工具在提交前运行检查器。
定期代码扫描：让AI定期扫描代码库的架构违规并自动生成修复PR。

module.exports = {
  rules: {
    'no-direct-db-access': (context) => ({
      MemberExpression(node) {
        if (node.object.name === 'DB' && node.property.name === 'query') {
          context.report({ node, message: '不允许直接访问数据库，请使用服务层。' });
        }
      }
    })
  }
};

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npm run lint

实战：用Harness构建视频下载器

让我们将这些概念应用到"视频下载器和摘要器"项目中：

第1步：上下文架构——定义项目规则

# 视频下载器项目
- 技术栈：Python (FastAPI), React, yt-dlp
- 代码标准：PEP8, Airbnb React
- 文档：前端docs/frontend.md，API docs/api.md
- 禁止：控制器直接调用数据库；React组件内联样式。

第2步：执行能力——配置工具

在AI环境（如Cursor）中设置工具访问：启用终端访问以运行yt-dlp命令，配置网页抓取工具获取视频元数据。

第3步：任务编排——计划与执行

使用计划模式让AI制定项目大纲，拆分为子任务（前端UI、后端API、视频处理），在每个检查点用Git提交文档。

第4步：反馈机制——测试与验证

用pylint backend/和eslint frontend/检查代码，用pytest和npm test运行自动化测试，用Puppeteer进行浏览器测试。

第5步：架构护栏——强制标准

用Husky添加预提交钩子运行检查器，编写自定义检查器强制执行架构边界。

Harness入门指南

对初学者而言，按以下实践流程操作：

编写AGENTS.md：明确定义项目规则。
先计划后编码：使用计划模式让AI确认方案。
配备工具：为网页抓取、数据库访问等配置MCP和技能。
全面验证：让AI运行测试和自我检查。
文档与提交：用文档和Git提交保存进度。

如果你是项目工程的新手，可以利用Spec Kit（规范驱动开发）或Superpowers（内置TDD和代码审查等工作流）等工具。

常见问题

Harness工程和提示词工程有什么区别？

提示词工程专注于编写正确的指令让AI理解单个任务。Harness工程是围绕AI开发的更广泛系统——包括上下文架构（AGENTS.md、项目文档）、任务编排（计划模式、子代理）、工具配置、自动化测试管道和架构护栏。可以理解为：提示词工程告诉AI做什么；Harness工程确保AI可靠地交付完整结果。

小项目需要Harness工程吗？

需要，但要适度调整。对于周末项目，一个简单的AGENTS.md（包含技术栈和编码标准）加上提交前运行npm test就足够了。完整的Harness（自定义检查器、预提交钩子、子代理编排）适用于构建生产系统、团队协作或让AI长时间无人值守工作的情况。从最小化开始，随项目增长逐步添加组件。

Harness工程如何与Codex CLI等AI编程代理配合使用？