harness engineering 是围绕 AI 辅助代码生成的实践，使用确定性工具、基于代理的审查和定期的熵检查，以确保 AI 生成的代码随着时间的推移保持正确和一致。本文件解释了这个想法的来源、它的组成部分以及该插件如何实现它。起源 ¶ 该术语来源于 Birgitta Boeckeler 在 martinfowler.com 上的文章，写于 ThoughtWorks 的背景下，描述了团队使用 AI 代码助手交付真实软件。 Boeckeler 观察到了许多团队独立注意到的现象：AI 助手生成的代码看起来合理，但如果不加约束，它们会偏离轨道。它们会忘记约定、重复错误，并慢慢侵蚀代码库的内部一致性。代码持续编译并通过测试，但降级是悄然无声的。Boeckeler 的见解是，这个问题在软件工程中已经有了一个解决的类比：测试工具。测试并不会通过构造保证代码的正确性，而是检测何时代码停止正确。测试工具并不是对你编写的代码的限制；它是一个持续检查你所写内容是否符合标准的机制。该工具不信任程序员，而是进行验证。这一逻辑同样适用于 AI 辅助开发，但有一个关键的不同之处。测试工具检查功能正确性：程序是否按照预期执行？而 AI 编码的工具需要检查更广泛的内容：代码库是否仍然体现团队一致认可的架构决策、命名约定、安全约束和结构规则？功能测试是必要的，但不足以满足这一需求。你需要一种不同类型的工具。这就是 harness engineering 所提供的内容。三大组成部分 ¶ Boeckeler 描述了测试工具必须解决的三类问题。上下文工程 ¶ AI 编码助手只能在其知道的范围内工作。如果它不知道你的项目使用了特定的日志库，它将自己发明一种方法。如果它不知道你从不使用可变的全局状态，它在方便的情况下会使用它。如果它不知道所有数据库写入必须经过特定的抽象层，它将绕过该层。上下文工程是确保 AI 知道它需要了解的知识的学科。实际上，这意味着维护一个文档——在本插件的约定中为 HARNESS.md——该文档捕获了技术栈、架构决策、命名约定、约束及其背后的理由。该文档不是人类的 README，而是 AI 的知识库。它需要准确、具体并保持最新。这个差别很重要：README 解释项目的功能，而上下文文档则告诉 AI 代理必须和绝对不能做的事情及其原因。这些是面向不同受众、更新节奏不同的不同文档。架构约束 ¶ 知道规则和执行规则是两个不同的问题。你可以将每个约束都写入 HARNESS.md，AI 仍然会违反它们，因为 AI 是一种优化合理性的概率系统，而不是遵循规则的机器。上下文工程减少了违约行为，但并不能消除它们。架构约束是捕捉违规行为的机制。Boeckeler 将执行点称为“验证插槽”——在开发工作流中定义的时刻，检查运行并通过或阻止进展。每个验证插槽的关键设计决策是它是否使用确定性工具或基于代理的审查。确定性工具是一种静态检查工具、脚本、正则表达式检查、文件结构断言——任何能够在没有判断的情况下生成通过/失败结果的工具。当约束可以精确表达时，这些工具是首选。它们快速、廉价，并在其规范范围内完全可靠。基于代理的审查是语言模型根据约束描述检查代码并进行判断。这在约束涉及意图、语义或难以作为机械规则表达的模式时是必要的。代理更加昂贵且不够确定，但它们能够捕捉到没有脚本能够捕捉到的问题。这两种类型的验证插槽都属于测试工具。随着对约束理解的加深，目标是将约束从基于代理迁移到确定性。这个过程就是渐进加固原则，下面将描述。垃圾回收 ¶ 代码库是一个动态系统。即使在良好的上下文工程和严格的架构约束下，熵也会累积。无用代码会增加。TODO 注释会持续数月。依赖关系会失去新鲜感。在项目早期阶段有意义的抽象在后期可能会变成障碍。早期确立的约定在变得不方便时被悄然放弃。垃圾回收是定期对抗这种熵的过程。