Harness Engineering：工程化驾驭AI编程助手，从智能补全到规格驱动开发

1. 项目概述：从“智能补全”到“工程化驾驭”

如果你和我一样，在过去一两年里尝试过各种AI编程助手，从GitHub Copilot到Cursor，再到Claude Code，你很可能经历过一个典型的“过山车”式的心路历程：从最初的惊艳——“它居然能猜出我要写什么！”，到随后的困惑——“这代码风格怎么这么怪？”，再到偶尔的愤怒——“它把我整个函数逻辑都改错了！”。最终，很多人会把它降级为一个“高级一点的自动补全工具”，只在写样板代码或简单注释时用用。这太可惜了，我们仿佛手握一把光剑，却只用来削苹果。

“Harness Engineering”这个项目，正是为了解决这个核心痛点。它不是一个新工具，而是一套工程方法论和最佳实践手册。其核心主张非常明确：AI编程助手不应该仅仅是一个“聪明的补全工具”，而应该被“工程化地驾驭”（Harness），成为软件开发流程中一个可靠、可控、可预测的组成部分。这就像驯服一匹野马，你需要的不只是勇气，更需要一套合适的马具（Harness）、明确的指令和长期的训练方法。项目作者 Gabriel Ferreira 将这套方法体系化，旨在帮助工程团队和科技组织，在真实、大规模的项目中，系统性地用好AI编程助手。

简单来说，它回答了一个我们都在摸索的问题：“在真实的、有历史包袱、有复杂业务逻辑和团队规范的工程项目中，如何让AI助手持续、稳定、安全地输出高质量代码，并真正融入我们的开发流程，而不是制造混乱和技术债？”这个手册覆盖了从理念、上下文工程、智能体编排、验证到团队协作和治理的完整链条，是为那些决心将AI生产力提升到新层次的资深工程师、技术负责人和工程管理者准备的实战指南。

2. 核心理念与六大层次解析

为什么我们现有的使用方式常常失效？根本原因在于，我们默认AI助手拥有和我们一样的“项目上下文”和“工程直觉”。但实际上，它没有。它每次对话都是一个“失忆的天才”，需要我们从零开始为其构建一个临时的、有限的认知环境。Harness Engineering 的核心，就是系统地构建和维护这个认知环境，并将其标准化、工程化。

手册将一套成熟的“驾驭体系”（Harness）分解为六个互补的层次，这为我们理解如何与AI协作提供了一个极其清晰的心智模型。

2.1 第一层：知识（Knowledge）—— 项目的“记忆库”

这是最基础的一层，指AI完成任务所需的所有背景信息。但手册强调，这远不止是打开几个相关文件那么简单。它需要被精心组织。

• 静态知识：项目规格说明书（Spec）、产品需求文档、架构设计图、API文档。这些是项目的“宪法”。
• 动态知识：项目待办列表（Backlog）、最近的会议纪要、尚未合并的Pull Request讨论。这些是项目的“近期记忆”。
• 上下文知识：当前任务相关的业务领域知识、历史决策原因（比如“为什么我们当初选择了MongoDB而不是PostgreSQL”）。

实操心得：很多团队犯的错误是，要么给AI太多无关文件，耗尽其上下文窗口；要么给得太少，让它“盲人摸象”。手册建议建立一种“分层递进”的上下文加载策略：先给一个高度精炼的摘要（如ARCHITECTURE_OVERVIEW.md），再根据任务范围，按需引入更具体的文件。永远不要假设AI“知道”那些没在对话中明确提及的事情。

2.2 第二层：专长（Expertise）—— 领域的“检查清单”

这一层关乎“如何做”。不同的开发任务（如“编写一个React组件”、“设计一个REST API”、“优化数据库查询”）有其特定的最佳实践、陷阱和步骤。手册将这些固化为一套套“技能”（Skills）。

• 技能即检查清单：一个“技能”可以是一个Markdown文件，例如skill_api_design.md，里面列出了设计API时需要遵循的所有规则：必须使用版本前缀（/v1/）、响应格式必须封装在data字段内、错误必须使用标准HTTP状态码和错误码、必须编写OpenAPI文档等。
• 按需调用：当要求AI“新增一个用户查询接口”时，你可以附加指令：“请遵循skill_api_design.md中的规则”。这样，AI的输出就会自动对齐团队的工程标准，而不是发明一套新的、可能不符合规范的API。

2.3 第三层：自动化（Automation）—— 只读的“子智能体”

当任务超出简单代码生成，需要探索、研究或执行特定自动化脚本时，就需要“智能体”（Agents）。手册特别强调了一个关键安全原则：这些子智能体应该是“只读”的。

• 何为只读智能体？例如，一个“研究智能体”可以接受指令：“浏览项目文档和代码，总结当前用户认证模块的实现方式，并找出与OAuth 2.0标准可能的偏差。” 它只能读取、分析、汇总信息，但不能直接修改任何代码文件。
• 安全边界：这明确划分了“研究”和“执行”的界限。人类或主协调流程在审阅了研究报告后，再决定是否以及如何执行修改。这避免了AI因误解而直接进行破坏性操作的风险。

2.4 第四层：编排（Orchestration）—— 任务的“指挥家”

这是控制流程和资源的核心。AI的上下文窗口（Context Window）是宝贵且有限的资源，不能任由一次对话无限膨胀。

• 上下文预算（Context Budget）：为每个任务或会话设定一个明确的上下文令牌（Token）预算。这迫使你精炼输入，优先传递最关键的信息。例如：“本次任务上下文预算为8000 tokens，请优先使用spec-payment.md和src/payment/目录下的文件。”
• 隔离会话（RPI模式）：手册推荐将复杂任务分解为三个隔离的会话阶段：
  1. 研究（Research）：只读阶段，收集信息，理解现状。
  2. 规划（Plan）：基于研究结果，制定具体的实现步骤、文件变更列表和验证方法。
  3. 实现（Implement）：执行规划，生成或修改代码。 每个阶段都是独立的对话，拥有自己的上下文预算，这保证了思维的聚焦，并防止前期探索的“思维碎片”污染后期的代码生成。

2.5 第五层：验证（Verification）—— 可执行的“完成定义”

AI生成的代码，在合并前必须经过验证。但这不能只依赖人工肉眼检查。手册提倡“可执行的完成定义”（Executable Definition of Done）。

• 自动化验证脚本：为每类任务配套一个验证脚本（如verify.sh）。当AI完成一个API端点的开发后，它应该能自动运行这个脚本。脚本可能包括：启动一个测试数据库、运行针对新端点的集成测试、用curl发起一系列请求验证响应格式和状态码、运行代码风格检查（Lint）等。
• “第二个文件”测试：这是一个非常精妙的实践。要求AI在修改一个文件（如service.py）后，必须同时更新或创建另一个相关的文件（如test_service.py或api_docs.md）。这迫使AI理解代码变更的连带影响，而不仅仅是孤立地完成一个文件。

2.6 第六层：连续性（Continuity）—— 会话间的“状态保持”

AI对话是短暂的。如何让上一次会话的决策和状态延续到下一次？手册提出了使用持久化的上下文文件，例如STATE.md。

• STATE.md模式：在会话结束时，要求AI将当前任务的关键决策、待办事项、下一步计划、以及重要的上下文摘要，写入一个名为STATE.md的文件。当下次继续这个任务时，首先将STATE.md的内容喂给AI，它就能快速“恢复记忆”，无缝衔接。
• 版本化状态：这个状态文件可以和代码一起提交到版本控制系统（如Git）中，为AI的贡献过程提供了可追溯的审计线索。

这六个层次共同构成了一套完整的“驾驭”体系。它把与AI协作从一个随机的、基于运气的行为，转变为一个可管理、可优化、可复现的工程流程。

3. 核心工作流：从需求到代码的规格驱动开发

有了理念和层次框架，具体怎么干活？手册花了大量篇幅阐述“规格驱动开发”（Spec-Driven Development）工作流。这是将AI深度整合进敏捷开发流程的关键。

3.1 工作流四阶段

传统的“需求→代码”流程在AI时代显得粗糙。Spec-Driven Development 将其细化为一个更严谨、更适合AI参与的流程：

1. 从想法到待办项（Idea → Backlog Item）：产品想法首先被转化为结构化的待办项。手册强调Backlog作为唯一事实来源的原则。每个待办项必须有清晰的标题、描述、验收标准（Acceptance Criteria）和关联的业务价值。AI可以协助润色描述，但创建和优先级排序必须由人类（产品负责人/工程师）完成。
2. 从待办项到规格（Backlog Item → Spec）：这是最关键的一步。工程师（或与AI结对）根据待办项，编写一份详细的实现规格说明书（Spec）。这份Spec不是给经理看的PPT，而是给AI（以及后续的验证脚本）的“精确施工图”。它应包括：
   • 接口设计：具体的API路径、方法、请求/响应体示例。
   • 数据模型变更：数据库表结构、字段类型、索引。
   • 算法逻辑描述：用伪代码或清晰的自然语言描述核心业务逻辑。
   • 错误处理：可能出现的错误场景和应对策略。
   • 测试策略：需要覆盖哪些测试用例（单元、集成、端到端）。
3. 从规格到计划（Spec → Plan）：AI（在人类的引导下）阅读Spec，并生成一个具体的实施计划。这个计划应该列出：
   • 需要修改/创建的文件列表。
   • 每个文件的大致变更内容。
   • 任务依赖关系（例如，需要先创建数据库迁移脚本，才能更新服务层）。
   • 潜在风险与备选方案。 这个计划需要经过工程师的评审和批准，确保其可行性。
4. 从计划到代码（Plan → Code）：AI根据批准的Plan和详细的Spec，开始生成代码。此时，由于前期工作充分，AI的上下文非常清晰，生成代码的质量和相关性会大幅提高。工程师的角色转变为“监工”和“架构师”，专注于审查AI生成的代码是否符合Spec和Plan，而不是亲自敲每一行代码。

3.2 “门禁”（Gates）与快速路径

并非所有任务都需要走完完整的四阶段。手册引入了“门禁”（Gates）的概念，根据任务的复杂度和风险，设置不同的审查节点。

• 简单任务（如修复拼写错误、更新依赖版本）：可以走“快速路径”，直接从待办项跳到代码，由资深工程师快速审查即可。
• 中等复杂度任务（如新增一个API端点）：必须经过“Spec编写”和“Plan评审”这两个门禁。
• 高复杂度/高风险任务（如重构核心模块、引入新技术栈）：可能需要额外的门禁，如架构评审委员会（Architecture Review Board）的批准。

这种“按比例施加的仪式感”（Ceremony Proportional to Risk）确保了流程的灵活性，既不会因为流程僵化而扼杀效率，也不会因为缺乏管控而引入风险。

4. 团队协作与工程治理

将AI规模化应用到工程团队，远不止是给每个开发者安装一个Copilot插件那么简单。它涉及到工作习惯、协作模式和治理结构的深刻变化。

4.1 双模式（Dual-Mode）策略

团队的工具链是异构的：有的用Jira，有的用Linear，有的用Notion。手册提出了“双模式”策略来应对。

• 模式A：代码库即事实源：所有Spec、Plan、State文件都作为Markdown文件存放在代码仓库（如Git）中。优点是版本控制、与代码变更关联紧密、工具链简单。
• 模式B：外部工具即事实源：使用Linear、Jira或Notion来管理Backlog和Spec。此时，需要建立自动化同步机制（例如，通过GitHub Actions或Linear的Webhook），将外部工具中的任务状态和Spec内容，在AI会话开始时，自动拉取并注入到AI的上下文中。
• 关键点：无论哪种模式，都必须保证信息的单向流动和一致性。AI在会话中产生的任何计划或决策，如果需要持久化，必须被写回唯一的事实源（无论是代码库里的STATE.md还是Linear的评论），避免信息碎片化。

4.2 角色演变：从编码者到架构师与审核员

AI的引入会重塑团队内各角色的职责：

• 初级工程师：AI成为强大的导师和生产力倍增器。他们可以更专注于理解业务逻辑和架构，而AI帮助处理繁琐的语法和样板代码。他们的工作重心从“写代码”向“描述问题”和“验证结果”倾斜。
• 高级工程师/技术负责人：他们的价值将更多体现在定义高质量的Spec、设计复杂的系统交互、制定团队级的“技能”（Skills）和规范，以及进行高难度的代码审查上。他们需要判断何时使用AI、如何设置约束，并承担AI输出结果的最终责任。
• 工程经理：需要关注新的度量指标：AI辅助下的代码吞吐量、Spec的清晰度与完备性、由AI引入的缺陷率、以及团队在“驾驭”AI技能上的成熟度。他们的管理重点从监控工时转向确保流程质量和知识传承。

4.3 安全、合规与成本治理

这是企业级应用无法回避的话题。

• 安全：
  • 提示词注入（Prompt Injection）：严禁将未经审查的用户输入直接作为AI指令的一部分。所有来自外部的需求，必须经过工程师转化为结构化的、安全的Spec。
  • 权限边界：严格执行“只读智能体”原则。任何有写权限的AI操作，必须处于明确的人类监督之下，或通过受控的自动化流水线执行。
• 合规：如果项目涉及敏感数据（用户个人信息、医疗记录、支付信息），必须确保AI模型的使用符合GDPR、HIPAA、PCI-DSS等法规。这可能意味着需要使用本地部署的模型，或确保云服务提供商有相应的合规认证。AI生成的代码中，绝不能包含硬编码的密钥或真实的敏感数据。
• 成本：使用高级LLM API（如Claude 3.5 Sonnet, GPT-4）是有成本的。手册建议建立“模型分级”策略：简单的语法补全用轻量级模型（如Copilot），复杂的逻辑设计和规划用重型模型。并为团队或项目设置合理的月度API预算，防止成本失控。

5. 实战避坑指南与反模式

手册中总结的“开发者使用AI的反模式”极具价值，很多都是我们踩过的坑。

5.1 常见反模式

1. 模糊指令：“让这个页面更好看一点。” AI会陷入困惑。正确做法：“将按钮的主色改为品牌蓝色#007BFF，并将间距从8px增加到16px。”
2. 上下文不足：让AI修改一个函数，却不告诉它这个函数在哪个类、模块中，以及被谁调用。正确做法：在对话开始时，提供必要的导入语句、类定义和关键的调用示例。
3. 盲目接受：不假思索地接受AI生成的第一版代码。正确做法：带着批判性思维审查。问自己：这真的符合Spec吗？有没有更优雅的实现？边界条件处理了吗？
4. 混合多任务：在同一个对话中，要求AI修复一个bug、重构一个模块、再写一份文档。这会导致上下文污染和思维混乱。正确做法：严格遵守“隔离会话”原则，一个对话只解决一个明确的任务。
5. 放弃所有权：认为“这是AI写的代码，出了问题怪AI”。正确做法：牢记你是代码的最终负责人。AI是工具，你是工匠。工具产出有问题，责任在工匠。

5.2 何时不应该使用AI

手册也清醒地指出了AI的局限性，明确了一些不应使用AI的场景：

• 高风险的安全关键代码：如加密算法、核心身份验证逻辑的首次实现。
• 涉及深刻领域知识或复杂业务规则的创新设计：AI缺乏真正的业务理解，可能给出看似合理实则错误的方案。
• 团队核心架构决策：这需要人类基于长期经验、团队能力和技术愿景进行判断。
• 调试高度复杂、非确定性的问题：AI可能提供大量误导性的假设，反而浪费时间。此时系统性的、基于证据的人类调试更有效。
• 编写清晰、面向人类的文档：AI生成的文档往往流于表面、重复代码注释。优秀的文档需要理解读者的认知路径和真实痛点，这目前仍是人类的强项。

6. 度量与持续改进

引入Harness Engineering后，如何衡量其成功？手册建议从定量和定性两个维度建立健康度指标。

6.1 定量指标

• 开发吞吐量：完成功能点（Story Point）的平均周期时间是否缩短？注意，要对比“同类复杂度”的任务。
• 代码质量：AI参与开发的功能，其单元测试覆盖率、静态代码分析（SonarQube）问题数、生产环境缺陷率，与纯人工开发相比有何变化？
• 返工率：因需求误解或实现错误导致的代码返工比例是否下降？
• AI使用成本与收益：计算AI订阅/API成本与因效率提升节省的人力成本之间的比率（ROI）。

6.2 定性指标

• 开发者满意度：通过匿名调研，了解开发者是否感到AI减轻了他们的重复劳动，是否让他们能更专注于有挑战性的设计工作。
• Spec与代码的一致性：评审时发现代码偏离Spec的情况是否减少？
• 知识传承：新成员通过阅读AI生成的、附带详细Spec和State的代码，是否能更快上手项目？
• 技术债增长：AI的引入是加速了还是减缓了技术债的积累？

这些指标不是为了监控开发者，而是为了评估“驾驭”方法本身的有效性，并指导其持续优化。例如，如果发现“代码偏离Spec”的情况增多，可能需要加强“验证”层的自动化检查，或者改进Spec的编写培训。

我个人在团队中推行类似实践后的体会是，最大的挑战往往不是技术，而是习惯的改变。工程师们习惯了直接动手写代码，现在要求他们先花时间写一份详细的Spec，会感到“拖慢速度”。这时，需要展示一个完整的成功案例：一个通过清晰Spec驱动、由AI高效实现、一次通过评审且几乎没有缺陷的任务。当大家亲眼看到“慢在Spec，赢在全程”的效果后，阻力就会转变为动力。最终，Harness Engineering的目标不是用AI取代工程师，而是通过一套严谨的工程方法，将人类工程师的创造性和判断力，与AI强大的生成和探索能力深度融合，打造出更高效、更可靠、也更令人愉悦的软件开发新模式。这趟旅程的起点，就是改变我们与工具互动的方式，从“随意使用”转向“精心驾驭”。