前十四篇从理论到案例覆盖了 Harness Engineering 的完整知识体系。这篇做收官的事把所有内容提炼成可以立即使用的实践指南——10 步路线图、失败模式速查表、给不同角色的具体建议以及对这个领域未来的判断。一、一句话重新定义 Harness Engineering在进入路线图之前先回到最核心的那个定义。Harness Engineering 是弥合「Demo 能跑」与「生产能用」之间鸿沟的工程学科。这个类比在整个系列里反复出现Harness Engineering 之于 AI Agent正如 DevOps 之于软件部署。DevOps 出现之前代码在开发者的机器上跑得好好的上了生产就崩。不是代码写错了是缺少系统性的部署、监控、回滚、告警基础设施。Agent 现在面临同样的问题。在笔记本上演示得很好接进真实工作流就开始出各种奇怪的问题上下文腐烂、工具误用、成本失控、安全漏洞、跨会话失忆。这些问题不是模型的问题是 Harness 的问题。二、十步从零构建 Harness这是一个适合大多数 Agent 项目的构建顺序——不是所有步骤都必须但这个顺序经过了实践验证。2.1 Step 1定义 Agent 的目标和边界在写任何代码之前先回答三个问题Agent 要完成什么任务越具体越好——「帮我写代码」是目标「对 GitHub PR 做代码审查输出 Markdown 格式的审查报告重点关注安全漏洞和性能问题」是可构建的规格。Agent 不能做什么明确禁止边界——不能访问哪些目录、不能执行哪些命令、不能接触哪些数据。成功长什么样定义可验证的成功标准——测试通过率、输出格式、响应时间、成本上限。这一步通常 30 分钟就够但省掉它会导致后面所有步骤的方向跑偏。输出物一份简短的 Agent 规格文档可以是 AGENTS.md 的初始版本。2.2 Step 2设计工具集原子工具为主Shell 为后备第 5 篇的核心原则# 好的工具集设计 TOOLS [ # 原子工具单一职责清晰边界 read_file_tool, # 读文件 write_file_tool, # 写文件 search_code_tool, # 代码搜索 run_tests_tool, # 运行测试 # Shell 后备处理原子工具没覆盖的场景 bash_tool, # 通用命令执行沙箱化 ]工具描述要精简——长描述增加 Token 成本短描述一句话对大多数工具已经够了。不要过早设计太多工具。先用 3-5 个核心工具跑起来根据 Agent 实际遇到的场景再增加。2.3 Step 3构建上下文管理策略上下文是 Harness 的核心第 4 篇三个基本原则渐进式披露系统提示里只放 Agent 完成当前任务所需的信息工具文档按需加载不要把所有可能用到的内容一次性塞进去。工具输出卸载工具返回内容超过 2000 tokens卸载到文件只把摘要 文件路径放进上下文。Prompt 缓存系统提示和固定的上下文块打上cache_control标记命中缓存省 90% 成本。2.4 Step 4实现状态管理Agent 没有持久记忆状态管理是 Harness 的职责状态管理三层结构 ├── 短期对话历史当前 session 内 ├── 中期Progress Fileclaude-progress.txt跨 session └── 长期Git代码变更的完整历史也是 Agent 操作的审计日志Progress File 的内容当前任务状态、已完成的子任务列表、遇到的问题、下一步计划。Agent 每完成一个关键步骤就更新它下次启动时先读它。4.5 Step 5配置安全护栏第 7 篇的核心最小权限原则。# 命令白名单只允许这些命令 ALLOWED_COMMANDS [ python, pytest, git, grep, find, cat, ls, echo, curl ] # 目录黑名单绝对禁止写入 FORBIDDEN_PATHS [ /etc/, /usr/, ~/.ssh/, .env, credentials/ ] # 破坏性操作需要人工确认 REQUIRE_APPROVAL [ rDROP TABLE, rDELETE FROM, rrm -rf, rgit push.*--force, rgit reset.*--hard ]护栏的核心不是「防止 Agent 做坏事」是「把风险控制在可接受范围内同时不影响正常任务」。太严格的护栏会让 Agent 什么都做不了太宽松的护栏会出事故。2.6 Step 6搭建验证循环Agent 做完了什么怎么知道做对了第 8 篇的核心问题计算型验证快、可靠测试套件、Linter、类型检查、格式检查。每次 Agent 修改代码后自动运行。推理型验证慢、灵活LLM Judge——用另一个模型来评估 Agent 的输出质量。适合无法用确定性规则描述的质量标准「代码可读性」「文档清晰度」。优先用计算型。推理型只在计算型覆盖不到的地方使用。2.7 Step 7部署可观测性第 12 篇的最简实现——5 分钟接入import os os.environ[LANGFUSE_PUBLIC_KEY] pk-... os.environ[LANGFUSE_SECRET_KEY] sk-... from langfuse.decorators import observe observe() def your_agent_function(task: str) - str: # 你的 Agent 逻辑不需要任何改动 return result先把 Trace 跑起来再根据实际需要增加 Metrics 和 Logs。完美的可观测性可以等基本的 Trace 一定要有。2.8 Step 8实现长程执行对于需要运行超过 10 分钟的任务需要 Ralph Loop第 6 篇def run_long_task(task: str, feature_list_path: str): Ralph Loop自动续接直到任务完成 while True: # 读取当前状态 progress read_progress_file() feature_list read_feature_list(feature_list_path) # 检查是否全部完成 if all(f[passes] for f in feature_list): print(✓ 所有子任务完成) break # 用干净的上下文窗口运行 Agent result run_agent_iteration( tasktask, progressprogress, remaining_features[f for f in feature_list if not f[passes]] ) # 更新进度文件 update_progress_file(result) # 检查是否触发退出错误、预算上限、人工中断 if should_stop(result): break关键每次迭代用干净的上下文从文件系统读状态——不要累积上下文。2.9 Step 9优化成本第 13 篇的优先级模型路由最高杠杆给每个任务步骤配合适的模型Prompt 缓存打开cache_control立即生效子 Agent 隔离避免单一大上下文的成本膨胀工具输出卸载防止大量工具输出填满上下文成本优化不需要一次全做。先做前两个通常就能节省 60%。2.10 Step 10持续迭代Harness 不是一次性构建完的是持续改进的评估 → 改进 → 重新评估。每周 review任务完成率是否在提升成本趋势是否健康最常见的失败模式是什么把改进方向记录在 AGENTS.md 里让下一个使用这个 Harness 的人包括未来的你能看到当前设计背后的决策原因。三、常见失败模式速查表这是一张可以贴在墙上的「Agent 出问题先查这里」速查表。3.1 完成幻觉Completion Hallucination表现Agent 报告任务完成但实际上没完成。测试没跑文件没写只是声称做了。诊断查 Trace看 Agent 最后几步是否真的调用了验证工具运行测试、读文件验证。缓解在 Feature List 里要求每个子任务有可计算的passes标准Agent 必须运行验证工具不能只声明完成。3.2 上下文腐烂Context Rot表现任务开始阶段正常运行 20-30 分钟后开始给矛盾的答案或者忘记最初的任务要求。诊断查 Trace找到质量开始下降的那个 LLM 调用查看当时的完整上下文——通常已经被大量中间结果淹没原始任务描述占比极小。缓解增加 Compaction 频率60% 上下文使用率就触发每次迭代重新注入原始任务描述。3.3 过早停止Premature Termination表现Agent 在任务完成前就停下来通常说「任务完成」或「我不确定下一步该怎么做」。诊断Feature List 里看哪些子任务的passes仍然是 false。缓解Ralph Loop 拦截退出尝试强制 Agent 继续工作直到所有 Feature 通过。在系统提示里明确说明「在所有测试通过之前不要停止」。3.4 级联错误Cascading Errors表现第一步的小错误导致后续所有步骤都错最终输出完全错误但 Agent 没有意识到问题。诊断从 Trace 的开头开始逐步检查找到第一个出现偏差的步骤。缓解在关键步骤后加入验证检查点——测试必须通过才能进行下一步。把任务分解成更小的子任务每个子任务有独立的成功标准。3.5 上下文溢出Context Overflow表现Agent 报错「Context length exceeded」或者性能突然下降模型开始忽略早期上下文。诊断查 Metrics看input_tokens趋势找到快速增长的时间点。缓解工具输出卸载大输出写文件、更早触发 Compaction、子 Agent 隔离每个子任务独立上下文。3.6 工具误用Tool Misuse表现Agent 用错了工具参数路径错误、命令语法错误或者用了不该用的工具。诊断查 Trace看工具调用的参数和返回值——通常错误在参数里就能看到。缓解改善工具描述明确说明参数格式和限制加入参数验证工具执行前检查参数合理性在系统提示里给出工具使用示例。3.7 跨会话失忆Cross-Session Amnesia表现新会话开始后Agent 不知道之前做过什么重复已经完成的工作或者做出与之前决策矛盾的选择。诊断检查 Progress File 是否在上次会话结束时正确更新Agent 在新会话开始时是否读取了 Progress File。缓解强制在系统提示里包含「先读取 progress.txt 了解当前状态」的指令Progress File 在每个关键步骤后立即更新不等会话结束。3.8 范围蔓延Scope Creep表现Agent 在完成指定任务的过程中开始做额外的「改进」——重构不相关的代码、更新不在任务范围内的文档、改变没有要求修改的配置。诊断对比 git diff 和原始任务描述找出超出范围的修改。缓解在 AGENTS.md 和系统提示里明确说明「只修改任务直接要求的内容不做额外改进」。Feature List 明确划定边界Agent 不能自行添加新的 Feature。四、Harness 设计检查清单在把 Agent 推上生产前过一遍这个 Checklist4.1 目标与边界[ ] Agent 的任务目标明确且可验证[ ] 禁止操作和禁止访问区域已定义[ ] 成功标准可以计算不是主观判断4.2 工具设计[ ] 工具集覆盖核心任务场景[ ] 有 Shell 后备工具处理未预见场景[ ] 每个工具有简洁的描述一句话[ ] 沙箱配置限制工具的访问权限4.3 上下文管理[ ] 系统提示使用渐进式披露[ ] 工具输出卸载机制已实现[ ] Prompt 缓存已为固定内容打开4.4 状态管理[ ] Progress File 模式已实现[ ] Git 集成每个关键步骤 commit4.5 安全护栏[ ] 命令白名单或黑名单已配置[ ] 破坏性操作有审批门禁[ ] 敏感路径访问限制已设置4.6 验证循环[ ] 自动化测试在每次修改后运行[ ] 测试通过是继续下一步的前提条件4.7 可观测性[ ] Trace 已接入至少 Langfuse 基础配置[ ] 成本追踪已启用[ ] 预算告警已设置4.8 成本控制[ ] 模型路由已按任务复杂度配置[ ] Prompt 缓存已启用[ ] 预算硬顶已设置五、工程师角色的真实转变这个系列从第 1 篇开始就在说一件事工程师的工作正在从「写代码」变成「设计让 Agent 能安全持续写代码的环境」。说得更具体一点新技能是三个5.1 约束工程Constraint Engineering不是告诉 Agent 做什么而是设计它不能做什么——护栏、白名单、审批门禁、边界定义。设计好的约束让 Agent 在安全边界内最大化发挥能力。5.2 评估设计Evaluation Design定义「什么叫做对了」——可计算的成功标准、测试套件、LLM Judge 的评估维度。没有好的评估你无法持续改进 Harness。5.3 反馈循环设计Feedback Loop Design可观测性告诉你系统现在怎么运行评估告诉你输出质量怎么样两者合起来让你知道下一步改什么、怎么改、改了有没有用。这三个技能和「写好代码」的能力是互补的不是替代。Harness 设计越好Agent 能做的事就越多Agent 能力越强Harness 设计者的杠杆就越大。六、给不同角色的建议6.1 给刚开始接触 Agent 的开发者先跑起来一个最小的 Harness不要追求完整。选一个你真正在用的任务代码审查、文档生成、数据分析接上工具写好系统提示跑起来看结果。前三步定义目标Step 1、设计工具Step 2、接入可观测性Step 7。其他步骤根据遇到的实际问题再加。6.2 给有 Agent 开发经验的工程师你可能已经有一个「能跑」的 Agent现在想让它「生产可用」。重点看两个地方评估Step 6你有可计算的成功标准吗任务完成率是多少你能量化 Harness 改进的效果吗可观测性Step 7你能看到 Agent 在某次失败时具体哪一步出了问题吗如果不能先接 Langfuse。6.3 给做决策的团队管理者一件事投资 Harness 基础设施是最高 ROI 的决策。不是模型。模型的成本和能力都在快速变化今天押注某个模型明年可能需要迁移。Harness 基础设施——可观测性平台、评估体系、安全护栏——随着 Agent 能力提升价值只会增加不会减少。投资在「如何安全地使用 AI Agent」上而不只是「买最好的 AI Agent 服务」上。七、展望Harness Engineering 的下一步最后说三个正在发生的趋势。7.1 模型与 Harness 的紧密耦合第 10 篇讲到Codex 模型对apply_patch工具有「肌肉记忆」——这不是偶然是训练时有意为之。未来的趋势是模型训练数据会包含大量特定 Harness 环境下的高质量轨迹模型和 Harness 不再是独立的组件而是协同设计的整体。7.2 自适应 Harness现在的 Harness 是工程师手工配置的——护栏规则、工具描述、系统提示。下一步是Harness 自己观察 Agent 的运行模式自动识别失败模式自动调整配置。GEPA 算法第 12 篇提到过Hermes Agent 系列里也讲过是这个方向的早期实践。7.3 Harness as a Service不是每个团队都有资源自己构建完整的 Harness 基础设施。云端 Harness 平台正在兴起——托管的安全护栏、可观测性基础设施、评估服务按需使用。LangSmith、Galileo、Helicone 都在往这个方向走。八、系列总结三件最重要的事这个系列走完了 15 篇如果只记住三件事8.1 第一件模型之外的一切才是真正决定 Agent 生产质量的模型是 CPUHarness 是操作系统。一个 70 分的模型配上精心设计的 Harness能稳定完成复杂生产任务一个 95 分的模型没有 Harness在真实工作流里依然脆弱。8.2 第二件评估是 Harness 改进的引擎没有评估Harness 改进是猜测。有了评估你知道哪里是瓶颈改进之后能量化效果持续迭代有方向。所有在生产中稳定运行的 Agent 背后都有一套认真的评估体系。8.3 第三件从可运行到可生产核心是工程纪律Harness Engineering 不是新的魔法是把软件工程的基本原则——测试、可观测性、故障隔离、持续改进——应用到 AI Agent 这个新的执行环境上。工程纪律的基本原理没有变变的是应用场景。附1实战指南怎么搭建你的Harness1.1 第一步写好你的指令文件这是成本最低、效果最立竿见影的Harness组件。代码语言javascript1 # CLAUDE.md (或 AGENTS.md / .cursorrules) 2 3 ## 项目概述 4 本项目是一个供应链管理系统使用 Node.js React PostgreSQL。 5 6 ## 架构规则 7 - src/controllers/ 只能调用 src/services/不能直接访问 src/models/ 8 - 所有数据库操作必须通过 src/repositories/ 层 9 - 前端组件不允许直接调用 API必须通过 src/hooks/ 层 10 11 ## 编码规范 12 - 使用 TypeScript strict mode 13 - 函数名使用 camelCase类名使用 PascalCase 14 - 错误处理业务异常用自定义 AppError系统异常直接 throw 15 - 不要添加未要求的功能、注释或类型注解 16 17 ## 测试规则 18 - 每个新函数必须有对应的测试 19 - 测试文件放在 __tests__/ 目录命名为 *.test.ts 20 - 使用真实数据库连接不要 mock 21 22 ## 常见错误每条都是踩过的坑 23 - ❌ 不要在 controller 中直接写 SQL 24 - ❌ 不要使用 any 类型 25 - ❌ 不要把环境变量硬编码在代码中1.2 第二步搭建计算型传感器代码语言javascript// .claude/settings.json — 生命周期Hook配置 { hooks: { PostToolUse: [ { matcher: Write|Edit, command: npx eslint --fix $FILE npx tsc --noEmit } ], PreCommit: [ { command: npm test -- --bail } ] }每次Agent写完代码自动跑Lint和类型检查。每次提交前自动跑测试。Agent犯的错在提交之前就被拦截了。1.3 第三步建立错误→规则的反馈循环这是Harness Engineering最核心的实践代码语言javascript1 Agent犯错 2 ↓ 3 你发现了 4 ↓ 5 分析根因是缺少约束还是缺少检测 6 ↓ 7 如果是缺少约束 → 更新 CLAUDE.md 8 如果是缺少检测 → 添加 Linter规则或测试 9 ↓ 10 Agent永远不会再犯同样的错误Mitchell Hashimoto的原则每一个Agent错误都是改进Harness的机会。不要只是修复这次的错误而是要确保这类错误永远不会再发生。1.4 第四步Eval驱动开发搭建一套评估基准持续衡量Harness的效果代码语言javascript1 # 从真实失败案例中收集20-50个任务 2 # 每次修改Harness后跑一遍eval 3 # 跟踪通过率变化 4 5 eval-results/ 6 ├── baseline.json # 基线无Harness通过率62% 7 ├── v1-agents-md.json # 加了CLAUDE.md通过率78% 8 ├── v2-linter.json # 加了Linter hook通过率85% 9 ├── v3-arch-tests.json # 加了架构测试通过率91% 10 └── v4-eval-driven.json # Eval驱动迭代通过率94%参考文献Harness Engineering 实践指南——从零到生产的完整路线图Prompt Engineering已死2026年最值钱的技能叫Harness Engineering-腾讯云开发者社区-腾讯云