跳至主要內容

Harness Engineering 学习笔记

钝悟2026/7/29大约 8 分钟人工智能人工智能AIHarness

Harness Engineering 学习笔记

Harness Engineering 是 2026 年 AI 编程领域最核心的工程方法论之一，由 HashiCorp 联合创始人 Mitchell Hashimoto 首次提出，并经 OpenAI Codex 团队实践验证。其核心公式为：Agent = Model + Harness——模型负责推理与生成，Harness 是包裹模型的整套工程基础设施。

概念起源

2026 年 2 月，Mitchell Hashimoto 在《My AI Adoption Journey》中将自己长期使用 Coding Agent 的方法命名为"Harness Engineering"。他的核心做法是：每当 Agent 犯一次错误，就花时间把解决方案工程化——可能是补一条仓库规则、新增 Lint 规则、自动化测试或 Git Hook，让同类错误不再依赖人类临时提醒。

几天后，OpenAI 发布 Codex 团队官方复盘：一个小团队从空仓库开始，让 Codex 生成应用代码、测试、CI、文档、可观测性和内部工具；五个月后仓库规模约 100 万行，期间约 1,500 个 PR 被创建并合并。这里真正重要的不是"AI 写了多少行代码"，而是人类工程师把工作重心转向了环境设计、意图描述和反馈回路。

LangChain 给出了一个精炼的表达：Agent = Model + Harness。模型负责推理和生成；模型之外的系统提示词、工具描述、文件系统、沙箱、状态管理、子 Agent 编排、上下文压缩、Lint、测试和恢复逻辑，都属于 Harness。

核心定义

Harness Engineering（驾驭工程 / 缰绳工程） 是一套专为 AI 编程 Agent 设计的系统化工程方法论。其核心理念：AI 编程不是单纯的"生成代码"，而是构建一套包含指令、约束、反馈、记忆与编排的控制系统，让 AI 在明确的边界内自主工作。

与 Vibe Coding 的本质区别：

维度Vibe Coding（氛围编码）Harness Engineering（驾驭工程）
控制方式人持续适配 AI，优化单次对话提示词构建系统约束 AI，将规范固化为可执行机制
关注层面单次对话如何沟通长期、多人、大型项目中如何持续可控使用 AI
人类角色驾驶员——全程操控交通系统设计师——搭建规则和反馈回路
适用场景个人探索、快速原型生产级项目、团队协作、长期维护

五大组件

Harness 的五大组件构成完整的控制闭环：

组件核心作用关键实践/载体
指令定义 AI 的身份、目标与行为边界CLAUDE.md / AGENTS.md、System Prompt、SDD 设计文档
约束设定不可逾越的红线与质量标准静态分析规则、Git Hooks、单元测试断言、类型系统
反馈提供执行结果的验证信号，形成闭环编译器报错、测试覆盖率、Lint 结果、人工 Code Review
记忆维护上下文一致性，避免"金鱼记忆"项目级记忆文件、向量数据库、Git Commit 历史、决策日志
编排拆解复杂任务，调度子 Agent 或工具链Agentic Loop、SubAgents、MCP 协议、CI/CD 流水线

指令层（Instructions）

指令是 Agent 的"宪法"，定义其身份、目标和行为边界。核心载体是项目根目录的指令文件（如 CLAUDE.md、AGENTS.md），最佳实践是作为信息索引而非海量文本堆砌——仅指向其他详细文档的路径，避免一次性灌入冗余信息导致模型混淆。

约束层（Constraints）

约束是 Agent 的"红线"，必须用代码和工具链进行硬性约束，而非依赖自然语言说服。关键手段：

  • 静态分析：ESLint / Ruff / Checkstyle 等工具，将编码规范自动化执行。
  • 类型系统：TypeScript strict 模式、Python Type Hints，在编译期捕获类型错误。
  • Git Hooks：Pre-commit 钩子强制执行格式化（Prettier）、Lint 检查和测试通过。
  • CI/CD 门禁：PR 合并前必须通过自动化测试、覆盖率门槛和静态扫描。

反馈层（Feedback）

反馈是 Harness 的"神经系统"。AI 不怕报错，怕的是没有反馈。将错误信息结构化地回传给 AI，是最高效的调试手段：

  • 编译器/解释器报错 → 直接回传给 Agent 重试。
  • 测试失败信息 → 结构化输出（文件名、行号、断言差异）供 Agent 定位。
  • Lint 违规 → 自动修复或回传给 Agent 修正。
  • 人工 Review 意见 → 沉淀为规则，下次同类问题自动检测。

记忆层（Memory）

记忆解决 Agent 的"金鱼记忆"问题。核心原则是主动维护一份"当前状态摘要"，而非保留原始聊天记录：

  • 项目级记忆文件：CLAUDE.md / .cursorrules 记录项目约定和决策历史。
  • 向量数据库：长期知识检索，支持语义搜索历史上下文。
  • Git Commit 历史：代码变更的权威来源，Agent 可追溯任意决策的上下文。
  • 决策日志：记录关键技术决策的背景和理由，避免 Agent 在后续任务中重复犯错。

编排层（Orchestration）

编排是 Harness 的"大脑"，负责将复杂任务拆解为可执行的子任务序列：

  • Agentic Loop：Agent 的"感知→规划→执行→反思"循环，是所有框架的核心。
  • SubAgents：角色分离，如生成者与评判者分开（Maker-Checker 模式）。
  • MCP 协议：标准化工具连接，Agent 通过 MCP 调用外部系统。
  • CI/CD 流水线：将 Agent 输出集成到现有的持续集成和部署流程中。

反直觉原则

Harness Engineering 的五条核心原则，与传统软件工程思维有显著差异：

  1. 少即是多：过度详细的指令会限制 AI 的推理能力，保留适当的"模糊地带"反而能激发其规划能力。指令文件应聚焦"是什么"和"为什么"，而非手把手规定"怎么做"。

  2. 约束优于提示：不要试图用自然语言说服 AI 遵守规则。一条 Lint 规则胜过十句"请不要这样做"。必须用代码、测试或工具链进行硬性约束。

  3. 反馈即燃料：AI 不怕报错，怕的是没有反馈。将错误信息结构化地回传给 AI，是最高效的调试手段。每一次报错都是一次学习机会。

  4. 记忆需压缩：不要将所有历史对话塞入上下文。主动维护一份"当前状态摘要"比保留原始聊天记录更有效。上下文窗口是稀缺资源，必须精打细算。

  5. 人类负责架构，AI 负责实现：Harness 的终极目标是让人类专注于 SDD（软件设计文档）和验收标准，将编码与测试执行完全托管。人类的价值在于意图描述和质量判断。

落地实践

OpenAI Codex 团队实践

OpenAI Codex 团队的实验数据是 Harness Engineering 最具说服力的案例：

  • 规模：小团队从空仓库开始，5 个月后约 100 万行代码。
  • 产出：约 1,500 个 PR 被创建并合并。
  • 关键洞察：人类工程师的工作重心从"写代码"转向"环境设计、意图描述和反馈回路"。
  • Harness 构成：系统提示词 + 工具描述 + 沙箱 + 测试套件 + CI 流水线 + 代码审查规则。

最小可用 Harness 搭建步骤

  1. 建立项目指令文件：在项目根目录创建 CLAUDE.md 或 AGENTS.md，定义项目约定、技术栈和行为边界。
  2. 配置自动化反馈：设置 ESLint / Ruff + Pre-commit Hook + CI 测试门禁。
  3. 定义 SDD 文档：为每个任务编写 Spec 文档，明确输入、输出、验收标准。
  4. 实现记忆持久化：将关键决策和状态摘要写入项目记忆文件。
  5. 设计人工熔断机制：定义哪些操作需要人工审批（如删除文件、修改权限、发布部署）。

落地检查清单

常见误区与踩坑

误区问题正确做法
指令文件写成百科全书上下文窗口被占满，Agent 推理能力下降指令文件仅做索引，指向详细文档
用自然语言替代硬约束"请不要使用 any 类型" 无法被可靠执行用 TypeScript strict 模式 + ESLint 规则强制
忽略反馈回路Agent 犯错后无信号回传，同类错误反复出现每次 Agent 犯错，花时间工程化解决方案
上下文不压缩对话越来越长，Agent 响应越来越差定期总结状态，清理历史对话
没有熔断机制Agent 无人值守时执行危险操作关键操作（删除、部署、权限变更）必须人工确认

总结

Harness Engineering 的核心价值在于将 AI 编程从"即兴对话"升级为"工程化控制"。它不是让 AI 更聪明，而是让围绕 AI 的系统更可靠。对于从传统软件工程转向 AI 编程的团队来说，Harness 提供了一套可落地的方法论框架——人类负责意图和判断，AI 负责执行和迭代，Harness 负责确保两者之间的协作可控、可追溯、可持续。

参考资料

Copyright © 2026 钝悟