Harness Engineering 的本质：把工程判断写进上下文

一、一个越来越普遍的困惑：写规范的时间超过了写代码

不少开发者近一两年都有类似体验：引入智能编程工具后，最初惊喜于“一句话生成一个模块”，随后却发现，真正花时间的不是提示词，而是那份放在项目根目录的规范文件——也就是告诉智能体“这个项目该怎么写”的上下文文档。

而且这不是一次性的工作。典型的工作循环是这样的：

1. 智能体生成了代码，但把工具函数放错了目录；
2. 你回到规范文件，补一条“工具函数统一放在 utils 目录”；
3. 再跑一次，目录对了，错误处理方式又不符项目约定；
4. 再补一条规则，再跑，再修……

如此往复几十轮之后，这份文件膨胀到几百行，涵盖架构分层、命名约定、错误处理策略，甚至一份长长的“禁止事项”清单。此时许多开发者的第一反应是：我是不是在浪费时间？是不是在给工具“打工”？

要回答这个问题，需要先理解一个正在成型的工程概念——Harness Engineering。

二、Harness Engineering 是什么

Harness 的原意是“马具、缰绳”。把一匹力气极大但不受控的马，变成能拉车、能耕地的生产力，靠的不是把马关起来，而是给它套上合适的缰绳与挽具。

在智能体开发的语境下，Harness 指的是包裹在大模型外层的整套工程化设施，通常包括：

• 上下文文件：告诉智能体项目背景、架构约定与行为边界的结构化文档；
• 工具与权限边界：允许智能体读写哪些文件、执行哪些命令；
• 自动化钩子：在关键动作前后自动运行的检查、格式化与测试；
• 评审与验证环节：智能体产出之后由人或流程把关的机制。

而 Harness Engineering，就是围绕“如何让一个通用的生成式模型在特定项目里稳定产出合格工程产物”所进行的全部设计、维护与迭代工作。

大模型本身是通用能力的引擎：它见过海量代码，熟悉几乎所有主流语言的语法。但“会语法”和“懂你这个项目”之间隔着巨大鸿沟。Harness 的作用就是填平这道鸿沟——把一个“什么都会一点的通才”，装配成“深谙本项目规矩的专才”。

三、本质一：把隐性工程经验显性化

回头看“写规范比写代码还慢”的现象，它慢的原因其实很简单：你写的不是文字，而是判断力。

一位资深工程师的真正价值，从来不在打字速度，而在大量难以言传的隐性判断：这个函数该放在哪一层、这个命名会不会引起歧义、这个错误该在哪一层被处理、这段逻辑改动会波及谁。在过去，这些判断以三种形态存在：

• 存在脑子里，通过 code review 的只言片语零散输出；
• 存在新人培养的口口相传中，随人员流动而流失；
• 存在各自为政的内部文档里，常年无人更新。

Harness Engineering 做的事情，就是强迫你把这些判断力用智能体可执行的形式写下来。当你写下“repository 层禁止反向依赖 service 层”时，完成的不是一次文档写作，而是一次知识萃取：把“我总觉得这么写不对”，提炼成“为什么不对、什么才算对”。

这个过程当然比写代码慢——萃取永远比表达慢。但它的产出物有着完全不同的复利属性。

四、本质二：用规则闭环换取确定性

如果说本质一回答了“你写的是什么”，本质二回答的则是“为什么必须反复迭代”。

生成式模型的输出天然带有随机性，而工程追求确定性。规范文件的迭代循环——出错、加规则、再跑、再修——表面上像在“救火”，本质上却是一个标准的反馈控制过程：

• 智能体的每次失误，是一次“测量”；
• 你补充的每条规则，是一次“校正”；
• 文档从几十行到几百行的过程，是系统逐步收敛的过程。

理解这一点非常重要，因为它直接改变你对“又出新问题”的心态。新问题不断出现不是失败信号，而是收敛信号。真正的健康度指标是：同类问题的出现频率是否下降、解决一类新问题所需的规则条数是否在减少。如果迭代几十轮后，智能体仍反复在同一类问题上跌倒，那说明问题多半出在规则的写法——太模糊、互相冲突、或根本不可验证——而不是“迭代”这个方法本身。

五、本质三：一次投入，持续复利

第三重本质关乎投入产出结构。

一条写进规范文件的规则，成本只支付一次，却会在之后每一次会话、每一个模块、每一个任务中被反复执行。这是典型的杠杆结构：前期投入大，边际成本趋近于零。

对比传统知识传递路径会更清晰：

• 口头带教：一位资深工程师带熟一个新人，往往以月计；
• 规范沉淀：一次沉淀，团队里每个使用智能体的成员自动继承同一套标准，且随版本演进持续更新。

当 Harness 足够成熟时，它实际上成为团队工程标准的“单一事实来源”：人做事看它，智能体做事也看它，两边标准天然对齐。这在工程管理上的价值，远超“让 AI 少犯错”本身。

六、实践指南：如何把 Harness Engineering 做好

理念清楚之后，落地需要方法。以下六条实践，是大量团队踩坑后的共识。

1. 分层组织，别写成一锅粥

几百行的规范文件难维护，往往因为架构、命名、错误处理、禁止事项全部堆在一起。更合理的结构是三层：全局层（跨项目的个人偏好，如注释语言、提交信息格式）、项目层（架构分层、目录结构、技术选型约束）、模块层（仅对特定子系统生效的细则）。一个典型的项目级规范文件骨架如下（示意）：

# 项目工程规范
## 架构约定
- 分层：api / service / repository，依赖方向只能自上而下
- repository 层禁止 import service 层
## 命名规范
- 函数名以动词开头，小驼峰
- 数据库表与字段使用小写下划线
## 错误处理
- 统一通过 Result 结构传递失败，禁止异常穿透层边界
- 对外错误必须映射为错误码，内部日志保留完整堆栈
## 禁止事项
- 禁止在循环体内发起网络或数据库请求
- 禁止绕过 service 层直接在 api 层访问数据库

2. 把规则文件当代码来管理

规范文件应该进版本库、走评审、有明确 owner、定期重构。尤其要建立“规则退役”机制：架构演进后，过时规则不是留着占篇幅，而是果断删除。规则与代码一样，只在被持续维护时才可信。

3. 能自动化的，就不要写成散文

“提交前必须格式化”这类要求，写成自然语言，智能体未必每次遵守；挂一个自动运行的格式化钩子，则几乎百分之百生效。经验法则是：凡是机器能检查的（格式、依赖方向、命名模式），交给自动化工具强制执行；规范文件里只留机器查不了的“判断题”。

4. 负面清单必须可验证

“不要写烂代码”是无效规则，“禁止在循环内发起网络请求”才是有效规则。判断标准很简单：读这条规则的人或机器，能否在没有主观理解加持的情况下判断“违反了没有”。模糊的规则约束不了智能体，只会稀释整个文件的权重。

5. 警惕上下文的稀释效应

规范文件越长，单条规则获得的注意力越低。行数膨胀到几百行之后，对文件末尾规则的遵守率下降是普遍现象。要定期做减法：合并重复、拆分层级、把低频规则移出主文件。Harness 的质量不取决于厚度，而取决于信噪比。

6. 区分“事实”与“约束”

“本项目使用消息队列解耦订单与库存”是事实，帮助智能体理解背景；“消费者中禁止同步调用外部接口”是约束，划定行为边界。两类内容混排时，优先保证约束规则位置靠前、表述简短。

七、重新理解“写代码”这件事

回到最初的困惑：写规范文件的时间比写代码还多，算不算浪费？

答案取决于你如何定义“工程活动”。在智能体深度参与的开发范式里，开发者的核心产出，正在从“代码本身”转向“让代码被正确产出的条件”。过去我们靠脑内经验、口头评审、散落文档维系这些条件；现在，它们被要求以更结构化、更可执行的方式沉淀下来。

所以，Harness Engineering 的本质可以浓缩为一句话：把“你如何理解工程”固化成可复用、可验证、可传承的资产。写代码的收益止于当下这个功能；写缰绳的收益，作用于此后产出的每一行代码。

那些觉得“在给规范文件打工”的日子，其实是在做工程师职业生涯中回报周期最长的一类投资——把你脑子里的东西，变成团队和智能体都能用的东西。