工具工程

# 引擎工程 - ai-literacy-superpowers 来源：https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/ https://github.com/Habitat-Thinking/ai-literacy-superpowers/edit/main/docs/plugins/ai-literacy-superpowers/explanation/harness-engineering.md 引擎工程是一种实践，通过结合确定性工具、基于代理的审查和周期性的熵检查，来约束AI辅助的代码生成，从而确保AI生成的代码长期保持正确性和一致性。本文档解释了这一思想的起源、组成部分以及本插件如何实现它。 ## 起源¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#the-origin) 该术语源自 Birgitta Boeckeler 发表在 martinfowler.com 上的文章，文章写作于 ThoughtWorks 团队使用AI编码助手交付实际软件的背景下。Boeckeler 注意到了许多团队独立发现的一个现象：AI 助手生成的代码看起来合理，但如果不受约束，它们会产生偏差。它们会忘记规范，重复犯错，并逐渐侵蚀代码库的内部一致性。代码依然能编译通过和通过测试。这种退化是悄无声息的。 Boeckeler 的洞见在于，这个问题在软件工程中已有类似的解决方案：测试工具集（test harness）。测试并不能从构造上保证代码的正确性，它们只能检测代码何时不再正确。测试工具集并不约束你编写什么样的代码；它是一种持续检查你所写代码是否符合标准的机制。工具集并不信任程序员，它进行验证。 同样的逻辑适用于AI辅助开发，但有一个关键区别。测试工具集检查功能正确性：程序是否按预期工作？用于AI编码的工具集需要检查更广泛的方面：代码库是否仍然体现了团队商定的架构决策、命名规范、安全约束和结构规则？功能测试是必要的，但并不足够。你需要一种不同类型的工具集。 这就是引擎工程所提供的。 --- ## 三个组成部分¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#the-three-components) Boeckeler 描述了工具集必须解决的三类问题。 ### 上下文工程¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#context-engineering) AI编码助手只能在它所知的范围内工作。如果它不知道你的项目使用某个特定的日志库，它会自己发明一种方法。如果它不知道你从不使用可变的全局状态，它会在方便时使用。如果它不知道所有数据库写入都必须通过某个特定的抽象层，它会绕过这个层。 上下文工程是确保AI了解它需要知道什么的学科。在实践中，这意味着维护一份文档——在本插件的规范中是`HARNESS.md`——它记录了技术栈、架构决策、命名规范、约束以及每个决策背后的原理。这份文档不是给程序员看的README。它是给AI看的知识库。它需要准确、具体，并保持最新。 这个区别很重要：README解释项目是做什么的。上下文文档告诉AI代理它必须做什么、不能做什么以及为什么。这是面向不同受众、具有不同更新节奏的不同文档。 ### 架构约束¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#architectural-constraints) 知道规则和执行规则是两个独立的问题。你可以将每条约束都写入`HARNESS.md`，AI仍然会违反它们，因为AI是一个为“看起来合理”而优化的概率系统，而不是一个遵守规则的机器。上下文工程减少了违规行为，但并不能消除它们。 架构约束是捕捉违规行为的机制。Boeckeler 将执行点称为“验证槽”——在开发工作流中定义的检查点，检查要么通过，要么阻止进度。每个验证槽的关键设计决策是使用确定性工具还是基于代理的审查。 确定性工具是检查器、脚本、正则表达式检查、文件结构断言——任何能产生通过/失败结果而无需判断的东西。当约束可以精确表达时，它们是首选。它们快速、廉价，并在其规格内完全可靠。 基于代理的审查是语言模型根据约束描述审查代码并做出判断。当约束涉及难以表达为机械规则的意图、语义或模式时，这是必要的。代理成本更高且确定性更低，但它们能捕捉到任何脚本都无法捕捉的东西。 两种类型的验证槽都属于工具集。随着时间的推移，目标是将约束从基于代理的审查迁移到确定性检查，前提是你对约束的理解足够清晰，能够精确地进行规范。这就是下文描述的渐进硬化原则。 ### 垃圾回收¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#garbage-collection) 代码库是一个动态系统。即使有良好的上下文工程和严格的架构约束，熵也会累积。死代码会增长。TODO注释会持续数月。依赖项会过时。在项目某个阶段有意义的抽象，在后期阶段可能变成障碍。早期制定的规范在变得不便时会被悄然抛弃。 垃圾回收是与这种熵进行斗争的周期性过程。与在代码生成或审查时运行的另外两个组件不同，GC按照计划运行。它不被特定的编码事件触发，它的运行仅仅因为时间的流逝。 在引擎工程框架中，GC规则是对“干净”状态的明确声明，并配合按计划运行的代理或脚本来检查代码库是否仍然符合这些标准。其输出不是一份阻止PR的错误列表；而是一份报告，在问题变得严重之前，将注意力引向累积的问题。 --- ## 有生命力的工具集¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#the-living-harness) 一个维护良好的工具集最重要的特性是它不是静态的。一个只编写一次而从不更新的工具集，反映的是团队在某个时间点的理解。代码库持续演进。新模式出现。旧约束变得无关紧要。原始作者未预料到的新类型的AI生成错误会出现。 `HARNESS.md`被设计为一个自引用文档。它不仅描述当前生效的约束；还跟踪每个约束的状态：是当前未验证、正在代理审查中，还是已被确定性地强制执行。文档声明了什么是应该成立的。代理、钩子和CI检查验证它是否成立。工具集审计员——本插件中的一个按计划运行的代理——读取这些检查的结果，并更新`HARNESS.md`中的状态条目以反映现实。 这就创造了一个反馈循环。这份文档既是一份规范，也是一份健康记录。在任何时候阅读`HARNESS.md`，不仅能告诉你团队对代码库商定了什么，还能告诉你这些协议实际执行得如何。 自引用特性是有生命力的工具集与一份会过时且被忽视的文档的区别所在。因为工具集本身是执行的对象——工具集审计代理检查`HARNESS.md`是否准确反映了当前的验证状态——忽视工具集会变得可见而非不可见。进入这个自检查的日常入口是`/harness-sync`，它运行审计检测逻辑并呈现统一的偏差表；用户无需记得调用单独的诊断工具，就能看到声明的工具集与现实之间的不一致。 --- ## 渐进硬化¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#progressive-hardening) 并非所有约束都是平等的，也并非所有约束从一开始就准备好被确定性地执行。渐进硬化描述了约束如何成熟的晋升阶梯。 阶梯是一个维度。**触及范围**——约束是要求在每个PR上都检查，还是**出现即检查**——是第二个维度，`执行方式`字段并未记录它。 **未验证**是起始状态。你在`HARNESS.md`中声明了一条约束。你认为它很重要。你还没有机制来检查它。这个状态不是失败；它是诚实的说明。未验证的约束是建立执行机制的承诺，而非声称执行已经存在。 **代理**是第二个状态。你编写了一个代理提示，在PR审查或计划检查中检查该约束。该约束正在被强制执行，但由语言模型进行判断，而不是由确定性规则。代理执行在大多数情况下能捕获大多数违规行为。它并非完全可靠，并且需要人工审查代理的输出。 **确定性**是最终状态。你已经将约束表达得足够精确，可以将其编码为脚本、检查器规则或结构检查。它在CI中运行。要么通过，要么阻止合并。不涉及判断，也没有检查可能被混淆或误导的情况。 移动的方向总是朝着确定性。当一个代理反复捕获同一类违规时，这种重复就是一个信号：该模式现在已被充分理解，可以自动化了。编写脚本，弃用针对该特定约束的代理检查，并将`HARNESS.md`中的条目更新为确定性状态。 渐进硬化很重要，因为它防止了两种失败模式。第一种失败模式是从一开始就试图将所有约束都确定性地执行，这对于新颖或语义复杂的约束来说是不可能的。第二种失败模式是接受基于代理的执行作为永久状态，这既昂贵又不可靠。阶梯为你提供了一条介于两者之间的路径。 --- ## 本插件如何实现它¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#how-this-plugin-implements-it) 本插件将验证槽结构化为三个执行循环，在不同的时间尺度上运行，并对假阳性有不同的容忍度。 **内循环**是建议性的，在编辑时运行。当你保存文件或完成一个编码会话时，会运行轻量级检查，并将潜在问题作为建议而非阻断性错误呈现。内循环优化了低摩擦。它不应打断工作流程。它的职责是尽早发现问题，而不是停止工作。 **中循环**是严格的，在PR时运行。当你打开一个拉取请求时，会运行一整套基于代理和确定性的检查。这个循环有权阻止合并。它是架构约束的主要执行点。这里的失败必须在代码合并之前解决。 **外循环**是调查性的，按计划运行。垃圾回收规则、适应度函数和工具集审计会定期运行——每日、每周或任何适合该规则的周期。外循环生成报告而非阻断。它的发现会作为潜在的新约束或现有约束的更新反馈到工具集中。 这三个循环大致对应于三个组成部分：内循环服务于上下文工程（在当下保持AI知情），中循环服务于架构约束（在集成时执行商定的标准），外循环服务于垃圾回收（在集成事件之间检测缓慢的熵增）。 本插件中的代理在有限信任下运行。没有代理有权单方面修改生产代码或合并更改。代理进行审查、建议、报告和标记。人类做决定。这是一个刻意的设计选择：工具集放大人类的判断力；它不取代人类。 --- ## 自我改进维度¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#the-self-improving-dimension) Boeckeler 的原始框架将工具集描述为团队构建和维护的东西。本插件增加了一层：工具集可以从自身的运行中学习。 每次编码会话后，`/reflect`命令会捕捉哪些做得好、哪些失败了、哪些规范被违反了以及哪些新模式出现了。这些反思会累积在学习日志中。工具集代理在做决策时会阅读这份日志，因此过去的错误模式会为当前的审查提供信息。 回归检测朝着同一个方向工作。当工具集审计代理运行时，它不仅检查当前约束是否被满足。它会查看约束违规的历史以识别模式：相同的约束是否被反复违反？如果是，这表明该约束需要更强的执行机制，或者上下文文档没有清晰解释其原理，或者约束本身是错误的，需要重新考虑。 这闭合了原始框架中留下的一个开放环节。一个静态的工具集只有在人类注意到失败并手动更新它时才会变得更好。一个自我改进的工具集将其自身的操作历史视为输入数据，并为其自身的改进生成建议。人类仍然决定接受哪些建议，但模式识别的工作——阅读违规日志并注意到相同的错误反复出现——被委托给了代理。 本插件中的自动工具集添加进一步扩展了这一点：`harness-init`过程本身会读取现有代码，以推断已存在于代码库中但尚未声明的约束。无需要求团队从头指定所有内容，代理会根据观察到的模式引导生成一个候选的`HARNESS.md`，并请求开发者确认、拒绝或完善每个条目。人类仍然是权威，但构建工具集的初始成本被大幅降低了。 `harness-init`也支持增量采用。团队选择要配置哪些功能——上下文工程、约束、垃圾回收、CI和可观测性——并且可以稍后重新运行该命令以添加更多功能。现有配置在多次运行中得以保留。这意味着团队可以从仅上下文和约束开始，证明其价值，然后在准备好时添加垃圾回收和CI执行。工具集随着团队的成熟而成长，而非要求一开始就完全承诺。 --- ## 延伸阅读¶ (https://habitat-thinking.github.io/ai-literacy-superpowers/plugins/ai-literacy-superpowers/explanation/harness-engineering/#further-reading) 本插件的概念基础建立在 Birgitta Boeckeler 的