为什么要谈 Harness Engineering这两年团队里关于 AI 的讨论很多但真正落到研发现场问题往往很具体为什么 AI 有时看起来很能干有时又完全不靠谱为什么它能写出一段像样的代码却经常交不出一个可验证的结果为什么同一个任务换个人问、换种说法结果差异会这么大如果把 AI 只当成一个“更会说话的搜索框”这些问题几乎无解。因为问题不只出在模型本身更出在我们给它的工作环境太松散任务定义不清、上下文不完整、工具边界不明确、验证机制缺失最后只能得到一个“像完成了”的回答。Harness Engineering 想解决的正是这类问题。它不是某种新奇技巧也不只是把 prompt 写得更复杂。更准确地说它是一套把 AI 纳入工程流程的方法给任务加边界给执行加路径给结果加验证给经验加沉淀。一句话概括Harness Engineering 关注的不是“AI 会不会回答”而是“AI 能不能稳定交付”。二、什么是 Harness Engineering可以把 Harness Engineering 理解成给 AI 搭一套“任务运行框架”。在这套框架里AI 不再只是被动响应问题而是要在明确目标、范围、上下文、工具和验收标准的前提下完成任务。它的关注点不是模型的单次表现而是整个执行链路是否可控任务有没有被定义清楚项目背景有没有被准确提供AI 能调用哪些工具边界在哪里执行是否遵循固定流程结果有没有经过真实验证成功经验能不能复用所以AI 是执行者Harness 是执行环境。没有 HarnessAI 更像一次临场发挥有了 HarnessAI 才有可能成为工程流程里稳定的一环。三、它和 Prompt Engineering 到底差在哪Prompt Engineering 当然重要但它解决的主要是“怎么问”。Harness Engineering 解决的是另一层问题“当问题已经提出后AI 应该在什么环境里、按什么方式、用什么工具、经过哪些检查把事情做完。”两者的区别可以放在一张表里看维度Prompt EngineeringHarness Engineering关注点优化模型输入设计 AI 的执行环境核心目标提高回答质量提高任务交付稳定性主要手段Prompt 模板、上下文组织任务定义、工具、流程、验证、沉淀输出更好的文本结果可执行且可验证的工程结果失败后的处理继续改 prompt复现、诊断、修复、重试典型场景问答、生成、摘要编码、调试、评审、自动化更简洁一点说Prompt Engineering 解决“表达问题”。Harness Engineering 解决“交付问题”。用户目标Prompt Engineering优化提问方式Harness Engineering设计执行环境更好的回答可执行任务流工具调用验证与反馈可交付结果团队真正需要的通常不是一个更会“说”的 AI而是一个更会“做”的 AI。四、一个不带 Harness 的 AI通常会怎么失手这件事在工程里很常见。比如我们给 AI 一个任务“帮我实现登录功能。”这句话看起来没问题但实际缺了太多关键约束登录是账号密码、SSO还是短信验证码允许改哪些目录需不需要兼容旧接口是否允许改数据库前后端分别在哪里验收标准是什么需要跑哪些测试于是 AI 往往会陷入一种典型状态能写代码但不确定是不是该这么写能输出方案但没有依据现有项目结构能给出结论但没有真实验证能说“完成了”但没有留下可复查的证据这并不是模型“笨”而是任务环境没有工程化。Harness Engineering 的价值就是把这些本来靠经验补齐的隐含条件变成显式结构。五、Harness Engineering 的核心组成在实际工程里Harness Engineering 可以拆成七个部分。它们合在一起构成了 AI 的执行框架。5.1 Task Harness先把任务定义成可执行规格AI 并不怕复杂任务它更怕模糊任务。相比“帮我实现登录功能”下面这种写法明显更适合执行目标 - 实现用户登录功能 范围 - 只修改 backend/auth 和 frontend/login 相关代码 - 不修改数据库 schema除非需求明确提出 输入 - 项目路径 - 登录接口文档 - UI 设计稿 输出 - 可运行代码 - 测试用例 - 变更说明 约束 - 复用现有 auth middleware - 不引入新的状态管理库 - 保持向后兼容 验收标准 - 单元测试通过 - e2e 登录流程通过 - 错误密码返回 401 - 登录成功后跳转 dashboard好的任务定义至少要回答六件事做什么改哪里参考什么不能做什么交付什么怎么算完成任务一旦被定义成“规格”AI 的行为就更容易收敛执行结果也更稳定。5.2 Context Harness别让 AI 靠猜理解项目真实工程里任务本身通常只占问题的一半另一半是上下文。如果没有上下文AI 只能根据经验做“平均化推断”这也是很多结果看上去合理、落到项目里却不合适的原因。常见上下文包括项目目录结构技术栈和关键依赖模块边界代码规范测试命令历史设计文档CI 日志和报错信息业务约束和兼容性要求项目里最好有一些稳定的上下文载体比如AGENTS.mdREADME.mddocs/设计文档测试脚本与 CI 配置例如一个简单但有效的AGENTS.md可以是这样# Agent Instructions ## Tech Stack - Backend: FastAPI - Frontend: React Vite - Database: PostgreSQL - Tests: pytest, playwright ## Rules - Do not change public API without updating docs. - Always run uv run pytest before finishing backend changes. - Prefer small, focused commits. - Do not add dependencies unless necessary. ## Useful Commands - Backend tests: uv run pytest - Frontend tests: npm test - Type check: npm run typecheck这类文件的意义并不在于“写文档”而在于把原本只存在于资深开发者脑子里的默认规则变成 AI 可以直接消费的工程上下文。5.3 Tool Harness工具要给边界也要给如果 AI 只能输出文本它很难真正完成工程任务。它至少需要一些基本能力读写文件搜索代码修改代码运行测试查看日志执行脚本查看 diff调用浏览器或接口但工程里另一个常见误区是只想着“让 AI 能做更多”却忽略“让 AI 不能乱做”。所以 Tool Harness 的关键不是工具数量而是权限边界。比如允许 - 读取项目文件 - 修改 src/ 和 tests/ - 运行 pytest - 运行 npm test - 查看 git diff 禁止 - 删除数据库 - 强制 push - 修改 secrets - 直接部署生产环境 - 未经确认安装系统级依赖工具的本质是执行能力边界的本质是风险控制。两者必须同时存在。5.4 Execution Harness让执行过程有固定路径很多 AI 任务失败并不是因为它不会写而是因为它执行顺序错了。功能开发任务通常至少应该经过下面这条路径理解任务检查项目结构定位相关代码阅读现有实现制定计划修改代码添加或更新测试运行验证命令修复失败项总结变更和结果是否理解任务检查项目结构定位相关代码阅读现有实现制定计划修改代码补充或更新测试运行验证命令验证通过?整理变更说明定位失败原因不同任务可以有不同流程Bug 修复强调先复现、再定位、再回归验证重构强调先保护行为、再渐进修改、再持续回归代码评审强调证据指向、风险分级和结论可复查但无论是哪类任务最怕的都是“想到哪做到哪”。Execution Harness 的意义就是把执行方式从临场发挥变成标准路径。5.5 Verification Harness没有验证就没有完成这是整个方法里最关键的一环。工程任务最大的误区之一是把“生成了结果”和“完成了任务”混为一谈。对 AI 来说更是如此它很容易写出一个看起来正确的答案但这不等于结果真的可用。一个合格的交付应该附带真实验证记录例如已执行 - uv run pytest tests/auth - npm run typecheck - npm run test:e2e login.spec.ts 结果 - 42 tests passed - typecheck passed - login e2e passed如果没有验证成功也应该明确说明未能完成验证 - npm test 失败 - 原因缺少 node_modules - 已尝试安装依赖但当前环境网络不可用 - 已完成代码修改尚未完成运行验证团队要建立一个共识AI 的“我完成了”没有价值测试、构建、类型检查和回归结果才有价值。5.6 Memory / Skill Harness把成功做法沉淀下来如果某类任务反复出现就不该每次从零开始组织输入。例如这些高频场景修 API bug做代码评审写技术方案修 CI生成测试排查线上问题准备 PR 描述对于这类任务更合理的做法是把成功路径沉淀成可复用资产SkillPlaybookChecklist模板自动化脚本例如“修复后端接口 bug”可以固化成下面这样# Playbook: 修复后端接口 bug ## 触发条件 - 用户要求修复 API bug - 测试失败 - 接口返回异常 ## 步骤 1. 读取错误日志 2. 找到对应 endpoint 3. 阅读测试与 schema 4. 复现问题 5. 添加回归测试 6. 修改实现 7. 运行相关测试 8. 输出根因、改动点和验证结果 ## 禁忌 - 不要直接删除失败测试 - 不要通过修改测试绕开问题 - 不要在需求不明确时修改公共 API当流程能沉淀下来团队依赖的就不再是谁“更会提问”而是谁把方法做成了标准资产。5.7 Feedback Harness把一次任务变成可迭代闭环工程任务很少一次就完全正确。代码评审、CI、集成测试和人工验收都会构成下一轮输入。成熟的 AI 使用方式应该是一个闭环是否任务输入AI 执行测试 / CI / Review是否通过交付结果反馈问题修复与重试沉淀为 Skill / Playbook这个闭环至少有两个价值让 AI 的输出持续被校正而不是一次性拍板让每次任务不只产出结果也顺手改进下一次任务的执行方式六、在实际工程里应该怎么用如果要把 Harness Engineering 用到日常研发中最有效的方式不是先讲概念而是直接放进具体场景里。6.1 场景一功能开发相比一句“帮我实现支付功能”更好的写法是任务 实现 Stripe Checkout 支付流程。 范围 - 后端新增 checkout session API - 前端新增支付按钮 - 不处理订阅只处理一次性付款 上下文 - 后端位于 backend/ - 前端位于 frontend/ - 当前认证用户可从 request.user 获取 - Stripe secret 从环境变量 STRIPE_SECRET_KEY 读取 约束 - 不要把 secret 写入代码 - 不要修改现有订单表结构 - 不要引入新的前端状态管理库 验收标准 - 后端测试覆盖 checkout session 创建 - 前端测试覆盖按钮点击 - 类型检查通过 - 输出实际执行过的测试命令和结果 执行要求 1. 先检查项目结构 2. 找到 payment/order 相关代码 3. 制定简短计划 4. 实现功能 5. 添加测试 6. 运行验证 7. 总结变更与结果这种写法并不复杂但它把原本隐含在提问者脑子里的关键信息全都显式化了。6.2 场景二Bug 修复Bug 修复任务的关键不只是“改掉错误”而是先形成一个可复现、可回归的闭环。任务 修复登录接口在密码错误时返回 500 的问题。 已知现象 - POST /api/login - 输入错误密码 - 期望返回 401 - 实际返回 500 要求 1. 先复现问题 2. 找到根因 3. 添加回归测试 4. 修复实现 5. 运行相关测试 6. 输出 - 根因 - 修改文件 - 测试结果这里真正重要的是AI 不是“猜测修法”而是“围绕证据修复问题”。6.3 场景三代码评审代码评审特别适合 Harness 化因为它天然要求结构化输出。任务 评审当前分支相对于 main 的代码变更。 重点关注 - 安全问题 - 并发问题 - API 兼容性 - 测试覆盖 - 错误处理 - 是否引入不必要依赖 不要关注 - 轻微格式问题 - 主观命名偏好 输出格式 1. 总体结论 2. 高风险问题 3. 中风险问题 4. 低风险建议 5. 必须修改项 6. 可选优化项 要求 - 每个问题都指出具体文件和原因 - 不确定的地方明确标注“不确定” - 不要编造不存在的代码这样一来AI 的工作重点会落在“找证据、分风险、给结论”而不是写一段模糊的评语。6.4 场景四技术方案与设计文档方案写作类任务最容易出现“字很多、信息很少”的问题。Harness 的作用是强制它围绕评审逻辑组织内容。任务 为订单系统重构写一份技术方案。 背景 - 当前订单状态散落在多个服务中 - 经常出现状态不一致 - 需要统一订单状态机 方案需要包含 - 当前问题 - 目标 - 非目标 - 方案选项 - 推荐方案 - 数据模型 - API 变化 - 迁移计划 - 风险 - 回滚方案 - 验收标准 文风 - 技术评审文档风格 - 结论明确 - 避免空泛表达方案类任务不是让 AI “写得多”而是让它“写得可评审”。七、一个团队里最值得先做的模板如果团队要开始落地 Harness Engineering第一步不是追求复杂系统而是先把高频任务的输入模板标准化。下面这份模板就足够实用# AI Engineering Task Harness ## Role 你是当前项目的工程代理。你的目标不是只给建议而是完成可验证的工程结果。 ## Task 描述要完成的任务。 ## Background 补充背景、业务目标、已知问题、相关上下文。 ## Scope 允许修改 - 不允许修改 - ## Inputs - 项目路径 - 相关文件 - 相关文档 - 错误日志 - 设计稿 / API 文档 ## Constraints - - - ## Expected Output - 代码变更 - 测试 - 文档 - PR 描述 - 验证结果 ## Acceptance Criteria - - - ## Required Workflow 1. 检查项目结构和相关文件 2. 阅读现有实现 3. 制定简短计划 4. 小步修改 5. 添加或更新测试 6. 运行验证命令 7. 修复失败 8. 输出最终总结 ## Verification 必须实际执行以下命令并报告真实结果 bash # example npm test npm run typecheck uv run pytest ## Final Response Format 1. 完成了什么 2. 修改了哪些文件 3. 如何验证 4. 测试结果 5. 已知限制 6. 建议下一步任务模板输入角色与任务范围与约束上下文与输入执行流程工具执行验证结果最终交付模板的价值不在于形式而在于它帮团队建立了一种共同语言什么叫任务说清楚什么叫上下文给够什么叫真正完成。八、团队落地时建议按这个顺序推进如果要在团队里真正用起来建议不要一上来做“大而全”的平台化建设而是按下面的顺序逐步推进。第一步在项目根目录放一份AGENTS.md先把最基础、最常用的项目信息稳定下来例如项目概览架构简介编码规则测试命令常见工作流禁止操作评审清单这一步解决的是“AI 每次进项目都像第一次来”的问题。第二步为高频任务建立 Playbook优先整理三到五类最常见的任务比如fix-bug.mdimplement-feature.mdcode-review.mdwrite-design-doc.mddebug-ci.md每个 Playbook 都尽量回答这些问题什么时候使用需要哪些输入按什么流程执行如何验证产出格式是什么常见坑有哪些这一步解决的是“同一类任务每次都重新组织一遍”的问题。第三步为改动类型定义验证矩阵不同类型的改动最低验证要求应该明确而不是靠操作者自行判断。改动类型最低验证要求Backend 逻辑变更uv run pytest、静态检查Frontend 页面变更npm test、npm run typecheckAPI 变更接口测试、兼容性检查、文档同步DB migration迁移验证、回滚验证配置变更启动验证、关键路径 smoke test这一步解决的是“写完了”和“验证通过了”经常被混为一谈的问题。第四步按风险分层开放权限并不是所有动作都应该自动化。团队最好提前约定哪些是低风险、哪些必须人工确认。AI 执行权限低风险中风险高风险读代码写文档生成测试修改业务代码修改配置安装项目依赖数据库迁移删除文件部署生产环境修改权限与密钥高风险操作最好保留人工确认这不是保守而是工程纪律。第五步把成功经验沉淀成组织资产当某条流程已经被反复验证就应该把它沉淀下来而不是继续依赖“谁更会写 prompt”。组织资产可以是SkillPlaybook模板自动化脚本CI 检查项走到这一步团队对 AI 的使用方式就不再是零散技巧而开始具备工程能力。九、一个成熟的 AI 工程任务应该长什么样一个成熟的 AI 任务不一定复杂但通常具备这些特征目标清晰范围明确上下文充分工具受控流程固定结果可验证失败可诊断方法可复用如果这些条件基本齐备AI 在团队里的角色就会发生变化它不再只是一个“问答助手”而更像一个被纳入流程管理的执行单元。下面这张图可以概括一个成熟任务的完整链路否是明确任务目标补充上下文限定范围与约束选择工具与权限按标准流程执行测试与验证是否达标反馈与修正交付结果沉淀为 Playbook / Skill这个链路里真正重要的不是每个环节都做得很重而是环节本身不能缺。十、如果现在就开始最小可行方案是什么如果团队今天就想试不需要先建设一整套平台。一个足够实用的最小版本只需要先做五件事在项目根目录写一份AGENTS.md为“功能开发 / Bug 修复 / 代码评审”各准备一个模板明确每类改动必须执行的验证命令要求 AI 输出真实执行结果而不是口头总结把重复验证过的流程沉淀为 Skill 或 Playbook从实践角度看Harness Engineering 真正落地看的不是概念是否完整而是下面这些事情有没有发生任务是否被说清楚上下文是否被补齐风险边界是否明确AI 是否真正执行结果是否经过验证成功经验是否得到复用只要这几件事开始稳定发生团队其实就已经走在 Harness Engineering 的路上了。十一、结语Harness Engineering 的价值不在于提出了一个新名词而在于它把 AI 的使用方式从“偶尔有帮助的生成工具”推进成“可以纳入工程流程的执行能力”。它要求我们不再只关注 AI 说得像不像而是去看任务定义是否清楚执行过程是否受控输出结果是否可验证
