【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载“harness约束框架”是 AI 编程 Agent 讨论中被滥用最多的词之一多数人说起 harness 时指的只是一个 prompt 文件但一个 prompt 文件并不是 harness。本篇文章以 learn-harness-engineering 仓库第二讲Lecture 02: What a Harness Actually Is及配套组件清单文档code/harness-components.md为核心给出 harness 的精确定义、五个子系统的职责划分、可量化的评估方法并结合仓库中的 TypeScript 示例与真实项目工程帮助你在自己的仓库里从零搭建一套可验证、可迭代的 harness。一、什么是 Harness模型之外的一切工程基础设施先看本讲给出的最直接定义——对于一个在本地仓库中工作的编码 Agentharness 组件清单如下原文见 code/harness-components.mdModelLLM 本身这是唯一不属于 harness 的部分Harness包含prompt 系统system promptAGENTS.mdbash 工具bash tool文件读写工具file read/write toolsgit 访问git access本地文件系统local filesystem启动脚本startup scripts测试命令test commands停止钩子stop hookslint 检查lint checks评估循环evaluator loop清单末尾有一句被很多人忽略的关键结论“If you change any of the above harness pieces, you change the effective agent.”你改动上面任何一件 harness 组件就等于改动了实际的 Agent。这句话是 harness engineering 的出发点——模型的权重是固定的但决定模型能力被兑现多少的是这套外部基础设施。本讲原文进一步把 harness 收拢成一个可执行的公式Harness 指令Instructions 工具Tools 环境Environment 状态State 反馈Feedback五个子系统缺一不可。缺失任何一个意味着 harness 不完整Agent 用起来总会“别扭”。二、五个子系统的职责与落地要点本讲用一张流程图描述五个子系统之间的数据流见 index.md1. 指令子系统Instructions为项目创建AGENTS.md或CLAUDE.md内容应包含项目概览与目的、技术栈与版本、首次运行命令、不可妥协的硬性约束、指向更详细文档的链接。关键原则是“给地图而不是给手册”Give a map, not a manualAGENTS.md应该像导航页而不是百科全书100 行左右通常足够装不下就拆分到docs/目录让 Agent 按需查阅。仓库里projects/project-01/solution/AGENTS.md是一个很好的示范——它只有五节Startup Rules、Electron Layer Boundaries、Conventions、Definition of Done、Working with the Feature List其中 Startup Rules 用有序步骤约束 Agent 开工前的固定动作先读本文件、再读docs/ARCHITECTURE.md与docs/PRODUCT.md、执行bash init.sh验证构建、最后读取feature_list.json。这正是“指令子系统”在真实项目中的形态。2. 工具子系统Tools确保 Agent 拥有足够的工具访问权。不要以“安全原因”禁用 shell——如果 Agent 连pip install都执行不了它如何完成任务但也不要毫无节制地全开应遵循最小权限原则least privilege。在本讲的配套代码 code/minimal-harness-loop.ts 中可以看到工具子系统的最小形态一个runTool(name, input)分发函数目前只实现了read_file未知工具直接返回ok: false与错误信息——这就是“用代码约束 Agent 能力边界”的最小可运行样例。3. 环境子系统Environment让环境状态“自描述”self-describing用pyproject.toml或package.json锁定依赖用.nvmrc或.python-version指定运行时版本用 Docker 或 devcontainers 保证环境可复现。环境的不可复现正是很多 Agent 失败报告中“能在我机器上跑”的真正根源。4. 状态子系统State长任务必须有进度追踪。用一个简单的PROGRESS.md记录三件事已完成what is done、进行中what is in progress、被阻塞what is blocked。每次会话结束前更新下次会话开始时读取。这与本讲后续项目Project 03 多会话连续性、Project 12 每次会话留下干净状态的思想一脉相承。5. 反馈子系统Feedback这是投资回报率最高的子系统。在AGENTS.md中显式列出验证命令原文示例Verification commands: - Tests: pytest tests/ -x - Type check: mypy src/ --strict - Lint: ruff check src/ - Full verification: make check (includes all above)仓库中projects/project-01/solution/AGENTS.md的 “Definition of Done” 一节同样把“可验证”作为完成标准TypeScript 编译无错误npm run check、应用能启动且窗口可见npm run dev、功能在feature_list.json中标记为pass并附上证据、遵守分层边界、运行期无 console 错误。这五条就是该项目的“验证命令集”。三、用代码看懂 harness 如何改变 Agent 行为本讲的配套代码 code/harness-vs-no-harness.ts 用同一个任务执行器做了“有 harness”与“无 harness”的对照实验可以直接运行npx tsx docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts任务集包含 5 个任务每个任务有requiresAuth、hasTests、withinScope三个属性const tasks: Task[] [ { name: Add search endpoint, requiresAuth: true, hasTests: false, withinScope: true }, { name: Add delete endpoint, requiresAuth: true, hasTests: true, withinScope: true }, { name: Refactor auth middleware, requiresAuth: true, hasTests: true, withinScope: false }, { name: Add health check, requiresAuth: false, hasTests: true, withinScope: true }, { name: Add rate limiter, requiresAuth: true, hasTests: false, withinScope: true }, ];无 harness 版本runWithoutHarness的执行逻辑是“Agent 干完活就宣布完成”——passed恒为true即使“需要鉴权的端点没有测试”“任务超出当前范围”这类问题已经发生也没有任何机制让 Agent 察觉。有 harness 版本runWithHarness则引入了两条可执行规则和一次验证步骤const rules { requireTestsForAuth: true, enforceScope: true, }; // 规则 1鉴权端点必须有测试否则 BLOCKED // 规则 2超出当前范围的任务被跳过标记 BLOCKED // 验证通过后才检查 没有测试 并给出 WARNING运行后程序会输出一个对照表和一个汇总指标printComparison其中“假阳性通过了但有缺陷”一栏最能说明问题无 harness 时所有任务都“通过”而 harness 版本能把真实缺陷暴露出来。脚本最后两行注释点明了结论“The harness catches problems the no-harness run silently ignores. Without a harness, every task passes even when it shouldnt.”harness 捕获了无 harness 运行会静默忽略的问题没有 harness每个任务都会“通过”即使它本不该通过。这个例子完美呼应了组件清单中的“evaluator loop评估循环”——反馈不是靠 Agent 自觉而是靠外部的检查机制强制闭环。四、量化 harness 的价值控制变量排除实验harness 组件这么多怎么知道哪个最有价值本讲给出的方法论是**“控制变量排除测试”**controlled variable exclusion test保持模型固定不变一次只移除五个子系统中的一个删除AGENTS.md、不提供验证命令、去掉进度文件……测量移除后性能下降的幅度。移除后下降最大的组件就是当前任务边际贡献最高的组件值得优先强化。但有两个重要的限定条件下降幅度不等于瓶颈位置这个实验只能回答“当前哪个组件最有价值”不能单独证明“瓶颈在哪里”。要定位真正瓶颈必须结合失败记录与失败归因failure attribution任务本身定义不清上下文不足环境不可复现缺少验证反馈还是状态管理坏了组件消融结果只能作为佐证。接近零影响的组件不要急着删它们可能只是冗余、设计不佳或者只是“当前任务没用到”。随着模型变强一些组件会不再关键但新的关键组件总会出现——这正是 Anthropic 在实际消融中观察到的现象。五、一个真实团队的演进案例20% → 近 100%本讲记录了一个真实团队用 GPT-4o 开发 TypeScript React 前端应用约 2 万行代码的四个阶段本质上是“一次加一个 harness 组件”阶段加了什么成功率阶段 1仅 README 中的基础项目描述20%5 次执行只成功 1 次主要失败选错包管理器npm vs yarn、不遵循组件命名规范、无法运行测试阶段 2增加AGENTS.md写明技术栈版本、命名规范、关键架构决策60%剩余失败集中在环境问题与验证缺失阶段 3在AGENTS.md中列出验证命令yarn test yarn lint yarn build80%阶段 4引入进度文件模板Agent 每次运行记录完成与未完成内容稳定在 80%–100%四次迭代模型从未更换成功率却从 20% 提升到接近 100%。你没有换更强的模型——换的是 harness。这个案例在仓库中并非孤例projects/project-01/solution/feature_list.json就展示了“把验证结果固化成证据”的落地方式——每个功能条目都带statuspass/fail/not-started、evidence和testedAt时间戳例如window-launch的 evidence 是“npm run devlaunches window at 1200x800 with contextIsolationtrue and nodeIntegrationfalse”。这相当于把上面案例里的“阶段 3 阶段 4”合并成了一种可审计的工程实践不是 Agent 声称完成了而是有可复现的证据表明完成了。六、工具对比为什么说“是 harness 不行不是 Agent 不行”本讲用几个读者都熟悉的工具印证 harness 思想此处仅作项目事实引用不提供外部链接Claude Code会读取仓库中的CLAUDE.md、能执行 shell 命令、运行在本地环境、维护会话历史、可运行测试。但如果你不告诉它测试怎么跑它就无法验证自己做得对不对——反馈子系统缺失。Cursor.cursorrules是指令来源终端是工具能读取项目结构与 lint 配置。但状态管理较弱——关闭 IDE 再打开之前的上下文就没了。CodexOpenAI 的编码 Agent用 git worktrees 隔离每个任务的运行环境配合本地可观测性栈日志、指标、trace每次改动都在独立环境中验证。在带AGENTS.md和清晰验证命令的仓库中表现远好于“裸”仓库。AutoGPT反面教材。缺少结构化状态管理导致长任务中上下文无限累积缺少精确反馈机制导致 Agent 进入死循环。很多人说“AutoGPT 不好用”实际上是它的 harness 不好用。本讲还引用了两个行业共识作为理论锚点OpenAI 将 harness engineering 的核心原则概括为“the repo IS the spec仓库即规格”——所有必要上下文都应存在于仓库内通过结构化指令文件、显式验证命令和清晰的目录组织交付Anthropic 的长时运行 Agent 文档则强调状态持久化、显式恢复路径和结构化进度追踪。两家公司侧重不同但说的是一件事模型之外的一切工程基础设施决定了模型能力被真正兑现多少。七、核心要点与实践练习关键结论Harness 指令 工具 环境 状态 反馈五个子系统缺一不可只要不是模型权重就是 harness。你的 harness 决定模型能力被兑现多少五个子系统中反馈子系统通常成本最低、回报最高——先从验证命令开始用控制变量排除测试量化各子系统的边际贡献要定位真正瓶颈依赖失败记录与归因而不是仅靠消融Harness 会像代码一样腐烂。定期审计像偿还技术债一样偿还 harness 债。三个可直接上手的练习五维审计选一个你正在用 AI Agent 的项目用五子系统框架做完整审计为每个子系统打 1–5 分找到最低分子系统花 30 分钟改进它观察 Agent 表现变化。控制变量排除测试固定一个模型和一个有挑战性的任务依次只移除指令删AGENTS.md、移除反馈不提供验证命令、移除状态无进度文件每次只删一项并测量性能下降同时记录失败日志做根因归因。Affordance 分析找出项目中 Agent“想做但做不到”的场景例如知道应该用参数化查询却不了解项目的 ORM 模式分析它是 Gulf of Execution不知道如何操作还是 Gulf of Evaluation不知道自己做对了没有然后设计一个 harness 改进来弥合该差距。配套的动手项目是 Project 01: Baseline vs Minimal Harness其完整工程含AGENTS.md、feature_list.json、分层架构文档位于 projects/project-01/solution可作为你对照练习的参考基线。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 精读Harness 组件拆解与五子系统工程化实践learn harness engineering 精读Harness 组件拆解与五子系统工程化实践 导读 本文是《Harness Engineering 从Harness 模板套件完全指南在 learn-harness-engineering 中搭建 Agent 工作流基础设施Harness 模板套件完全指南在 learn harness engineering 中搭建 Agent 工作流基础设施 导读 Template GuidePrompt Calibration 指南让 Harness 根指令文件保持锋利——learn-harness-engineering 实践Prompt Calibration 指南让 Harness 根指令文件保持锋利——learn harness engineering 实践 根指令文件ro上一篇Lucky缓存机制原理解析提升DDNS解析效率减少API请求次数下一篇LongCat-Flash-Thinking-2601-FP8随机复杂任务测试大模型泛化能力突破的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![11_神经网络基础[pytorch框架与神经网络基础]](http://pic.xiahunao.cn/yaotu/11_神经网络基础[pytorch框架与神经网络基础])
