IT 程序员必须了解的 Harness Engineering：真正决定 AI 编程效率的，不只是模型

打开 AI 编程工具，输入需求，几十秒后得到一段代码——这件事已经不稀奇了。真正让我们程序员头疼的是实际投产和提效：AI写的代码与现有架构规范不一致；换个会话得重新解释技术栈和目录结构；AI 代码是写得很快，但我们检查、返工却花了很多时间。 其实问题不是模型不够强，也不是提示词写得不够详细，而是现在的大模型没有记忆，而我们又缺一套能让 AI 稳定工作的工程环境。这正是今天要讲的 Harness Engineering 要解决的问题。 不同于Prompt Engineering，Harness Engineering关心的不仅仅是“怎么问 AI”，还关心怎么把上下文、工具、规则、执行环境、验证手段和反馈等等组织起来，让 AI 能够持续正确的完成任务。 对普通程序员来说，不需要从零开始开发一个 Agent 平台，但必须理解 Harness Engineering。因为 AI 辅助编程的效率上限，越来越取决于我们为 AI 搭建了怎样的工作脚手架。

为什么用了AI，开发效率还是没有明显提升

刚开始用AI辅助编程的时候我和我的同事都多多少少有过这个困惑，总结发现几点原因：

• 每次开启新对话，AI不记得过去的对话内容，要重新解释项目背景、技术栈和目录结构。

• AI开发的一些功能方法在项目中的其他模块已经有这个功能了。

• 针对任务AI修改了相关代码，但不知道为什么还顺手“优化”了几个无关文件。代码评审时加大了工作量。

• AI说“开发任务已经完成”，实际上没有运行测试，连冒烟测试都过不了。

• 项目涉及多语言，AI总是只改了一种语言而漏加了其他语言的语料。 这些问题很难靠一句更长、更详细的提示词解决，而且也不适合每次对话都发送巨长无比的提示词给AI。真实的软件开发是一条连续链路。AI 需要先理解项目，再定位代码，接着修改文件、运行工具、读取报错、继续修复，最后证明结果符合验收条件。其中任何一环缺失，AI 都可能生成一堆屎山代码。所以，程序员需要完成一次思维转变：从研究“怎样向 AI 提问”，转向设计“怎样让 AI 在项目里稳定工作”。

Harness Engineering 到底是什么

我们如果把AI模型看成是一名开发能力很强，但对项目几乎不了解的新同事，那么Harness 就是这名同事周围的工作环境和给他使用的办公工具。项目文档告诉它背景，代码搜索帮助它定位信息，权限规则限制它的行为，测试和构建判断结果是否正确，最后再由人类程序员处理需要业务判断的部分。新同事的研发能力很重要，但能力只有被放进完整的工作运行环境，才能持续产生可靠结果。 它与几个常见概念既有关联，也有侧重点上的区别：

• Prompt Engineering：重点是如何表达当前指令。

• Context Engineering：重点是当前任务应该向模型提供哪些信息。

• Agent Engineering：重点是让模型能够规划步骤、调用工具并持续执行。

• Harness Engineering：重点是把上下文、工具、规则、执行环境、验证和反馈循环组织成一套可重复的工程系统。

当然这些术语仍在发展，边界并非完全统一。上述表述是个人见解，是为了帮助理解，不宜把它们当成已经形成统一标准的行业定义。

程序员必须掌握的五个知识点

一、上下文不是越多越好，而是要按任务精准供给

AI 判断错误可能是来自于以下两个原因之一。一种是信息太少，例如，让 AI 修改支付回调，却没有告诉它接口幂等规则、订单状态流转方式和现有异常处理约定。模型只能根据局部代码补全一个“看起来合理”的答案。另一种是信息太多，把整个仓库、所有规范和大量历史文档一次性塞给 AI，不仅增加处理成本，也可能稀释当前任务真正重要的信息。 比较实用的做法，是把上下文分成两层。项目级上下文负责说明“这是一个怎样的项目”，通常包括：

• 技术栈及主要版本；

• 核心目录及模块职责；

• 启动、测试和构建命令；

• 编码规范；

• 关键架构约束；

• 禁止修改的区域；

• 已知风险和高风险操作。 任务级上下文负责说明“这一次具体要做什么”，通常包括：

• 相关代码和配置；

• 接口或数据契约；

• 报错日志；

• 预期行为；

• 验收条件；

• 允许修改的文件或目录；

• 已经尝试过但无效的方法。 这里不建议无差别地把整个仓库发送给AI处理。建议流程是先搜索和定位，再读取相关文件，最后按任务需要补充上下文。我们可以根据不同 AI 编程工具编写AGENTS.md、CLAUDE.md，在其中写清项目入口、常用命令、目录结构、基本规范和禁止事项。重点不是文件写得多完整，而是内容必须与仓库当前状态一致。这个文档也不用完全人工来编写，可以让AI阅读现有代码后编写，人工进行核查修改。 另外还可以使用一些工具来辅助AI了解项目，比如开源框架GitNexus （ https://github.com/abhigyanpatwari/GitNexus ）就是一个可以将项目转换成AI可以理解的知识图谱，它通过索引代码库中的每个依赖、调用链、集群和执行流程，帮助 AI 智能体深度理解代码结构。目前已有4万多颗星，强烈推荐大家进行了解和试用。

二、用“渐进式披露”控制 Skill 的加载顺序

我们程序员通常觉得AI提效效果不及非技术人员预期的原因之一是我们处理的是复杂项目，AI在复杂项目上总是做的不如人意。这可能是因为遇到了另外一个问题：如何在复杂项目中给AI当前需要的信息。整个项目AI可能用到的知识很多，但当前任务真正需要的只有一小部分。如果把数据库诊断、接口设计、代码审查、发布流程和安全规范全部作为常驻规则，AI 每次执行一个小任务，都要背着一大包未必相关的信息。这就涉及到了程序员需要了解的另一个技巧：“渐进式披露”。 “渐进式披露”的思路是按照任务进展逐层加载知识。 第一层只提供能力目录，告诉 AI 有哪些 Skill，以及它们分别适用于什么场景。例如：

• SQL 性能诊断：适用于慢查询、索引失效和执行计划分析；

• 接口兼容性检查：适用于请求参数、响应结构和错误码变更；

• 单元测试补全：适用于已有模块缺少关键分支覆盖的情况。 当 AI 判断当前任务确实需要“SQL 性能诊断”时，再进入第二层，读取这项 Skill 的完整操作流程，包括所需输入、诊断顺序、可调用工具、禁止事项和完成标准。 只有执行到具体环节时，才进入第三层，加载相应的脚本、模板或版本资料。例如，需要分析执行计划时，再读取对应数据库版本的参考材料，而不是从任务一开始就把所有数据库文档都塞进上下文。 需要特别强调：渐进式披露Skill 不是堆砌一批提示词。而是要把触发条件、操作步骤、工具和验证标准封装起来。一个可复用的Skill，至少应该回答五个问题：

1. 什么情况下使用？
2. 执行前需要哪些输入？
3. 应该按什么步骤操作？
4. 哪些事情不能做？
5. 怎样判断任务已经完成？

三、工具不仅要能调用，还要可预测

AI 要真正参与复杂系统的开发，还要能够运行命令对接其他系统、查询其他工具文档、执行相关测试并查看差异。这些能力都可以通过工具提供，但AI“接入了工具”不等于工具已经好用。一个适合 AI 调用的工具，至少应满足以下要求：

• 名称能够准确表达用途；

• 参数含义清楚，必填项和可选项明确；

• 返回结果结构稳定；

• 失败时提供可以继续行动的信息；

• 单个工具不要承担过多不相关职责；

• 高风险操作具备权限限制、隔离或人工确认机制。 例如，一个命令失败后只返回“执行失败”，AI 很难判断究竟是参数错误、权限不足、文件不存在，还是测试本身未通过。如果返回退出码、关键错误信息、执行目录和失败阶段，AI 才有机会修正参数并再次执行。 检查工具是否真正接入反馈闭环，可以问一个简单的问题：

工具失败后，AI 能否仅根据返回结果判断失败原因，并决定下一步怎么做？

如果不能，这个工具虽然可调用，却还不可用。就比如你提供了工具来测试验证AI的代码，但是当发生错误时（比如传入了不符合规范的参数）工具却不能给出具体错误原因，那么就AI可能也就无法快速的调整和修复了。

四、把验收标准变成机器可以执行的反馈

AI写完代码通常也会做一些验证检测，比如如果项目中有单元测试，AI可能会执行单元测试，但如果没有明确要求，这种验证检测范围通常是不稳定的。而为了提升效率，获得更加可靠稳定的代码，我们就需要给出明确的验收反馈，例如：

• 格式检查是否通过；

• 类型检查是否通过；

• 新增单元测试是否通过；

• 原有测试是否出现回归；

• 项目是否能够成功构建；

• 静态分析是否发现新增问题；

• 接口响应结构是否保持兼容；

• 代码差异是否超出允许范围。 一条最小验证链可以是：

修改代码 → 格式检查 → 类型检查 → 单元测试 → 构建 → 查看差异 → 人工审核

并非所有项目都要机械执行全部步骤。修改一处文案和调整数据库迁移脚本的验证强度显然不应该相同。关键是根据改动风险，在任务开始前就约定完成条件。 例如，与其说“修复用户注册问题”，不如明确为：

• 修复重复邮箱注册时的异常处理；

• 不改变现有成功响应结构；

• 为重复邮箱场景增加测试；

• 相关模块原有测试必须通过；

• 不修改数据库结构；

• 完成后展示代码差异和测试结果。 验证失败后，还要把错误输出重新交给 AI。只有形成“修改—验证—读取结果—继续修复”的循环，测试才真正成为 Harness 的一部分。

五、限制修改范围，比反复纠错更省时间

AI完成任务，还有另外一种常见问题是AI的修改又扩大了影响面。AI为了修复类型错误有可能会升级依赖库，为了让自己测试能够通过可能又会修改测试自己，也可能因为解决一个接口而重构一个公共模块。每一项修改单独看来都有道理，但是回头看这样的修改又是扩大了影响面，需要评审和测试的范围也会很大。 因此建议给AI的任务最好有一个边界：1. 代码边界：哪些目录和文件可以改、哪些接口可以改、哪些公共能力不能改 2. 操作边界：哪些操作可以直接做、哪些操作要人确认 3. 环境边界：允许否访问网络、读取环境变量、连接服务、接触敏感数据等。删除文件、升级依赖、执行数据库迁移、碰上线，都应该能大概做到哪里人来明确确认。 另外有建议把大任务拆成一个个可以单独测试的小任务。一步脚踏一步，每次只实现目标的一部分，大大减小了代码变动量，出现问题也能较快排查问题出自哪里。

怎样搭建一套最小可用 Harness

其实我们不用一开始就去建设复杂的平台。对一般开发者或者较小的创业公司而言，甚至可以先这么做6步。

第一步：整理一页项目入口信息

内容包括：

• 用途、技术栈；

• 启动、测试、检查、构建命令；

• 核心目录、目录意义；

• 代码风格；

• 不准改动的内容；

• 需人手动确认的内容；等等。

  尽量保持1页内。详细内容后续通过渐进式披露实现。

第二步：定义任务完成标准

每次让 AI 修改代码前，写清四件事：

1. 要获得什么样的结果业务；
2. 准许修改的东西；
3. 要进行哪些检测；
4. 哪些事情需要考虑交由人工审查。

第三步：接通基础开发工具

首先保证 AI 能够完成最短的开发链路：搜索代码 → 读文件 → 编辑文件 → 跑测试 → 运行构建 → 看差异。工具不必多，但每一个工具都有清晰的输入、输出、失败信息。

第四步：沉淀第一个可复用的渐进式披露Skill

不要先写一大套“大而全”的skill库。先从团队遇到比较频繁的、步骤基本固定的任务入手，例如：

• 根据报错日志定位问题；

• 为已有模块添加单元测试；

• 校对接口修改前后是否“互不兼容”；

• 执行团队代码审查的规范步骤。 Skill 中至少写明条件、输入资料、操作步骤、禁止事项、达成标准。低频的模板、脚本、参考文档放在外面，在每步操作实行到对应步骤时加载。

第五步：建立自动验证和反馈循环

要求 AI 按约定自动地继续测试，并输出失败后再继续进行修复。同时加上停止的条件。如一直失败多次、要改大的范围、要升级依赖、要做不可逆的事情等，不能让 AI 一直失败重跑下去，需要交给人类程序员判断。

第六步：复盘失败任务

不要把所有的失败都说成是因为“模型不够聪明”。可以逐一筛查如下： 1）模型拿到必要上下文了吗？ 2）任务拆分大吗？ 3）工具输出描述得明白吗？ 4）验收标准可执行吗？ 5）权限边界、修改的边界清楚吗？ 6）失败信息有没有送到下一轮？ 7）这个任务是否本来就需要人工业务判断？ 这样的复盘才会沉淀为下一次可以复用的工程改进。

三个容易踩的误区

误区一：Harness Engineering 就是多接几个工具

但工具数目并不是工程能力。如果工具职责重叠、参数不清晰、错误的输出无法阅读，AI 反而更加容易选错工具。真正重要的还是工具能否造出一条流水顺畅、可预知、可验证的执行“流水线”。

误区二：把所有规则一次性塞进上下文

如果规则越多，那么维护成本就越高，也越容易让当前任务失去重点。现行有效的方式是把信息分成三类：项目规则可少量常驻、开发当前任务所需的上下文内容、需要通过渐进加载的复杂知识。

误区三：有自动测试就可以取消人工审核

自动测试只能验证已经被明确的业务逻辑。业务理解、架构取舍、安全风险仍然需要人类程序员负责把关。即使代码通过现有的所有自动测试，我们也不能保证业务逻辑正确、没有安全问题或达到上线质量的。

程序员的新能力，不只是会不会调用模型

AI 辅助编程正在改变程序员的工作效率也在改变着工作重心。过去，我们主要关心怎样写好每一行代码。现在还要学会给AI定义任务、组织上下文、配置工具、限制权限、设计验证机制，并在AI无法处理时进行人工介入。这并不意味着编码能力不再重要。恰恰相反，只有理解代码、架构和业务，人类程序员才能判断应该向 AI 提供什么信息、设置什么要求，以及用什么来验证任务已经完成。普通程序员不需要从零开发 Agent 平台，但应该尽早搭建自己的最小 Harness：一份可靠的项目说明、一套明确的任务模板、几个高频 Skill、一条能够自动执行的验证链，再加上必要的人工审核点。