【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本讲是 learn-harness-engineering 课程的第二讲核心解决一个被反复误用的概念harness不是一份 prompt 文件而是模型权重之外的全部工程基础设施。文章将给出一个精确、可执行的定义——由指令、工具、环境、状态、反馈五个子系统组成的框架并结合本仓库的源码示例code/ 目录 中的对比实验、Project 01 的 starter/solution 对照工程、audit-harness.sh 审计脚本讲清楚harness 如何决定模型能力的实际发挥比例以及如何量化每个组件的边际价值。读完你将能对任意 AI 编码项目做一次完整的五元组审计并用控制变量排除法定位真正的瓶颈。从一个类比开始为什么模型很强任务还是做不好想象一位刚入职的工程师被丢进一个没有任何文档的项目里没有 README、代码里没有注释、没人告诉你怎么跑测试、CI 配置藏在某个角落。你也许还能写出好代码——如果你足够聪明又足够有耐心——但你会把大量时间花在搞清楚这个项目是怎么回事上而不是解决问题上。AI agent 面对的是同样的困境而且更糟你至少还能问同事agent 只能看到你摆在它面前的文件和它能执行的命令。它没办法拍拍同事的肩膀问这个项目用的是哪个版本的 ORM。本课程的文档引用 OpenAI 的 harness engineering 文章把核心原则概括为**仓库即规范the repo IS the spec**所有必要的上下文都应该在仓库里通过结构化的指令文件、明确的验证命令和清晰的目录组织呈现出来。Anthropic 的 long-running agents 文档则更侧重状态持久化、显式恢复路径和结构化的进度跟踪。两家公司侧重点不同但说的是同一件事模型之外的一切工程基础设施决定了模型能力能被发挥多少。这一论断在仓库里也有直接印证根目录的 CLAUDE.md 本身就是给 Claude Code 使用的指令文件提供本仓库工作时的指导它用结构化的命令、目录说明和 Key PatternsIPC 通道常量、harness 文件清单、渐进式披露等把如何在本仓库工作编码成 agent 可读的规范。几个你熟悉的工具各自的 harness 形态课程文档用厨房类比来理解现成工具注意以下对各工具的描述均引自本课程文档Claude Code是 harness 思想的体现读仓库里的CLAUDE.md配方架、能用 shell 跑命令刀具、在你的本地环境执行灶台、有会话历史备餐台、能跑测试看结果质检窗口。但如果你不告诉它怎么跑测试质检窗口就是坏的——没人知道菜到底熟了没有。Cursor逻辑类似.cursorrules是指令来源终端是工具能读项目结构和 lint 配置但状态管理相对弱关掉 IDE 再打开上次的上下文就没了。CodexOpenAI 的 coding agent用 git worktree 隔离每个任务的运行环境配合本地可观测性栈日志、指标、追踪让每个变更都在独立环境中验证它在有AGENTS.md和清晰验证命令的仓库里表现远超裸仓库。AutoGPT是反面教材缺乏结构化状态管理导致长任务中上下文不断累积缺乏精确反馈机制导致 agent 陷入循环。很多人说 AutoGPT不行但准确地说是它的harness不行——给厨师一个坏的灶台再好的食材也做不出菜。核心概念速览课程文档给出了五个关键概念作为全文的地基什么是 harness模型权重之外的一切工程基础设施。OpenAI 把工程师的核心工作概括为三件事——设计环境、表达意图、构建反馈循环Anthropic 直接把 Claude Agent SDK 称为通用 agent harness。仓库是唯一事实来源agent 看不到的东西对它来说就不存在。仓库是记录系统所有必要上下文必须通过结构化文件和清晰的目录组织落在仓库里。给地图不给说明书AGENTS.md应该是目录页content page而不是百科全书100 行左右足够放不下就拆分到docs/目录让 agent 按需读取。这正是仓库里 projects/project-01/solution/AGENTS.md 的做法——短入口文件 指向docs/ARCHITECTURE.md、docs/PRODUCT.md的链接。约束而非微操好的 harness 用可执行的规则约束 agent而不是逐条叮嘱。OpenAI 说执行不变量不要微管实现Anthropic 发现 agent 会自信地夸赞自己的工作解决方案是把干活的人和检查的人分开。逐个移除看效果想量化 harness 各组件的边际贡献就逐个移除看哪个移除后性能下降最多它既能揭示当前最有价值的组件也能暴露暂时贡献不明显的组件。Anthropic 用这个方法发现随着模型变强某些组件不再关键但总会有新的关键组件出现。Harness 五子系统模型回到厨房类比一间完整的厨房有五个功能区一个 harness 也有五个子系统。课程文档用下面的 mermaid 图描述它们的关系数据流的主干是规则与状态喂给 Agent → Agent 调用工具 → 工具运行在环境里 → 环境产生检查结果 → 检查结果反馈回 Agent。下面逐一拆解每个子系统的职责和落地文件。指令子系统配方架创建AGENTS.md或CLAUDE.md内容至少覆盖项目概览和目的一句话技术栈和版本如 Python 3.11、FastAPI 0.100、PostgreSQL 15首次运行命令make setup、make test不可违反的硬约束如所有 API 必须用 OAuth 2.0指向更详细文档的链接仓库里的范例是 projects/project-01/solution/AGENTS.md它定义了Startup Rules写任何代码前按顺序完成通读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 运行bash init.sh验证构建 → 读feature_list.json、四层 Electron 边界main/preload/renderer/services 各自的关键不变量、ConventionsTypeScript strict、命名导出、IPC 通道常量集中定义、Definition of Done5 条完成标准以及 feature list 的操作规则。这就是约束而非微操的实体样例。工具子系统刀架确保 agent 有足够的工具访问权限。不要因为安全考虑把 shell 禁掉——agent 连pip install都跑不了还怎么干活但也不要什么都开放遵循最小权限原则。课程配套的组件清单 code/harness-components.md 列出了本地仓库编码 agent 的典型 harness 构成系统 prompt、AGENTS.md、bash 工具、文件读写工具、git 访问、本地文件系统、启动脚本、测试命令、停止钩子stop hooks、lint 检查、评估器循环evaluator loop。文档特别强调你更改上述任何一个 harness 组件就改变了实际运行的 agent——模型LLM 本身是唯一不属于 harness 的部分。环境子系统灶台让环境状态自描述self-describing用pyproject.toml或package.json锁定依赖用.nvmrc或.python-version指定运行时版本用 Docker 或 devcontainer 让环境可重现本仓库的 package.json 就是环境自描述的实例devDependencies锁定了 tsx、typescript、vitepress、playwright 等版本并提供dev/build/preview/docs:dev/docs:build/lecture:runtsx等命令任何新会话都可以从npm install开始重建环境。状态子系统备餐台长任务必须有进度跟踪。课程推荐一个简单的PROGRESS.md文件记录哪些做完了、哪些在做、哪些被阻塞。每个会话结束前更新下一个会话开始时读取。仓库里的实例是 projects/project-01/solution/claude-progress.md按会话记录 Duration、Goal、What was done、Decisions、Issues、Next session——上一会话做到哪、为什么这么做、下一步做什么全部落盘下一会话据此无缝续跑。反馈子系统质检窗口这是投入产出比最高的子系统。做法是在AGENTS.md里显式列出验证命令课程文档给出的模板验证命令 - 测试pytest tests/ -x - 类型检查mypy src/ --strict - Lintruff check src/ - 完整验证make check包含以上全部反馈子系统的核心价值是让 agent 拥有知道自己做对没有的闭环。对照实验 code/harness-vs-no-harness.ts下文详解里有无验证规则的差异一目了然没有 harness 时每个任务即使存在未测的鉴权接口越界改动等问题也会被标记为 PASS有 harness 时这些缺陷会变成 BLOCKED 或 WARNING。五个子系统缺一不可五个子系统缺一个harness 就不完整agent 用起来总会别扭——就像厨房少一个功能区饭还是能勉强做出来但过程永远别扭。如何量化 harness 组件价值控制变量排除法课程给出了严谨的量化方法要点如下保持模型不变逐个移除五个子系统看哪个子系统缺失时性能下降最多下降最多的组件说明它在当前任务里的边际贡献最大值得优先保留是否加强它取决于失败归因而不是只看下降幅度几乎零影响的组件不能直接判定为无用它可能是冗余、设计失效或只是还没有被当前任务充分触发这个实验回答的是当前哪个组件最有价值不能单独证明瓶颈在哪里要真正定位瓶颈先看失败记录和归因任务没说清楚上下文不足环境不可复现验证反馈缺失还是状态管理断裂——组件拆除结果只能作为辅助证据。课程把这一方法背后的行业实践Anthropic 的移除实验发现随着模型变强某些组件不再关键但新的关键组件总会出现和失败归因优先的纪律都写进了文档这也是本仓库第 1、3、4、5、8、9 讲的内容铺垫。教学示意同一模型四阶段从 20% 到接近 100%教学示意该场景及其中的数字是为解释机制设定的不是已发表实验的实测结果。课程文档明确标注了这一点读者不应把它当作真实测评数据。一个团队用 GPT-4o 开发约 20,000 行代码的 TypeScript React 前端应用经历四个阶段——本质上是一件一件添置 harness 组件阶段做了什么成功率阶段 1空厨房只有 README 里的基本项目描述5 次运行成功 1 次20%主要失败选错包管理器npm vs yarn、没遵循组件命名约定、跑不了测试阶段 2配方架添加AGENTS.md写明技术栈版本、命名约定、关键架构决策升到 60%剩余失败主要来自环境问题和验证缺失阶段 3质检窗口在AGENTS.md列出验证命令yarn test yarn lint yarn build升到 80%阶段 4备餐台引入进度文件模板agent 每次运行记录完成与未完成的工作稳定在 80–100%四次迭代模型一个字没改成功率从 20% 到接近 100%。没有换更贵的模型只是把厨房整理好了——这正是 harness 工程的力量所在。仓库实战Project 01 对照实验starter vs solution课程文档把第二讲与 Project 01Baseline vs Minimal Harness 直接关联。这是一个真实的、可复跑的对照实验同一个任务、同一个 agent分别用弱 harness只有 prompt和显式 harness规则文件 验证机制跑一遍测量完成率差异。弱 harness 起点一个模糊的 promptstarter/task-prompt.md 故意只写一句话Build an Electron app that can show documents and answer questions.这就是纯 prompt 设置prompt-only setup的极限形态——没有 AGENTS.md、没有 feature_list.json、没有验证命令。agent 拿到它只能靠猜。显式 harness 的四个产物文件solution/ 目录则是一整套显式 harnessAGENTS.md启动规则、四层架构边界、编码约定、Definition of Done、feature list 操作规则指令子系统feature_list.json把模糊任务拆成 4 个可验证的特性window-launch、document-list、question-panel、data-directory每个都有statuspass/fail/not-started、evidence和testedAt状态子系统 可验证的完成标准{ project: project-01, description: Baseline Electron knowledge base with minimal harness, features: [ { id: window-launch, name: Window Launch, description: Electron app opens a BrowserWindow with correct dimensions and preload script, status: pass, evidence: npm run dev launches window at 1200x800 with contextIsolationtrue and nodeIntegrationfalse, testedAt: 2026-03-30T10:00:00Z } ] }init.sh会话开始前的环境验证脚本npm install→npm run check→npm run build三步确认项目是绿的环境子系统 启动钩子claude-progress.md会话日志状态子系统配套的docs/ARCHITECTURE.md和docs/PRODUCT.md分层架构图、数据流、构建管线以及产品功能与约束反馈与指令的深度支撑。项目 README 给出了具体的复跑方法先在starter/下npm install并把task-prompt.md作为 prompt 交给 Claude Code/Codex不要给 solution 文件再在solution/下npm install让 agent 先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md 再动代码最后对比三个问题——任务是否完成、需要重试几次、agent 是否提前声称完成。四个功能的对照关系starter 的源码位置 vs solution 的 feature_list.json 条目在 README 的表格里逐项列出。代码示例运行指南直观感受有 harness 与没 harness课程 code/ 目录 专门用来区分四类东西模型行为、harness 行为、纯提示词设置、有环境支撑的 agent 设置。其中有两个可直接运行的 TypeScript 示例每个语言目录下都有本文以docs/tr/路径为例。对照实验harness-vs-no-harness.ts文件 code/harness-vs-no-harness.ts 用同一组模拟任务对比两种执行器。任务列表是 5 个带有requiresAuth、hasTests、withinScope属性的任务如 Add search endpoint、Refactor auth middleware。运行方式package.json里lecture:run就是tsxnpm run lecture:run -- docs/tr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts # 或直接 npx tsx docs/tr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts无 harness 版runWithoutHarness的逻辑是agent 干完活就宣布完成passed恒为 true即使它悄悄记下了鉴权接口没有测试任务超出当前范围这类问题也不会影响通过判定。有 harness 版runWithHarness则把规则显式化requireTestsForAuth和enforceScope两条规则会把问题升级为BLOCKED: Auth-protected endpoint missing tests/BLOCKED: Task outside active scope -- skippedpassed false通过的任务若没有测试还会收到 WARNING。根据代码逻辑可以推出输出无 harness5/5 全部 PASS检测到 3 个问题假阳性 3 个通过了但实际有缺陷有 harness只有 2 个任务真正通过Add delete endpoint、Add health check3 个问题被拦截为 FAIL假阳性 0 个。脚本结尾的输出点题The harness catches problems the no-harness run silently ignores. Without a harness, every task passes even when it shouldnt.——无 harness 时每个任务都会通过哪怕它本不该通过。最小 harness 循环minimal-harness-loop.ts文件 code/minimal-harness-loop.ts 展示了一个最简 harness 的形态runTool是工具执行器目前只实现read_fileminimalHarness(messages)决定下一个动作{ tool: read_file, input: README.md }执行后把结果以 assistant 消息追加回消息列表type Message { role: user | assistant; content: string; }; type ToolResult { ok: boolean; output: string }; function runTool(name: string, input: string): ToolResult { if (name read_file) { return { ok: true, output: contents of ${input} }; } return { ok: false, output: unknown tool: ${name} }; } export function minimalHarness(messages: Message[]) { const nextAction { tool: read_file, input: README.md }; const result runTool(nextAction.tool, nextAction.input); return { messages: [ ...messages, { role: assistant, content: Tool ${nextAction.tool} returned: ${result.output}, }, ], }; }这段代码揭示了 harness 的最低形态模型之外还需要决定动作的策略 工具执行层 消息状态累积。工具调用结果被追加回上下文形成最朴素的 agent 循环——这是理解环境支撑的 agent 设置与纯 prompt差别的起点。用 audit-harness.sh 给现有仓库做五元组审计课程的核心要点之一是harness 和代码一样会腐化要定期审计。仓库为此提供了一个零依赖的审计脚本 tools/audit-harness.sh./tools/audit-harness.sh [path/to/repo]它会按五个子系统脚本注释标注对应 L03–L12 各讲逐项检查指令子系统AGENTS.md/CLAUDE.md是否存在、前 10 行是否回答系统是什么、是否列出验证命令、是否声明 MUST/MUST NOT 硬约束、入口文件是否控制在 50–200 行并链接到docs/工具子系统.claude/settings.json、MCP 配置环境子系统锁文件、.nvmrc/.python-version、Makefile状态子系统PROGRESS.md、DECISIONS.md、feature_list.json反馈子系统make check/make test、验证命令文档化以及跨会话连续性clock-in/clock-out 惯例、仓库即记录系统ACID、WIP1、feature list 状态机、防止过早宣布完成、E2E 与架构边界、可观测性、干净状态协议等。所有 CRITICAL 项通过则退出码为 0否则为 1并输出该修什么清单——它就是五元组审计方法的可执行版本。核心要点Harness 指令 工具 环境 状态 反馈五个子系统缺一不可不是模型权重的部分全是 harness你的 harness 决定了模型能力能被发挥多少五个子系统中反馈子系统通常是投入最少、回报最高的——先把验证命令写清楚用控制变量排除法量化各子系统的边际贡献定位真正瓶颈要靠失败记录和归因不能只靠拆除实验Harness 和代码一样会腐化定期审计像还技术债一样还 harness 债。关联内容与延伸阅读本讲在课程体系中的位置和延伸材料均为仓库内部路径前置第一讲为什么强大的模型仍然会失败为什么能力强的 agent 依然会失败后续第三讲为什么仓库必须成为唯一事实来源、第四讲为什么单一巨型指令文件会失败、第五讲为什么长任务会丢失连续性、第八讲为什么功能列表是 harness 原语、第十一讲为什么可观测性应该内置于 harness实战Project 01Baseline vs Minimal Harness本讲的对照实验工程另有 中文版工具tools/audit-harness.sh五元组审计脚本skills/harness-creator/SKILL.md配套的 harness 创作技能包练习Harness 五元组审计拿你正在用 AI agent 的项目按五元组框架做一次完整审计每个子系统打 1–5 分找出最低分的那一个花 30 分钟改进它然后观察 agent 表现的变化。等模型对照下的组件价值实验选一个模型和一个有挑战性的任务依次移除指令删掉 AGENTS.md、移除反馈不给验证命令、移除状态不提供进度文件——每次只移除一个测量性能下降幅度基于结果排出各子系统在当前任务里的边际价值。若要找瓶颈还必须同时记录失败日志并做原因归因。可供性分析找一个 agent 在你的项目中想做但做不了的场景比如它知道该用参数化查询但不知道你项目的 ORM 怎么写。分析这是执行鸿沟不知道怎么做还是评估鸿沟不知道做得对不对然后设计一个 harness 改进来弥补。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Harness 到底指什么用五子系统模型理解 AI 编码 Agent 的外围工程learn-harness-engineeringHarness 到底指什么用五子系统模型理解 AI 编码 Agent 的外围工程learn harness engineering 导读 harnessLearn Harness Engineering 第 2 讲Harness 到底是什么 —— 从提示词文件到五子系统工程模型Learn Harness Engineering 第 2 讲Harness 到底是什么 —— 从提示词文件到五子系统工程模型 本讲对应仓库 docs/Harness 到底是什么从五子系统模型到工程落地 —— learn-harness-engineering 第 2 课深度解读Harness 到底是什么从五子系统模型到工程落地 —— learn harness engineering 第 2 课深度解读 导读本文基于 learn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/11 3:43:02 · 阅读 1.2k Harness 到底是什么：用五子系统模型拆解 AI 编码 Agent 的工程基础设施（learn-harness-engineering 第二讲）
【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本讲是 learn-harness-engineering 课程的第二讲核心解决一个被反复误用的概念harness不是一份 prompt 文件而是模型权重之外的全部工程基础设施。文章将给出一个精确、可执行的定义——由指令、工具、环境、状态、反馈五个子系统组成的框架并结合本仓库的源码示例code/ 目录 中的对比实验、Project 01 的 starter/solution 对照工程、audit-harness.sh 审计脚本讲清楚harness 如何决定模型能力的实际发挥比例以及如何量化每个组件的边际价值。读完你将能对任意 AI 编码项目做一次完整的五元组审计并用控制变量排除法定位真正的瓶颈。从一个类比开始为什么模型很强任务还是做不好想象一位刚入职的工程师被丢进一个没有任何文档的项目里没有 README、代码里没有注释、没人告诉你怎么跑测试、CI 配置藏在某个角落。你也许还能写出好代码——如果你足够聪明又足够有耐心——但你会把大量时间花在搞清楚这个项目是怎么回事上而不是解决问题上。AI agent 面对的是同样的困境而且更糟你至少还能问同事agent 只能看到你摆在它面前的文件和它能执行的命令。它没办法拍拍同事的肩膀问这个项目用的是哪个版本的 ORM。本课程的文档引用 OpenAI 的 harness engineering 文章把核心原则概括为**仓库即规范the repo IS the spec**所有必要的上下文都应该在仓库里通过结构化的指令文件、明确的验证命令和清晰的目录组织呈现出来。Anthropic 的 long-running agents 文档则更侧重状态持久化、显式恢复路径和结构化的进度跟踪。两家公司侧重点不同但说的是同一件事模型之外的一切工程基础设施决定了模型能力能被发挥多少。这一论断在仓库里也有直接印证根目录的 CLAUDE.md 本身就是给 Claude Code 使用的指令文件提供本仓库工作时的指导它用结构化的命令、目录说明和 Key PatternsIPC 通道常量、harness 文件清单、渐进式披露等把如何在本仓库工作编码成 agent 可读的规范。几个你熟悉的工具各自的 harness 形态课程文档用厨房类比来理解现成工具注意以下对各工具的描述均引自本课程文档Claude Code是 harness 思想的体现读仓库里的CLAUDE.md配方架、能用 shell 跑命令刀具、在你的本地环境执行灶台、有会话历史备餐台、能跑测试看结果质检窗口。但如果你不告诉它怎么跑测试质检窗口就是坏的——没人知道菜到底熟了没有。Cursor逻辑类似.cursorrules是指令来源终端是工具能读项目结构和 lint 配置但状态管理相对弱关掉 IDE 再打开上次的上下文就没了。CodexOpenAI 的 coding agent用 git worktree 隔离每个任务的运行环境配合本地可观测性栈日志、指标、追踪让每个变更都在独立环境中验证它在有AGENTS.md和清晰验证命令的仓库里表现远超裸仓库。AutoGPT是反面教材缺乏结构化状态管理导致长任务中上下文不断累积缺乏精确反馈机制导致 agent 陷入循环。很多人说 AutoGPT不行但准确地说是它的harness不行——给厨师一个坏的灶台再好的食材也做不出菜。核心概念速览课程文档给出了五个关键概念作为全文的地基什么是 harness模型权重之外的一切工程基础设施。OpenAI 把工程师的核心工作概括为三件事——设计环境、表达意图、构建反馈循环Anthropic 直接把 Claude Agent SDK 称为通用 agent harness。仓库是唯一事实来源agent 看不到的东西对它来说就不存在。仓库是记录系统所有必要上下文必须通过结构化文件和清晰的目录组织落在仓库里。给地图不给说明书AGENTS.md应该是目录页content page而不是百科全书100 行左右足够放不下就拆分到docs/目录让 agent 按需读取。这正是仓库里 projects/project-01/solution/AGENTS.md 的做法——短入口文件 指向docs/ARCHITECTURE.md、docs/PRODUCT.md的链接。约束而非微操好的 harness 用可执行的规则约束 agent而不是逐条叮嘱。OpenAI 说执行不变量不要微管实现Anthropic 发现 agent 会自信地夸赞自己的工作解决方案是把干活的人和检查的人分开。逐个移除看效果想量化 harness 各组件的边际贡献就逐个移除看哪个移除后性能下降最多它既能揭示当前最有价值的组件也能暴露暂时贡献不明显的组件。Anthropic 用这个方法发现随着模型变强某些组件不再关键但总会有新的关键组件出现。Harness 五子系统模型回到厨房类比一间完整的厨房有五个功能区一个 harness 也有五个子系统。课程文档用下面的 mermaid 图描述它们的关系数据流的主干是规则与状态喂给 Agent → Agent 调用工具 → 工具运行在环境里 → 环境产生检查结果 → 检查结果反馈回 Agent。下面逐一拆解每个子系统的职责和落地文件。指令子系统配方架创建AGENTS.md或CLAUDE.md内容至少覆盖项目概览和目的一句话技术栈和版本如 Python 3.11、FastAPI 0.100、PostgreSQL 15首次运行命令make setup、make test不可违反的硬约束如所有 API 必须用 OAuth 2.0指向更详细文档的链接仓库里的范例是 projects/project-01/solution/AGENTS.md它定义了Startup Rules写任何代码前按顺序完成通读本文件 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 运行bash init.sh验证构建 → 读feature_list.json、四层 Electron 边界main/preload/renderer/services 各自的关键不变量、ConventionsTypeScript strict、命名导出、IPC 通道常量集中定义、Definition of Done5 条完成标准以及 feature list 的操作规则。这就是约束而非微操的实体样例。工具子系统刀架确保 agent 有足够的工具访问权限。不要因为安全考虑把 shell 禁掉——agent 连pip install都跑不了还怎么干活但也不要什么都开放遵循最小权限原则。课程配套的组件清单 code/harness-components.md 列出了本地仓库编码 agent 的典型 harness 构成系统 prompt、AGENTS.md、bash 工具、文件读写工具、git 访问、本地文件系统、启动脚本、测试命令、停止钩子stop hooks、lint 检查、评估器循环evaluator loop。文档特别强调你更改上述任何一个 harness 组件就改变了实际运行的 agent——模型LLM 本身是唯一不属于 harness 的部分。环境子系统灶台让环境状态自描述self-describing用pyproject.toml或package.json锁定依赖用.nvmrc或.python-version指定运行时版本用 Docker 或 devcontainer 让环境可重现本仓库的 package.json 就是环境自描述的实例devDependencies锁定了 tsx、typescript、vitepress、playwright 等版本并提供dev/build/preview/docs:dev/docs:build/lecture:runtsx等命令任何新会话都可以从npm install开始重建环境。状态子系统备餐台长任务必须有进度跟踪。课程推荐一个简单的PROGRESS.md文件记录哪些做完了、哪些在做、哪些被阻塞。每个会话结束前更新下一个会话开始时读取。仓库里的实例是 projects/project-01/solution/claude-progress.md按会话记录 Duration、Goal、What was done、Decisions、Issues、Next session——上一会话做到哪、为什么这么做、下一步做什么全部落盘下一会话据此无缝续跑。反馈子系统质检窗口这是投入产出比最高的子系统。做法是在AGENTS.md里显式列出验证命令课程文档给出的模板验证命令 - 测试pytest tests/ -x - 类型检查mypy src/ --strict - Lintruff check src/ - 完整验证make check包含以上全部反馈子系统的核心价值是让 agent 拥有知道自己做对没有的闭环。对照实验 code/harness-vs-no-harness.ts下文详解里有无验证规则的差异一目了然没有 harness 时每个任务即使存在未测的鉴权接口越界改动等问题也会被标记为 PASS有 harness 时这些缺陷会变成 BLOCKED 或 WARNING。五个子系统缺一不可五个子系统缺一个harness 就不完整agent 用起来总会别扭——就像厨房少一个功能区饭还是能勉强做出来但过程永远别扭。如何量化 harness 组件价值控制变量排除法课程给出了严谨的量化方法要点如下保持模型不变逐个移除五个子系统看哪个子系统缺失时性能下降最多下降最多的组件说明它在当前任务里的边际贡献最大值得优先保留是否加强它取决于失败归因而不是只看下降幅度几乎零影响的组件不能直接判定为无用它可能是冗余、设计失效或只是还没有被当前任务充分触发这个实验回答的是当前哪个组件最有价值不能单独证明瓶颈在哪里要真正定位瓶颈先看失败记录和归因任务没说清楚上下文不足环境不可复现验证反馈缺失还是状态管理断裂——组件拆除结果只能作为辅助证据。课程把这一方法背后的行业实践Anthropic 的移除实验发现随着模型变强某些组件不再关键但新的关键组件总会出现和失败归因优先的纪律都写进了文档这也是本仓库第 1、3、4、5、8、9 讲的内容铺垫。教学示意同一模型四阶段从 20% 到接近 100%教学示意该场景及其中的数字是为解释机制设定的不是已发表实验的实测结果。课程文档明确标注了这一点读者不应把它当作真实测评数据。一个团队用 GPT-4o 开发约 20,000 行代码的 TypeScript React 前端应用经历四个阶段——本质上是一件一件添置 harness 组件阶段做了什么成功率阶段 1空厨房只有 README 里的基本项目描述5 次运行成功 1 次20%主要失败选错包管理器npm vs yarn、没遵循组件命名约定、跑不了测试阶段 2配方架添加AGENTS.md写明技术栈版本、命名约定、关键架构决策升到 60%剩余失败主要来自环境问题和验证缺失阶段 3质检窗口在AGENTS.md列出验证命令yarn test yarn lint yarn build升到 80%阶段 4备餐台引入进度文件模板agent 每次运行记录完成与未完成的工作稳定在 80–100%四次迭代模型一个字没改成功率从 20% 到接近 100%。没有换更贵的模型只是把厨房整理好了——这正是 harness 工程的力量所在。仓库实战Project 01 对照实验starter vs solution课程文档把第二讲与 Project 01Baseline vs Minimal Harness 直接关联。这是一个真实的、可复跑的对照实验同一个任务、同一个 agent分别用弱 harness只有 prompt和显式 harness规则文件 验证机制跑一遍测量完成率差异。弱 harness 起点一个模糊的 promptstarter/task-prompt.md 故意只写一句话Build an Electron app that can show documents and answer questions.这就是纯 prompt 设置prompt-only setup的极限形态——没有 AGENTS.md、没有 feature_list.json、没有验证命令。agent 拿到它只能靠猜。显式 harness 的四个产物文件solution/ 目录则是一整套显式 harnessAGENTS.md启动规则、四层架构边界、编码约定、Definition of Done、feature list 操作规则指令子系统feature_list.json把模糊任务拆成 4 个可验证的特性window-launch、document-list、question-panel、data-directory每个都有statuspass/fail/not-started、evidence和testedAt状态子系统 可验证的完成标准{ project: project-01, description: Baseline Electron knowledge base with minimal harness, features: [ { id: window-launch, name: Window Launch, description: Electron app opens a BrowserWindow with correct dimensions and preload script, status: pass, evidence: npm run dev launches window at 1200x800 with contextIsolationtrue and nodeIntegrationfalse, testedAt: 2026-03-30T10:00:00Z } ] }init.sh会话开始前的环境验证脚本npm install→npm run check→npm run build三步确认项目是绿的环境子系统 启动钩子claude-progress.md会话日志状态子系统配套的docs/ARCHITECTURE.md和docs/PRODUCT.md分层架构图、数据流、构建管线以及产品功能与约束反馈与指令的深度支撑。项目 README 给出了具体的复跑方法先在starter/下npm install并把task-prompt.md作为 prompt 交给 Claude Code/Codex不要给 solution 文件再在solution/下npm install让 agent 先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md 再动代码最后对比三个问题——任务是否完成、需要重试几次、agent 是否提前声称完成。四个功能的对照关系starter 的源码位置 vs solution 的 feature_list.json 条目在 README 的表格里逐项列出。代码示例运行指南直观感受有 harness 与没 harness课程 code/ 目录 专门用来区分四类东西模型行为、harness 行为、纯提示词设置、有环境支撑的 agent 设置。其中有两个可直接运行的 TypeScript 示例每个语言目录下都有本文以docs/tr/路径为例。对照实验harness-vs-no-harness.ts文件 code/harness-vs-no-harness.ts 用同一组模拟任务对比两种执行器。任务列表是 5 个带有requiresAuth、hasTests、withinScope属性的任务如 Add search endpoint、Refactor auth middleware。运行方式package.json里lecture:run就是tsxnpm run lecture:run -- docs/tr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts # 或直接 npx tsx docs/tr/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts无 harness 版runWithoutHarness的逻辑是agent 干完活就宣布完成passed恒为 true即使它悄悄记下了鉴权接口没有测试任务超出当前范围这类问题也不会影响通过判定。有 harness 版runWithHarness则把规则显式化requireTestsForAuth和enforceScope两条规则会把问题升级为BLOCKED: Auth-protected endpoint missing tests/BLOCKED: Task outside active scope -- skippedpassed false通过的任务若没有测试还会收到 WARNING。根据代码逻辑可以推出输出无 harness5/5 全部 PASS检测到 3 个问题假阳性 3 个通过了但实际有缺陷有 harness只有 2 个任务真正通过Add delete endpoint、Add health check3 个问题被拦截为 FAIL假阳性 0 个。脚本结尾的输出点题The harness catches problems the no-harness run silently ignores. Without a harness, every task passes even when it shouldnt.——无 harness 时每个任务都会通过哪怕它本不该通过。最小 harness 循环minimal-harness-loop.ts文件 code/minimal-harness-loop.ts 展示了一个最简 harness 的形态runTool是工具执行器目前只实现read_fileminimalHarness(messages)决定下一个动作{ tool: read_file, input: README.md }执行后把结果以 assistant 消息追加回消息列表type Message { role: user | assistant; content: string; }; type ToolResult { ok: boolean; output: string }; function runTool(name: string, input: string): ToolResult { if (name read_file) { return { ok: true, output: contents of ${input} }; } return { ok: false, output: unknown tool: ${name} }; } export function minimalHarness(messages: Message[]) { const nextAction { tool: read_file, input: README.md }; const result runTool(nextAction.tool, nextAction.input); return { messages: [ ...messages, { role: assistant, content: Tool ${nextAction.tool} returned: ${result.output}, }, ], }; }这段代码揭示了 harness 的最低形态模型之外还需要决定动作的策略 工具执行层 消息状态累积。工具调用结果被追加回上下文形成最朴素的 agent 循环——这是理解环境支撑的 agent 设置与纯 prompt差别的起点。用 audit-harness.sh 给现有仓库做五元组审计课程的核心要点之一是harness 和代码一样会腐化要定期审计。仓库为此提供了一个零依赖的审计脚本 tools/audit-harness.sh./tools/audit-harness.sh [path/to/repo]它会按五个子系统脚本注释标注对应 L03–L12 各讲逐项检查指令子系统AGENTS.md/CLAUDE.md是否存在、前 10 行是否回答系统是什么、是否列出验证命令、是否声明 MUST/MUST NOT 硬约束、入口文件是否控制在 50–200 行并链接到docs/工具子系统.claude/settings.json、MCP 配置环境子系统锁文件、.nvmrc/.python-version、Makefile状态子系统PROGRESS.md、DECISIONS.md、feature_list.json反馈子系统make check/make test、验证命令文档化以及跨会话连续性clock-in/clock-out 惯例、仓库即记录系统ACID、WIP1、feature list 状态机、防止过早宣布完成、E2E 与架构边界、可观测性、干净状态协议等。所有 CRITICAL 项通过则退出码为 0否则为 1并输出该修什么清单——它就是五元组审计方法的可执行版本。核心要点Harness 指令 工具 环境 状态 反馈五个子系统缺一不可不是模型权重的部分全是 harness你的 harness 决定了模型能力能被发挥多少五个子系统中反馈子系统通常是投入最少、回报最高的——先把验证命令写清楚用控制变量排除法量化各子系统的边际贡献定位真正瓶颈要靠失败记录和归因不能只靠拆除实验Harness 和代码一样会腐化定期审计像还技术债一样还 harness 债。关联内容与延伸阅读本讲在课程体系中的位置和延伸材料均为仓库内部路径前置第一讲为什么强大的模型仍然会失败为什么能力强的 agent 依然会失败后续第三讲为什么仓库必须成为唯一事实来源、第四讲为什么单一巨型指令文件会失败、第五讲为什么长任务会丢失连续性、第八讲为什么功能列表是 harness 原语、第十一讲为什么可观测性应该内置于 harness实战Project 01Baseline vs Minimal Harness本讲的对照实验工程另有 中文版工具tools/audit-harness.sh五元组审计脚本skills/harness-creator/SKILL.md配套的 harness 创作技能包练习Harness 五元组审计拿你正在用 AI agent 的项目按五元组框架做一次完整审计每个子系统打 1–5 分找出最低分的那一个花 30 分钟改进它然后观察 agent 表现的变化。等模型对照下的组件价值实验选一个模型和一个有挑战性的任务依次移除指令删掉 AGENTS.md、移除反馈不给验证命令、移除状态不提供进度文件——每次只移除一个测量性能下降幅度基于结果排出各子系统在当前任务里的边际价值。若要找瓶颈还必须同时记录失败日志并做原因归因。可供性分析找一个 agent 在你的项目中想做但做不了的场景比如它知道该用参数化查询但不知道你项目的 ORM 怎么写。分析这是执行鸿沟不知道怎么做还是评估鸿沟不知道做得对不对然后设计一个 harness 改进来弥补。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Harness 到底指什么用五子系统模型理解 AI 编码 Agent 的外围工程learn-harness-engineeringHarness 到底指什么用五子系统模型理解 AI 编码 Agent 的外围工程learn harness engineering 导读 harnessLearn Harness Engineering 第 2 讲Harness 到底是什么 —— 从提示词文件到五子系统工程模型Learn Harness Engineering 第 2 讲Harness 到底是什么 —— 从提示词文件到五子系统工程模型 本讲对应仓库 docs/Harness 到底是什么从五子系统模型到工程落地 —— learn-harness-engineering 第 2 课深度解读Harness 到底是什么从五子系统模型到工程落地 —— learn harness engineering 第 2 课深度解读 导读本文基于 learn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考