Harness Engineering入门基础教程（非常详细），收藏这一篇就够了！

◈什么是 Harness一个公式Agent Model Harness。模型是 Anthropic 训练的你管不了。Harness 是模型之外的一切——文件系统、工具链、沙箱、验证闭环、Hooks、压缩机制、记忆系统。你的 CLAUDE.md、settings.json、Skills、MCP 配置加在一起就是你的 Harness。如果你不是模型你就是 Harness。这不是我造的词。Anthropic 自己在工程博客里专门写过一篇《Harness Design for Long-Running Apps》讲的就是怎么用 Harness 让 Agent 完成长时间自主任务。社区里的讨论也越来越多——有人分析了一个 35000 Star 的 Agent 项目的源码结论是「整个开发流程大概率是 TDD 或者叫 Harness engineering 出来的」。还有一个很有说服力的数据同一个模型Opus 4.6仅仅通过改善 Harness就能让 benchmark 排名从 Top 30 提升到 Top 5。模型是一样的。改变的只是工作环境。◈本篇在聊什么这篇文章做三件事理清脉络——从 Prompt Engineering 到 Context Engineering 再到 Harness Engineering三代演进的区别在哪给出原则——五条可操作的 Harness 设计原则约束优于指令、TDD 优先、确定性逻辑外置、文件系统作为记忆、工具设计优先于提示词回看前六篇——你搭的那套 .claude 配置每一层对应 Harness 的哪个组件不教新命令但读完之后你看前六篇的视角会完全不同。三代演进从教模型说话到给模型搭环境AI 编程方法论经历了三代演进。不是工具在变是控制权在转移AI 编程方法论三代演进第一代Prompt Engineering — 你在教模型关注点是「怎么把提示词写得更好」。角色设定、思维链、Few-shot 示例——这些在 ChatGPT 刚出来的时候确实有用。但到了 Claude Code 这种 Agent 级别的产品你会发现 prompt 的边际收益急剧下降。「作为一名资深高级工程师请你…」和「帮我改一下这段代码」的效果差别已经很小了。第二代Context Engineering — 你在管理信息上一篇讲的内容。关注点从「怎么写 prompt」转移到「怎么管理模型能看到的全部信息」。信噪比、Prompt Caching、Compaction、HANDOFF.md。提升是量级的——同样的模型、同样的 prompt上下文管理好不好的差距是「能干」和「干不了」。第三代Harness Engineering — 你在设计系统关注点再往外扩一层不只管模型看到什么还要管模型工作的整个环境。前面已经定义过Harness 是模型之外的一切。Harness 的设计是你的事而且它的天花板比 prompt 高得多。有人总结过 AI 编程的 8 个等级从 Tab 补全到自主 Agent 团队。第 6 级就是 Harness Engineering——核心原则是「给智能体的不只是编辑器而是完整的反馈循环」。代际你在做什么典型产物Prompt Engineering写更好的提示词一个精心设计的 Prompt 模板Context Engineering优化上下文信噪比/compact 策略、HANDOFF.mdHarness Engineering设计 AI 的工作环境一套完整的 .claude 配置 Hooks Skills MCP原则 1约束优于指令这条和很多人的直觉相反。传统做法是告诉模型一步一步该做什么「先跑测试然后检查覆盖率再看有没有 lint 错误最后 commit」。模型可能忘了第三步、跳过第四步。Harness Engineering 的做法完全不同「这是我想要的结果。一直做直到通过所有这些测试。」这句话比写十条指令更有效。因为你不是在教模型怎么做它自己知道而是在告诉它什么算做完。◈Prompt 做法 vs Harness 做法的对比看几个具体场景场景提交前要通过测试❌ Prompt 做法写在对话里「请在提交代码前先跑一遍测试确保所有测试通过然后再 git commit」问题Claude 可能忘记、可能跳过、可能觉得这次改动太小不用测 plaintext ✅ Harness 做法三层叠加1. CLAUDE.md 里写 ## NEVER - Commit without running tests2. Skills 里写一个 /pre-commit --- name: pre-commit description: Run before committing code changes --- ## Steps 1. Run pnpm test 2. Run pnpm lint 3. If all pass, proceed with commit 4. If any fail, fix issues first3. Hooks 里配 { hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: if echo \$TOOL_INPUT\ | grep -q git commit; then pnpm test --silent || (echo Tests failed, commit blocked exit 2); fi }] }] } }三层的区别CLAUDE.md 声明意图 — 可能被忽略Skill 定义方法 — 可能不被调用Hook 强制兜底 — 无法绕过这就是「约束优于指令」的意思。你不是在「请求」Claude 做什么你是在用系统机制保证它不得不做。场景不能修改 .env 文件❌ Prompt 做法「请不要修改 .env 和 .env.local 文件」 → Claude 忙起来可能忘了✅ Harness 做法 settings.json permissions: deny: [Read(./.env), Read(./.env.*)] PreToolUse Hook: exit 2 阻断任何对 .env 的 Edit/Write 操作 → 系统级阻断Claude 想改也改不了场景代码风格统一❌ Prompt 做法「请用 2 空格缩进用 single quote行末不要分号」 → Claude 偶尔会忘、混用✅ Harness 做法 PostToolUse Hook 自动跑 prettier 每次 Edit 之后prettier 自动格式化 → 不管 Claude 怎么写最终结果都是统一的Claude Code 创建者 Boris Cherny 分享过团队的做法其中有一条和这个原则直接相关每次纠正 Claude 的错误后让它自己更新 CLAUDE.md——「Update your CLAUDE.md so you don’t make that mistake again」。这不是在对话里叮嘱一次而是让约束沉淀到文件系统里下次启动自动生效。Boris 说 Claude 给自己写规则写得「出奇地好」。原则 2TDD 优先——测试是最强的验证闭环很多人追求「让 Claude 一次做对」。但在工程实践中能验证比一次做对更重要。◈怎么在 Claude Code 里做 TDD具体操作第一步让 Claude 先写测试帮我给用户注册功能写测试测试以下场景1. 正常注册成功2. 邮箱已存在3. 密码强度不够4. 必填字段缺失Claude 会生成一组测试。跑一遍确认全红测试都失败因为功能还没写。第二步让 Claude 写实现跑到绿现在实现用户注册功能让所有测试通过Claude 写实现代码跑测试。如果有测试没过它会自动修。一直到所有测试变绿。第三步/simplify 重构/simplify自动审查刚改的代码检查复用性、质量和效率有问题直接修。这个流程的妙处在于你不需要检查 Claude 写的每一行实现代码。只要测试覆盖了核心场景测试全通过了实现大概率是对的。你的审查精力可以集中在测试本身——测试覆盖了该覆盖的场景吗边界条件考虑到了吗◈验证闭环的三个层级TDD 只是验证闭环的一部分。完整的验证体系分三层层级手段说明最低层命令退出码、lint、typecheck、单测自动化最快中间层集成测试、截图对比、contract test半自动化最高层人工审查、生产监控最慢但最准这个分层有人称之为回压Backpressure——类型系统、测试、linter、pre-commit 钩子把错误推回给 Agent让它自己纠正。你不需要检查它的每一行代码你需要的是一套能自动告诉它「你错了」的系统。◈什么任务适合给 Agent什么不适合有一个很好的四象限模型什么任务适合给 AgentHarness 的终极目标是把任务推向右上角——让目标明确、让验证自动化。做到了Agent 就能自主闭环。实际判断标准也很简单如果一个任务你都说不清楚「Claude 怎么才算做对了」那它大概率也不适合直接丢给 Claude 自动完成。原则 3确定性逻辑外置——我自己总结的叫法第六篇已经讲过这条原则的概念。这里给完整的对照表和实操代码你想让 Claude 做的事Prompt 做法不可靠Harness 做法可靠每次都跑测试对话里提醒PreToolUse Hook 拦截 git commit检查文件是否改了让模型自己 git diffHook 自动跑 git diff 注入消息记住用 pnpm 不用 npm每次对话都提写到 CLAUDE.md 里编辑后格式化提醒「记得跑 prettier」PostToolUse Hook 自动跑不动 .env 文件写在 prompt 里permissions deny Hook exit 2提交前更新 changelog写在规范文档里Skill Hook 联动右列比左列可靠 10 倍的原因只有一个Prompt 可能被遗忘Hooks 和 permissions 是强制执行的。◈一个混合语言项目的实际 Hook 配置如果你的项目同时用 Rust 和 TypeScript或者 Java Python、Go Lua 等任何组合可以按文件类型分发检查{ hooks:{ PostToolUse:[ { matcher:Edit, hooks:[{ type:command, command:file$(jq -r .tool_input.file_path); case \$file\ in *.rs) cargo check 21 | head -30 ;; *.ts|*.tsx) npx prettier --write \$file\ npx tsc --noEmit 21 | head -20 ;; *.py) black \$file\ ruff check \$file\ 21 | head -10 ;; esac, statusMessage:自动检查中... }] } ]}}每次编辑完立刻知道有没有错——这比「跑了一堆代码最后才发现第一行就挂了」舒服得多。实测数据在 100 次编辑的会话中每次 Hook 检查节省 30-60 秒的人工确认时间累积节省 1-2 小时。原则 4文件系统作为外部记忆模型的上下文窗口是有限的即使 1M但文件系统是无限的。Anthropic 在官方博文里总结过长任务 Agent 失败的三大原因做着做着「失忆」、目标越做越偏、看似完成其实没做完。他们的解法不是强化模型而是用文件feature list / progress log / git保存状态每轮「重新加载世界」。◈用认知科学的视角理解记忆借用认知科学的分层来理解 Claude Code 的记忆机制这不是官方架构划分是帮助你建立直觉的类比层级存储方式类比加载时机工作记忆上下文窗口大脑当前在想的实时但有限程序性记忆Skills怎么做某件事按需加载情景记忆JSONL 会话历史发生了什么--resume恢复语义记忆MEMORY.md / Auto Memory重要的事实启动时加载前 200 行这四层的设计原则是一样的尽量少放在工作记忆上下文窗口里尽量多放在文件系统里。◈跨会话续跑的最佳实践把进度放在文件里不放在上下文里方法 1写一份交接文件上一篇讲过让 Claude 写一份结构化的进度文件你可以叫它HANDOFF.md、progress.md文件名不重要新会话只读这个文件就能接着做。方法 2功能清单用 JSON 而不是 Markdown{ tasks:[ {id:1,name:用户认证,status:done}, {id:2,name:订单状态机,status:in_progress,notes:enum 方案已确认}, {id:3,name:支付回调,status:todo}]}为什么用 JSON 不用 Markdown结构化格式更适合模型稳定修改。模型改 Markdown 列表时偶尔会丢格式但改 JSON 的准确率几乎 100%。方法 3Ralph Loops续跑模式更高级的做法是让 Harness 拦截模型的退出尝试在干净上下文里重新注入原始 prompt强制继续工作。文件系统使这成为可能——每次迭代从新上下文开始但从上一轮的文件系统状态读取。这其实就是/loop命令的底层原理。原则 5工具设计优先于提示词设计有人写了 30 个 Skills读完 Anthropic 官方文章才发现基本全用错了。Claude Code 工程师 Thariq 专门写过一篇《Seeing like an Agent》讲的就是怎么给 Agent 设计工具。他的核心观点是工具要适配模型的能力而不是你觉得好用的形状。判断方法不是猜是观察模型的行为——「You learn to see like an agent」。从中可以提炼出三条可操作的原则◈三条可操作的工具设计原则原则 1观察不要猜。模型「喜不喜欢」调用某个工具就是最真实的设计反馈。如果一个工具配了 auto-invoke 但 Claude 从来不主动用它说明 description 写得不好或者这个工具不解决模型遇到的问题。原则 2定期复盘工具假设。模型能力半年一个台阶当初加的限制可能已不成立。Thariq 在原文里举了一个亲身经历早期 Claude 需要 TodoWrite 工具来记住任务列表团队甚至每 5 轮插一次系统提醒。但模型变强后这个提醒反而让 Claude 觉得必须严格按列表走无法灵活调整再后来 Opus 4.5 擅长用 subagents 了多个 subagent 又无法共享同一个 Todo 列表——于是 TodoWrite 被 Task Tool 取代核心目的从「帮模型记住目标」变成「帮多个 agent 互相协调」。As model capabilities increase, the tools that your models once needed might now be constraining them. — Thariq原则 3给地图别给百科全书。让模型自己决定要什么信息——先看到索引和导航再按需拉取细节。这就是 Skills 的references/目录和 MCP 的defer_loading做的事。◈调试工具问题的正确思路大多数工具选择错误的原因不在模型能力在工具描述不准确。调试 Agent 时应该先检查工具定义description 是否明确告诉模型「何时用我」而不是「我是干什么的」返回格式是否清晰JSON Schema 只描述类型需要示例才能教会调用方式错误信息是否教模型怎么修不只返回 error code加了示例之后工具调用准确率可以从 72% 提升到 90%。回看前六篇你一直在做 Harness Engineering这可能是整篇文章最关键的一节。看看你前六篇做的事换一个视角你一直在做 Harness Engineering每一篇文章教你的不是「怎么和 AI 聊天」而是「怎么设计 AI 的工作环境」。一套完整的 Harness 配置参考下面是一个可以直接抄的项目级 Harness 完整布局覆盖了前六篇讲的所有组件your-project/├── CLAUDE.md # 系统提示层项目契约 200 行│ ├── ## 项目概述│ ├── ## 常用命令│ ├── ## 架构边界│ ├── ## 编码规范│ └── ## NEVER 列表│├── .claude/│ ├── settings.json # 配置层│ │ ├── permissions.allow # 高频命令免确认│ │ ├── permissions.deny # 危险操作阻断│ │ ├── hooks.PostToolUse # 编辑后自动格式化/检查│ │ ├── hooks.Stop # 完成后通知│ │ └── env.ENABLE_TOOL_SEARCH # MCP 工具延迟加载│ ││ ├── rules/ # 约束层│ │ ├── code-style.md # 代码风格约束│ │ ├── testing.md # 测试规范│ │ └── api-conventions.md # API 设计规则paths: src/api/**│ ││ ├── skills/ # 工作流层│ │ ├── pre-commit/SKILL.md # 提交前检查│ │ ├── review/SKILL.md # 代码审查│ │ └── deploy/SKILL.md # 部署流程disable-model-invocation: true│ ││ └── agents/ # 隔离层│ └── explorer.md # 只读探索 AgentHaiku省成本│└── .mcp.json # 工具层团队共享的 MCP Server每一层都有明确的职责CLAUDE.md告诉 Claude「你的项目是什么」settings.json控制「Claude 怎么工作」rules/定义「什么不能做」skills/封装「怎么做特定任务」agents/隔离「需要独立上下文的工作」.mcp.json连接「外部工具和数据」自检清单你的 Harness 够好吗最后给一份自检清单11 项全做到的人不多◈基础配置☐ 有 CLAUDE.md 且不超过 200 行☐ CLAUDE.md 里有 NEVER 列表☐ settings.json 配了 allow / deny 权限规则◈能力扩展☐ 至少有 1 个自己写的 Skill不是只装了插件☐ MCP Server 按需接入开了ENABLE_TOOL_SEARCHtrue☐ 不用的 MCP Server 及时断开◈质量保障☐ 至少有 1 个 PostToolUse Hook自动格式化是最低要求☐ 重要操作有验证闭环测试、lint、typecheck☐ 高风险 Skill 设了disable-model-invocation: true◈上下文管理☐ 知道 60% / 80% 上下文的对应操作☐ 做过至少一次跨会话交接交接文件 新会话续跑做到 7 条以上你的 Harness 就比大多数人好了。做到全部 11 条你已经在做真正的 Harness Engineering。读完这篇之后做什么框架讲完了自检清单也打完了。现在的问题是具体从哪下手先做一次体检再挑一个实验动手。◈第一步给你的 Harness 做一次体检不需要很久半小时就够。做三件事找缺的层。对着前面那个完整布局参考看你的.claude/目录缺什么。大多数人的情况是有 CLAUDE.md、有 MCP但rules/是空的、hooks一条没配、自己写的 Skill 为零。这意味着你的 Harness 有系统提示层和工具层但约束层和工作流层完全缺失——Claude 能做很多事但没有任何机制保证它做对。找该下沉的。翻你最近 5 次和 Claude 的对话找出你重复说过的话。「记得跑测试」「别动 .env」「用 pnpm 不用 npm」「改完跑一下 lint」——每一条重复的提醒都是一个信号这个指令应该从对话下沉到 Harness 里。下沉到哪里频率高 必须 100% 执行 → Hook 或 Permission频率高 允许偶尔跳过 → CLAUDE.md 的 NEVER/ALWAYS 列表频率低 流程复杂 → Skill找该砍的。跑一次/context看 MCP 工具定义吃了多少 token。如果你接了 5 个 MCP Server 但日常只用 2 个其他 3 个的工具定义每次对话都在白白消耗上下文。同样检查你的 Skills 列表——有没有配了 auto-invoke 但 Claude 从来不主动调用的那就是工具描述没写好或者这个 Skill 根本不解决 Claude 遇到的问题。关掉它们把上下文还给真正有用的信息。◈第二步挑一个实验本周动手体检完你会知道自己缺什么。但别一次补完先挑一个做感受到效果再扩展。实验 1写你的第一个 Hook推荐新手先做这个如果你的 Harness 还没有任何 Hook从最简单的开始——Edit 之后自动格式化{ hooks:{ PostToolUse:[{ matcher:Edit, hooks:[{ type:command, command:npx prettier --write \$(jq -r .tool_input.file_path)\, statusMessage:格式化中... }] }]}}配完之后让 Claude 随便改几个文件你会发现不管它怎么写输出都是格式统一的。这就是确定性逻辑外置的直接体感——你再也不需要在对话里提醒「记得跑 prettier」了。实验 2做一次Prompt → Harness迁移从你的 CLAUDE.md 里找一条你写过但 Claude 偶尔忽略的规则把它迁移到 Hook 或 Permission 里。比如「不要修改 .env 文件」从 CLAUDE.md 里的文字约束改成 settings.json 里的deny: [Edit(./.env), Edit(./.env.*)]。或者前面原则 1 里那个 pre-commit Hook第一个场景直接抄过去用。然后故意不在对话里提这件事直接让 Claude 干活。你会发现它碰到被 deny 的文件会直接被系统拦截不需要你提醒。对比之前写在 CLAUDE.md 里偶尔被忽略的体验差距是肉眼可见的。实验 3做一次跨会话交接找一个正在做的任务做到一半的时候告诉 Claude把当前进度写成一份交接文件包括已完成的、正在做的、尝试过但失败的、下一步建议。写到 progress.md然后开一个全新的会话只发一句话读一下 progress.md接着做你会发现新 Claude 实例不需要任何额外解释就能继续工作。这就是文件系统作为记忆——上下文窗口会丢但文件不会。◈一个判断标准怎么知道你的 Harness 在变好有一个简单的指标你在对话里重复说的话越来越少。如果你还在每次对话开头提醒 Claude 用什么包管理器、跑什么测试命令、不能动哪些文件——说明这些知识还停留在 prompt 层没有沉淀到 Harness 里。当你发现自己只需要说「做这个功能」剩下的 Claude 自己知道怎么做、做完自动检查、格式自动统一——那就对了。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】