【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文基于 learn-harness-engineering 仓库中俄语版《Лекция 01. Сильные модели не означают надёжного исполнения》第一讲模型能力强 ≠ 执行可靠及其配套代码目录展开。文章核心回答一个问题为什么同一个模型在弱环境下频频翻车在完整 harness 下却能稳定交付读完你将掌握能力鸿沟Capability Gap、验证缺口Verification Gap等核心概念学会用五层防御归因失败、编写机器可验证的完成定义Definition of Done并通过仓库中可运行的failure-pattern-demo.ts演示与 project-01 对比实验亲手验证修 harness 比换模型更有效这一核心结论。背景50-60% 的通过率意味着什么截至 2025 年底最强的 coding agent 在 SWE-bench Verified 上的通过率大约只有 50-60%。而且这个数字的前提是精心挑选过的任务——有明确的 issue 描述、有现成的测试用例。当你把日常需求丢过去时情况只会更糟需求模糊、没有现成测试、隐含的业务规则散落在各处。真实场景中你大概率遇到过这样的结果agent 跑了 20 分钟后告诉你做完了你一看代码——加了功能但测试挂了改了 bug 却引入了新 bug交付的东西根本不是你要的。大多数人的第一反应是这模型不行换一个更贵的。但在掏钱包之前请先读完本讲的核心论点问题可能根本不在模型身上。同一匹马两种命运Anthropic 对照实验Anthropic 做过一个极具说服力的对照实验同一个 prompt做一个 2D 复古游戏编辑器、同一个模型Opus 4.5跑了两次运行方式耗时成本结果裸环境无 harness 支持20 分钟$9游戏核心功能跑不起来完整 harnessplanner generator evaluator 三 agent 架构6 小时$200游戏可以正常游玩模型没换Opus 4.5 还是那个 Opus 4.5换的是马具——也就是 harness。OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白Codex 在一个 harness 搭得好的仓库里表现能从不可靠直接跳到可靠。注意这个用词——不是好了一点而是质变。Harness 的含义就是模型权重之外的一切工程基础设施——指令、工具、环境、状态管理、验证反馈。只要不是模型权重全都是 harness。agent 到底卡在哪五种典型失败模式具体失败模式其实就那么几种逐一对照你可以在真实项目中找到对应案例需求描述模糊agent 只能猜。加个搜索功能等于没说。搜索对象是什么全文本还是结构化查询结果要不要分页、要不要高亮你没说明白agent 就只好猜。猜对了算运气好猜错了来回折腾比一开始说清楚多花好几倍时间。**隐性约定没写下来agent 无从遵守。**你们全组都用 SQLAlchemy 2.0 新语法agent 默认写了 1.x 代码所有 API 端点必须走 OAuth 2.0 认证可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 不是不想遵守是真没见过这条规则。**环境配置有缺口agent 把精力花在修环境上。**开发环境不完整、依赖缺失、工具版本不对agent 把宝贵的上下文窗口花在pip install报错、Node 版本冲突上真正该干的活反而没精力做。缺少验证手段agent 自己觉得做完了就算完成。没有测试、没有 lint、或验证命令根本没告诉 agent。Anthropic 还观察到一个现象当 agent 感觉上下文快满时会匆忙结束当前工作、跳过验证步骤、选简单方案而非最优方案——这被称为上下文焦虑context anxiety。跨会话状态丢失每个新会话都要重新探索。上次会话的发现全丢了每个新会话都要重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。本讲配套目录中有一份专门演示任务定义不充分的示例文件 underspecified-task.md它给出了一个典型的模糊 prompt做一个带 AI 问答的桌面知识库应用然后明确列出该 prompt 缺失的约束——没有启动命令、没有目录结构、没有数据模型、没有显式完成标准。其典型结局正如文件所写agent 边做边发明结构、应用能编译但运行不稳定、UI 比真正可用的摄取/问答路径更早出现、agent 经常在表面成功后就停下来。这正是失败模式 1 与 4 的教科书案例。关键名词六组必须掌握的术语理解了上面的场景这些术语就不再是空话能力鸿沟Capability Gap模型在基准测试上的表现与真实任务表现之间的巨大落差。SWE-bench Verified 上 50-60% 的通过率意味着近一半真实 issue 解不了。Harness模型之外的一切——指令、工具、环境、状态管理、验证反馈。不是模型权重的部分全是 harness也就是马具。Harness 诱导失败Harness-Induced Failure模型本身能力足够但因执行环境存在结构性缺陷而失败。Anthropic 对照实验已经证明了这一点。验证缺口Verification Gapagent 对自己输出的信心评估与实际正确性之间的偏差。agent 说我做完了但实际没做完——这是最常见的失败模式。诊断循环Diagnostic Loop执行 → 观察失败 → 定位到 harness 的哪一层 → 修补那一层 → 重新执行。这是 harness 工程的核心方法论。完成定义Definition of Done一组可以用命令验证的条件——测试通过、lint 无报错、类型检查通过。没有显式的完成定义agent 就会自己编一个。代码演练用 failure-pattern-demo.ts 复现四步失败模式本讲配套代码 failure-pattern-demo.ts 用一段约 170 行的 TypeScript 程序把有能力的 agent 如何一步步滑向失败完整模拟出来。它抽象出四步失败模式上下文不完整Incomplete Contextagent 只拿到项目结构和路由定义不知道认证中间件、限流策略、测试规范的存在局部合理的修改Locally Reasonable Changes补上认证后代码局部看没问题但仍缺限流与测试缺乏全局验证No Global Verification功能看似齐备但没有测试回归风险与项目规范冲突被无视过早宣称完成Premature Completionagent 输出Done. Added search endpoint.任务被标记为完成实际交付物残缺。程序核心是一个模拟模型的决策函数modelDecide——它只根据给定上下文做决定没有auth上下文就写无认证的路由没有rate-limit就漏掉限流没有test-standards就不写测试。它精确还原了讲座的核心论断在信息不足时agent 的每一步单独看都合理但组合起来就是残缺交付物。运行方式需要 Node 环境与 tsxnpx tsx docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts程序会打印四步状态表每一步的可用上下文、缺失上下文、采取的行动、局部结果、全局影响、是否被标记完成最后输出一张对比表逐项核对 5 项必需上下文项目结构、路由定义、认证中间件、限流策略、测试规范中哪些缺失并给出结论Agent completed with N of 5 context items missing. This is the core failure pattern: each step looked reasonable in isolation.agent 在缺失 N/5 项上下文的情况下完成任务——每一步孤立看都合理这正是核心失败模式。失败信号检查清单复盘弱 harness 运行的五问配套的 failure-signals-checklist.md 提供了一份复盘清单在每次弱 harness 运行后逐条自问agent 是否询问过如何启动应用还是做出了错误假设它是否创建了与预期产品不符的目录或抽象它是否在只做完视觉 UI 外壳后就停下来而没有完整的可用场景它是否留下了有助于下一次运行接续的笔记或工件一个全新的会话能否在五分钟内理解之前发生了什么这五问把模糊的失败感转化为可操作的诊断输入是失败归因到层的最轻量落地工具。遇到失败先修 harness 而不是换模型核心原则只有一条遇到失败先别换模型先检查 harness。如果同一个模型在类似的结构良好的任务中能成功那优先假设是 harness 的问题——就像车坏了先查是不是没油而不是直接怀疑发动机。把每次失败归因到五层防御不要笼统地说模型不行而要问是任务没说清楚是上下文不够是环境没配好是验证手段缺失还是上一个会话的状态没接上把每次失败归到五层防御之一任务规范、上下文供给、执行环境、验证反馈、状态管理。养成这个习惯后模型不行这个结论会在你的日志里出现得越来越少。写显式的完成定义Definition of Done不要只说加个搜索功能要写成机器可验证的条件完成标准 - 新增 GET /api/search?qxxx 端点 - 支持分页默认 20 条 - 返回结果包含高亮片段 - 所有新代码通过 pytest - 类型检查通过mypy --strict在仓库根目录放一个 AGENTS.md用 AGENTS.md 告诉 agent 这个项目的技术栈、架构约定和验证命令。这是 harness 工程的第一步也是投入产出比最高的一步——一个 AGENTS.md 文件可能比你换一个更贵的模型更有效。本仓库自身就是最佳范例根目录的 CLAUDE.md 定义了项目概览、全部命令文档站点构建、npx tsx运行课程代码、各项目 Electron 应用的npm run dev/npm run check/npm run test与仓库结构这正是把约定写进仓库、让 agent 可读取的实践。建立诊断循环并测量改进不要把失败当agent 又犯傻了要当作harness 又暴露了一个缺陷的信号。每次失败定位到某一层 → 修补 → 下次不再犯。几轮下来 harness 越来越强agent 表现稳定提升。同时记一个简单的日志——每个任务成功与否、失败是哪一层的问题跑几轮后就能看出哪个层是瓶颈集中火力修那一层。仓库实战Project 01 对比实验prompt-only vs 规则先行本讲的结论在仓库中有一个直接对应的动手项目 project-01-baseline-vs-minimal-harness其目标是比较**弱 harness仅靠 prompt与显式 harness规则文件 验证机制**对 AI 编码任务完成率的影响。完整说明见 projects/project-01/README-CN.md。两个对照版本starter/起点版本。只有一份一句话的 task-prompt.md——Build an Electron app that can show documents and answer questions.构建一个能展示文档并回答问题的 Electron 应用。没有 AGENTS.md、没有 feature_list.json这就是弱 harness。solution/参考实现。同样的应用代码但配备完整 harnessAGENTS.md、feature_list.json、init.sh、claude-progress.md这是显式 harness。显式 harness 由什么组成solution/AGENTS.md 是规则先行的核心它包含启动规则Startup Rules写任何代码前必须按顺序完成——完整阅读本文件、读docs/ARCHITECTURE.md理解 Electron 分层、读docs/PRODUCT.md理解功能需求、运行bash init.sh验证构建、读feature_list.json了解功能状态分层边界Electron Layer BoundariesMain Process / Preload / Renderer / Services 四层严格隔离每层明确能做什么、禁止做什么例如 Renderer 禁止直接 import Node.js 模块只能通过window.knowledgeBase通信约定ConventionsTypeScript strict 模式、禁止无注释的any、统一具名导出、IPC 通道名集中在src/shared/types.ts完成定义Definition of DoneTypeScript 编译无错误npm run check、应用可启动且窗口可见npm run dev、功能在feature_list.json中标记pass并附证据、代码遵守分层边界、正常运行无控制台错误。feature_list.json 是项目进度的唯一事实来源每个功能有statuspass/fail/not-started与evidence字段。四个功能——window-launch窗口启动、document-list文档列表面板、question-panel问答面板、data-directory本地数据目录——全部以pass状态和可验证证据记录例如窗口以1200x800、contextIsolationtrue、nodeIntegrationfalse启动。这正是讲座中机器可验证的完成定义 验证反馈层的落地实现。init.sh 实现了初始化即验证依次执行npm install、npm run check类型检查、npm run build构建任何一步失败都阻止 agent 继续写代码——这就是环境层的自动化保障。实验步骤# 1. 用 starter弱 harness跑一次 cd projects/project-01/starter npm install # 把 task-prompt.md 的内容作为 prompt 交给 Claude Code / Codex # 让 agent 尝试完成四个功能这一轮不要给 solution 文件 # 2. 用 solution显式 harness跑一次 cd projects/project-01/solution npm install # 让 agent 先读取 AGENTS.md、init.sh、feature_list.json、claude-progress.md # 再开始实现同样的四个功能 # 3. 对比两次结果 # - 任务是否完成 # - 需要重试几次 # - agent 是否提前声称完成对照关系来自 README-CN.md窗口启动看src/main/main.ts↔feature_list.json的window-launch文档列表看src/renderer/components/DocumentList.tsx↔document-list问答面板看src/renderer/components/QuestionPanel.tsx↔question-panel本地数据目录看src/services/persistence-service.ts↔data-directory。注意这个项目不是普通的把 starter 改成 solution练习而是对比 prompt-only 与显式规则/验证产物之间的差异。一百万行代码的实验OpenAI 的极限验证2025 年OpenAI 三个工程师开始了一项激进实验他们不直接写代码只让 Codex 从空 git 仓库起步构建一个完整内部产品。五个月后仓库里有约 100 万行代码——应用逻辑、基础设施、工具、文档全部由 agent 生成。三个工程师开了约 1,500 个 PR平均每人每天 3.5 个。关键限制是人类不直接写代码。这不是作秀——实验逼着团队理解当工程师的主要工作不再是写代码而是设计环境、表达意图、构建反馈循环时什么才真正重要。起初进展出乎意料地慢原因不是 Codex 能力不足而是环境不够完整——agent 缺少推进高层目标所需的工具、抽象和内部结构。工程师的工作逐渐演化为把大目标拆成小积木设计、编码、审查、测试→ 让 agent 逐个搭建 → 再用这些积木组合更复杂的任务。当某件事做砸时修复方案几乎从来不是再努力一点而是agent 缺什么能力以及如何用一种既可理解又可执行的方式补上。这个实验直接印证了本讲核心论点同一个模型在空白环境里和在有完整 harness 的环境里产出有本质差异。模型没变变的是环境。一个更接地气的例子FastAPI 应用加端点一个团队用 Claude Sonnet 给一个中等规模的 Python Web 应用FastAPI PostgreSQL Redis约 15,000 行代码添加新 API 端点。第一轮只有一句话 prompt。他们说在/api/v2/users下添加用户偏好设置端点。结果agent 花了 40% 的上下文窗口探索仓库结构产出了看似合理的代码但没遵循项目的错误处理模式用了旧版 SQLAlchemy 语法宣称完成但端点实际有运行时错误下一个会话还得重新做一遍探索。第二轮补齐 harness。团队加了 AGENTS.md描述项目架构与技术栈版本、显式验证命令pytest tests/api/v2/ python -m mypy src/和架构决策记录ADR。同一个模型在三次独立运行中全部成功上下文使用效率提高了约 60%。模型没变。变的还是 harness。核心要点模型能力和执行可靠性是两回事千里马也得配上好马具。失败的时候先看 harness再看模型。换模型是成本最高的选择而且很多时候根本不是模型的问题。每次失败都是一个信号你的 harness 有结构性缺陷。把它找出来、修掉。五层防御任务规范、上下文供给、执行环境、验证反馈、状态管理。逐层排查问题十有八九出在其中一层。一个 AGENTS.md 文件可能比你换一个更贵的模型更有效。练习把理论变成肌肉记忆对比实验选一个你熟悉的代码仓库和一项非平凡的修改任务。先不给任何 harness 支持让 agent 跑一次、记录失败然后加一个 AGENTS.md 和显式验证命令让同一个 agent 再跑一次。对比两次结果把失败归因到五层防御中的某一层。验证缺口测量选 5 个编码任务每个任务完成后记录 agent 是否声称完成再用独立测试验证实际正确性。计算agent 实际没完成却声称完成的比例——这就是你的验证缺口。然后思考加什么验证命令能把这个比例降下来诊断循环实践找一个 agent 在你的项目中反复失败的任务。跑一次 → 记录失败 → 归因到某一层 → 修那一层 → 再跑。重复三到五轮记录每一轮的改善。延伸阅读与仓库入口本讲的结论基于 OpenAI《Harness Engineering: Leveraging Codex in an Agent-First World》、Anthropic《Effective Harnesses for Long-Running Agents》、HumanLayer《Skill Issue: Harness Engineering for Coding Agents》等 2025 年的行业文章以及 SWE-bench Verified 榜单数据均已在讲座原文中列出来源。你可以继续在本仓库深入本讲俄语版正文docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md另有中文版 docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md配套代码目录docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/含失败模式演示、失败信号检查清单、欠定义任务示例动手项目docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md 与 projects/project-01/README-CN.md后续内容第二讲 什么是 Harness 将进一步拆解 harness 的组成与构建方法。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Learn Harness Engineering 第 01 讲为什么强大的模型仍然执行失败——先修 Harness再换模型Learn Harness Engineering 第 01 讲为什么强大的模型仍然执行失败——先修 Harness再换模型 本文基于本仓库教程 Lectu为什么强大的模型仍然会失败learn-harness-engineering 第一课模型能力不等于可靠执行为什么强大的模型仍然会失败learn harness engineering 第一课模型能力不等于可靠执行 导读本篇文章以 learn harness e强模型为何仍然失败learn-harness-engineering 讲座 01 的失败模式拆解与 Harness 修复实战强模型为何仍然失败learn harness engineering 讲座 01 的失败模式拆解与 Harness 修复实战 本篇文章以 learn harn上一篇macOS百度网盘速度优化方案突破本地限制的完整技术解析下一篇Cursor Free VIP破解工具永久免费使用AI编程助手的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考