从提示词工程到 Harness Engineering：打造坚实可靠的 AI 开发系统

过去一段时间里，围绕 AI 编程的讨论，大多集中在模型能力本身：模型能不能理解需求、能不能写出可运行代码、能不能完成复杂重构。

这些问题当然重要。但在真实研发场景中，另一个问题正在变得更关键：

当模型已经足够会写代码之后，我们如何让它稳定地在工程系统中工作？

这篇文章讨论的 Harness Engineering，正是围绕这个问题展开。它并不是某个具体工具，也不是某个固定模板，而是一种将 AI 编码能力纳入工程流程的思路：通过指令、状态、范围、验证和会话生命周期，把模型的输出变得更可控、更可验证，也更容易被团队持续使用。

从“会写代码”到“可靠交付”：为什么需要 Harness

近一年来，大模型发展迅猛，模型能力持续提升，已经能够完成日常开发中的相当一部分编码工作。无论是生成业务代码、补充单元测试、解释遗留逻辑，还是进行简单重构，AI 编码助手都已经进入了真实研发流程。

但这是否意味着开发团队的整体效率，也会随着模型能力同步快速提升？

答案未必。

尽管模型能力很强，但在实际开发中，我们仍然会遇到很多问题：

• 模型可以每天产出大量代码，但其中相当一部分并不能直接上线；

• 有些代码无法通过测试；

• 有些实现偏离了需求；

• 有些改动引入了新的维护成本；

• 开发者不得不反复沟通、纠偏、审查和返工。

最终结果是：看似节省了编码时间，实际却把成本转移到了验证、清理和维护阶段。

随着高性能模型调用成本上升，以及 Agent 模式下 token 消耗快速增加，如何更有效地利用模型，让模型稳定产出可验证、可维护、可上线的结果，正在成为一个越来越重要的工程问题。

换句话说，今天的问题已经不只是：

模型会不会写代码？

而是：

如何让模型在真实工程环境中，可靠地完成任务？

这正是 Harness 工程化试图解决的问题。

Harness 是什么：把模型放进可验证的工程轨道

Harness 是一种 AI 工程化思想。简单来说：

模型决定要写什么代码，Harness 约束它在什么时候、在哪里、以什么方式写代码。

换句话说：

• Harness 不会让模型本身变得更聪明；

• Harness 会让模型的工作过程更可控；

• Harness 会让模型的输出更可靠。

它的基本模式大致如下：

可以看到，Harness 不同于简单的提示词工程。

提示词工程通常关注“如何把话说清楚”，而 Harness 工程化关注的是：

如何把模型放进一个可执行、可验证、可持续演进的软件开发流程中。

在一个完整的软件开发流程中，每个关键步骤都应该有对应机制来支撑模型工作，例如：

• 让模型知道应该先读什么；

• 当前任务做到哪里；

• 下一步做什么；

• 什么算完成；

• 如何验证；

• 会话结束时如何交接。

这些机制不应该只存在于一次性的对话里，而应该落地为仓库中的文件、脚本、测试和流程。这样才能约束模型动作，降低跑偏概率，并让每一次 Agent 会话都能在同一个工程上下文中继续推进。

我们真正关心的问题不是：

模型能不能写代码？

它们当然能。

真正的问题是：

模型能不能在真实代码仓库中，跨多个会话、无需持续人工监督地，可靠完成真实工程任务？

Harness 的价值不在于替代模型能力，而在于把模型能力约束到一个稳定的工程轨道中。

没有 Harness 时，Agent 像一个聪明但健忘、容易越界、缺少自检习惯的新同事。

有了 Harness 后，Agent 仍然可能犯错，但它的错误更容易被发现和定位，工作过程也更容易被复现和接续。

引入 Harness 后，开发流程会发生什么变化

在没有 Harness 的情况下，很多 AI 编码会话看起来很高效，但实际上很难延续。一次会话结束后，智能体可能忘记之前的背景；下一次开始时，又需要重新解释需求、重新判断状态，甚至重复已经做过的工作。

引入 Harness 后，变化不在于模型突然变得完美，而在于开发流程开始有了“轨道”。

没有 Harness

1. 会话 1：智能体写代码 → 破坏测试 → 说“完成了” → 你手动修复

2. 会话 2：智能体从零开始 → 不记得之前的事 → 重复工作或做完全不同的内容 → 你再次修复

3. 结果：你花在清理残局上的时间比自己做还多

有 Harness

1. 会话 1：智能体读取指令 → 运行init.sh→ 一次只做一个功能 → 验证通过后才声明完成 → 更新进度日志 → 提交干净状态

2. 会话 2：智能体读取进度日志 → 准确接上上次位置 → 继续未完成功能 → 你负责审查，而不是救火

3. 结果：智能体完成工作，你验证结果

这也是 Harness 的核心价值：它不是替代开发者做判断，而是让开发者从“不断救火”转向“审查和决策”。智能体负责在约束内推进任务，人负责设定方向、审查结果和维护工程质量。

一个典型 Harness 系统由哪些部分组成

如果把 Harness 拆开看，它通常可以分成五个子系统：指令、状态、验证、范围和会话生命周期。

这五个部分不一定要一次性全部搭建完成，但它们代表了让 AI 编码进入工程化流程时最常见的几个控制点。

Instructions：让智能体知道该如何工作

Instructions 用来告诉智能体：

• 要做什么；

• 按什么顺序做；

• 开始之前必须阅读哪些内容；

• 遇到不确定情况时应该如何处理。

它不应该是一个巨大的单一文件，而应该是一套渐进式披露结构。也就是说，入口文件保持简短清晰，只说明 Agent 必须遵守的核心规则，并链接到更细分的文档。Agent 根据当前任务需要，再继续读取对应内容。

例如：

• AGENTS.md：通用 Agent 操作手册；

• AI_GUIDE.md：针对具体模型、平台或工具的补充说明；

• docs/architecture.md：架构说明；

• docs/testing.md：测试策略；

• feature_list.json：功能清单和状态。

State：让工作可以跨会话延续

State 用来跟踪：

• 已经完成了什么；

• 当前正在做什么；

• 下一步准备做什么；

• 上一次会话留下了哪些问题。

状态应该持久化到磁盘，而不是只保存在对话上下文里。这样即使上下文窗口耗尽，或者下一次开启新会话，Agent 也可以通过读取状态文件，准确接上之前的工作。

常见状态文件包括：

• progress.md

• agent-progress.md

• feature_list.json

• DECISIONS.md

• git commit history

Verification：把“我完成了”变成“验证通过了”

Verification 的原则是：

只有通过测试和检查，才算真正完成。

Agent 不能仅仅因为“我已经实现了”就宣布任务完成。它需要提供可运行的证据，例如：

• 单元测试通过；

• 类型检查通过；

• lint 通过；

• 冒烟测试通过；

• 关键路径手动验证完成；

• E2E pipeline 通过。

这一步的作用，是把 Agent 的“主观完成”转换成工程上的“客观完成”。

Scope：限制一次只做一个明确任务

Scope 用来限制 Agent 一次只完成一个明确任务。

它要求：

• 一次只做一个功能；

• 不顺手重构无关模块；

• 不同时半完成多个功能；

• 不通过修改 feature list 来掩盖未完成工作；

• 每个任务都要有明确的 Definition of Done。

范围控制非常重要。很多 Agent 任务失败，并不是因为模型不会写代码，而是因为它在执行过程中不断扩展范围，最后导致改动过大、验证困难、问题难以定位。

Session Lifecycle：让每次会话都有开始和收尾

Session Lifecycle 约束一次 Agent 会话从开始到结束的完整过程。

典型流程包括：

• 会话开始时运行init.sh；

• 初始化依赖、检查环境、运行基础验证；

• 开始前读取说明文档和进度文件；

• 工作过程中持续更新进度；

• 结束前运行测试和检查；

• 清理临时文件和无效改动；

• 写下 handoff note；

• 只有在状态安全可恢复时才提交代码。

这保证了每一次会话结束后，仓库都能保持在一个干净、可继续工作的状态。

如何在真实项目中落地 Harness

理解 Harness 思想之后，并不需要一开始就搭建一套复杂平台，也不需要马上把它深度接入公司的研发系统。

更现实的做法是：先从一个真实仓库开始，给 AI 编码智能体增加一组结构化文件，用来定义：

• 它应该如何工作；

• 当前项目已经完成了什么；

• 接下来应该做什么；

• 如何验证工作结果；

• 会话结束时如何交接。

这些文件放在代码仓库中，让每一次 Agent 会话都能从同一个工程状态开始。无论你使用的是商业模型、开源代码模型，还是企业内部封装的研发 Agent，这套结构都可以复用。

一个最小可用结构如下：

项目根目录 ├ agents.md：智能体的通用操作手册 ├ guide.md：可选：针对具体模型/工具的补充说明 ├ init.sh：安装依赖、检查环境、运行验证 ├ feature_list.json：功能清单与完成状态 ├ progress.md：跨会话进度记录 ├ design.md：关键技术决策日志 ├ limitations.md：技术限制与约束记录 ├ bugs.md：历史问题和避坑记录 └ src/：业务代码

这个结构并不复杂，但它能把很多原本散落在对话里的信息，沉淀为项目的一部分。这样做的好处是：智能体不再每次都从零开始理解项目，而是可以沿着已有状态继续推进。

agents.md

用来说明：

• 项目是什么；

• 开始任务前必须读哪些文件；

• 修改代码前要遵守哪些规则；

• 一次只能处理什么范围；

• 完成前必须运行哪些检查；

• 不能做哪些危险操作。

guide.md

用于记录针对具体模型、平台或工具的补充说明。

例如：

• 某个工具如何启动；

• 某类任务应该使用什么命令；

• 某些平台环境有什么限制；

• 某些模型在当前项目中容易犯什么错误。

init.sh

用于安装或检查依赖、确认环境、运行基础验证。

它应该尽量明确说明：在不同任务场景下，智能体需要完成哪些准备工作，才能开始开发。

例如：

• 修复 bug 前，是否需要构造最小复现用例；

• 验证页面效果前，需要设置哪些环境变量；

• 本地服务应该使用哪个端口；

• 是否需要启动 mock server；

• 是否需要准备测试数据。

feature_list.json

这是任务和功能状态的来源。

它可以记录：

• 当前有哪些功能；

• 每个功能的状态；

• 每个功能的验收标准；

• 哪些功能正在进行；

• 哪些功能已经完成；

• 哪些功能被阻塞。

功能拆解不一定必须是平铺直叙的，也可以采用树状结构。对于复杂功能，可以继续拆解为多个子功能。

progress.md

用于记录：

• 本次会话做了什么；

• 修改了哪些文件；

• 运行了哪些验证；

• 还剩什么问题；

• 下一次会话应该从哪里继续。

design.md

用于记录关键技术决策和工程约束，例如：

• 优先使用本项目工具库中已有的方法，不要重复造轮子；

• 变量命名风格必须和本项目一致；

• 重复逻辑必须抽取公共方法；

• 某个模块为什么采用当前实现方式；

• 哪些方案已经被否决，为什么否决。

limitations.md

用于记录功能开发和迭代过程中遇到的技术限制，提示智能体避免进入不可行路径。

bugs.md

用于记录曾经踩过的坑和历史问题，避免智能体在接入新功能时再次引入重复 bug。

Harness 如何在实践中演进

前面介绍的是 Harness 的基本结构。但在真实项目中，Harness 不是靠一次性设计出来的，而是在一次次任务、失败、纠偏和复盘中长出来的。

下面是几个在实践中比较重要的经验。

经验一：Agent 规则应该来自真实经验，而不是一次性生成

所有操作文件，应该来自真实项目中的经验总结。

不能简单地给 AI 一个指令，然后等待它一次性生成一份复杂的 Agent 文件，就认为 Harness 搭建完成了。这样的文件往往看起来很完整，但很可能无法覆盖真实工作中的关键风险。

更合理的做法是：

1. 先让 Agent 参与真实任务；

2. 观察它在哪里容易跑偏；

3. 记录哪些规则能显著减少错误；

4. 把这些经验逐步沉淀进AGENTS.md；

5. 定期删除已经过时或无效的规则。

AI 可以帮助你编写和整理这些文件，但文件背后的判断应该来自现实世界的经验。

换句话说，不应该完全让 AI 接管 skill 或 Harness 规则的制定。智能体很聪明，但它并不天然理解你的业务环境、团队习惯、历史包袱和真实用户需求。人需要把这些经验沉淀下来，再让 AI 在这些约束下工作。

经验二：先由人搭建清晰项目雏形，再逐步引入 Harness

一个常见误区是：以为引入 Harness，就是在项目开始时先主观设计出一批 Agent 文件，再指望它们自然形成一个完美闭环。

实际上，Harness 的作用是辅助 AI 进入稳定、可验证的开发流程，而不是在一开始就预设出一个完美系统。尤其在复杂项目中，不建议直接把系统从零到一完全交给 AI 自由演进。

更稳妥的方式是：

先由人设计并搭建出一个架构清晰、职责明确、边界直观的系统。当系统本身经得起推敲之后，再让 AI 在这个架构内逐步扩展功能。

原因很简单：仅靠一句话让 AI 生成一个复杂应用，往往很难把控后续演进方向。

即使是人类工程师，也不可能在一开始就完全想清楚一个系统最终应该长什么样。很多真实需求，都是在投入使用后，通过试用反馈逐渐浮现，再逐步融入系统架构中。

如果复杂系统从一开始就完全由 AI 负责，早期可能看起来还比较精简，也容易运行。但随着迭代次数增加，系统架构很可能逐渐变得松散：

• 边界开始模糊；

• 重复逻辑增加；

• 临时方案变成长期方案；

• 最终维护成本越来越高。

如果先由人搭建整体架构，并建立良好的编码习惯，后续 AI 介入时会接收到这些范式，从而更容易模仿出好的代码。

但即便如此，在 AI 迭代过程中仍然会出现跑偏。例如：

• 引入不必要的抽象；

• 复制已有逻辑而不是复用；

• 为了通过测试写出脆弱实现；

• 顺手重构无关代码；

• 偏离原有架构边界。

这时人应该及时介入，调整方向。坏的模式如果不及时清理，会逐渐扩散并掩盖原本好的设计，最终让系统在某一天变得难以维护。

经验三：不要指望一个 Agent 承担所有职责

在 Harness 系统中，可以考虑引入多个智能体，或者让多个模型/Agent 协同工作，并承担不同职责。

不要把所有要求都塞进同一个提示词里，让一个 Agent 同时负责：

• 生成方案；

• 编写代码；

• 检查质量；

• 判断是否完成；

• 评价自己的成果。

更好的方式是拆分职责：

• 生成器 Agent：负责方案生成、代码实现、功能构建；

• 评估器 Agent：负责测试、审查、评分和反馈。

二者可以形成这样的协作关系：

原因在于，当要求智能体评估自己产出的工作时，它往往会自信地称赞这些成果。即使在人类观察者看来，其质量明显普通，Agent 也容易给出偏正面的评价。

这个问题在设计类、产品类、交互类任务中尤其明显。因为这类任务不像单元测试那样有清晰的二元判断。一个布局是精致还是普通，一个页面是否有设计感，本质上都包含主观判断。而 Agent 在给自己的作品评分时，通常会稳定偏向正面评价。

将“执行工作的智能体”和“评判工作的智能体”分离，是解决这一问题的有效杠杆。

当然，单纯分离并不会立刻消除宽松倾向。评估器仍然是 LLM，也可能对 LLM 生成的输出更加宽容。但相比让生成器批判自己的作品，训练或调教一个独立评估器，使其更怀疑、更严格，通常更容易。

一旦外部反馈存在，生成器就有了具体的迭代依据。

例如，在前端页面生成任务中，可以将“页面生成”和“页面评估”分离：生成器 Agent 负责实现页面，评估器 Agent 根据统一标准检查页面质量，并输出可执行的修改建议。随后，生成器再根据这些反馈继续迭代。

评估标准可以包括以下几个维度。

1）设计质量：Design Quality

这个设计是否像一个连贯整体，而不是一堆零散部件的集合？

优秀的设计应该让颜色、字体排版、布局、图像和细节形成统一的情绪和身份感。

2）原创性：Originality

是否能看出定制化决策，而不是模板布局、组件库默认样式和常见 AI 生成套路？

人类设计师应该能够识别出有意为之的创意选择。未经修改的现成组件，或典型 AI 生成痕迹，例如“白色卡片 + 紫色渐变”，在这一项上都应该扣分。

3）工艺：Craft / Technical Execution

这一项关注基础执行质量，包括：

• 字体层级；

• 间距一致性；

• 色彩协调；

• 对比度；

• 响应式表现；

• 细节完成度。

这是能力检查，而不是创造力检查。多数合理实现默认都能在这里表现不错；如果失败，说明基础能力出了问题。

4）功能性：Functionality

这一项独立于美学之外，关注可用性。

• 用户是否能理解界面在做什么？

• 是否能找到主要操作？

• 是否无需猜测就能完成任务？

通过这种方式，生成器不再只是“自我感觉良好”，而是要面对一个相对独立、可重复使用的评估标准。

经验四：持续改进 Harness，不要指望一次性搭建完美系统

Harness 不是一次性工程，而是一套需要持续演进的工作系统。

有一句话很适合用在日常开发里：

“以后再清理”，就是以后也不会清理。

每次使用 AI 后，都应该检查它是否引入了：

• 无效代码；

• 废弃代码；

• 重复逻辑；

• 临时方案；

• 没有使用的抽象；

• 只为通过当前测试而写的脆弱实现。

这些内容应该及时删除或修正，不要等。因为一旦坏模式进入代码库，后续 AI 很可能继续模仿它们。

同样，Harness 和提示词本身也需要持续维护。

提示词工程绝对不是越写越多越好。规则越堆越多，最终会变得臃肿、冲突，甚至连 AI 都难以遵守。

更好的做法是定期简化 Harness。

Harness 中每个组件的存在，通常都源于模型在某个方面还无法稳定独立完成。但随着模型能力演进，这些前提会逐渐过时。

例如，早期模型可能无法自己拆解复杂任务，所以需要外部任务拆分机制。但当模型规划能力变强后，原来的拆分机制可能反而变成负担。它会增加流程步骤，让 Agent 过度依赖外部结构，甚至限制模型自身的规划能力。

Evaluator 也是类似情况。

当任务难度较高、接近模型能力上限时，独立 Evaluator 很有价值，因为它能发现遗漏、检查质量、提供外部反馈。

但如果任务很简单，远在模型能力范围内，Evaluator 可能就是多余环节。

所以，要不要保留某个 Harness 组件，取决于三个因素：

• 任务有多难；

• 模型有多强；

• 这个组件是否仍然带来净收益。

一个推荐做法是：

每月挑选一个 Harness 组件，暂时禁用它，跑一遍基准任务。如果结果没有退化，就永久移除；如果结果退化，则恢复该组件，或换一个更轻量的替代方案。

更深层的原则是：

随着模型能力提升，Harness 中有趣的组合并没有减少，而是在发生位移。

过去必须依赖 Harness 解决的问题，可能会被模型新增能力覆盖。与此同时，模型能力提升也会打开新的使用边界，暴露出过去触及不到的新问题。

因此，Harness 不应该是一套固定不变的模板，而应该是一套持续演进的工程系统。

结语：Harness 的本质，是把 AI 能力变成工程能力

AI 编码真正困难的地方，往往不在于“生成一段代码”，而在于让这段代码进入真实工程系统，并且能够被验证、维护、复用和持续演进。

提示词工程解决的是“如何让模型更好地理解这一次请求”。

上下文工程解决的是“如何让模型看到更合适的信息”。

而 Harness Engineering 进一步关注的是：

如何让模型在一个可控、可验证、可持续演进的工程流程中工作。

它不是某个固定模板，也不是一组越写越长的提示词，而是一套围绕真实项目持续生长的工程机制。

当模型能力越来越强，开发者的角色也会发生变化：我们不再只是逐行编写代码，而是更多地设计约束、维护上下文、定义验证方式，并判断系统演进方向。

从这个角度看，Harness 并不是为了限制 AI，而是为了让 AI 的能力真正进入工程生产。只有当模型的输出能够被流程承接、被测试验证、被状态延续、被团队维护时，AI 编码才不只是一次漂亮的演示，而会成为可靠的软件开发能力。