【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载运行 Agent 任务时模型能力只是必要条件工程化交付的可靠性取决于 harness提示、规则、环境、验证与状态管理。本文围绕 learn-harness-engineering 仓库 Lecture 01 配套的失败信号检查清单逐条拆解五个可观测的失败信号并结合仓库中的失败模式演示代码与 Project 01 对照实验给出定位信号 → 归因层 → 修复 harness的完整诊断方法。读完你将能用五分钟清单快速审查一次 Agent 执行质量把模型不行的直觉判断转化为对 harness 五层结构的精准归因。一、信号清单给 Agent 执行质量做体检失败信号检查清单 是一份法语的轻量诊断工具原文只有五个问题用于审查一次较弱的 harness 执行。它的设计哲学是不评价模型能力只观察可验证的执行痕迹。完整清单如下启动方式Agent 是否错误地询问或自行推断如何启动应用结构与产品匹配是否创建了与预期产品不符的目录或抽象完成度是否在只做出可见 UI 外壳、没有完整流程时就停了下来延续性是否留下了能帮助未来执行继续下去的笔记或工件可理解性一个新会话能否在五分钟内弄清楚发生了什么这五个问题看似简单却分别对应 Lecture 01 核心论述中能力强的 Agent 依然失败的最常见成因欠定义的任务、缺失的上下文约定、缺失的验证回路以及长期任务中的状态断裂。下面逐一展开并结合仓库源码给出识别与修复方法。二、信号 1启动方式不明——环境层的隐性问题信号Agent 是否错误地询问或推断如何启动应用这是环境层environment失败的最典型表征。在 欠定义任务示例 中任务只写了一句构建一个带 AI 问答的知识库桌面应用约束明确写着没有提供启动命令、没有目录结构指南、没有数据模型、没有明确的完成标准。文档还预判了典型结果应用可以编译但无法稳定启动UI 先出现却没有可用的导入/查询路径。当 Agent 不知道npm run dev还是electron .才能启动时它会消耗大量上下文在pip install、Node 版本、依赖缺失等环境排错上而不是解决真正的问题——这正是 Lecture 01 中环境是陷阱一节的描述。仓库的 Project 01 说明 给出了对照starter/只有一句task-prompt.md内容 全文为Build an Electron app that can show documents and answer questions.而solution/则通过init.sh把启动链路固化为可执行脚本。修复方法把启动与验证命令写进仓库根目录的规则文件。Project 01 的 init.sh 是一个可以直接复用的模板它用set -euo pipefail保证任一步失败即中止#!/usr/bin/env bash # init.sh -- Verify the project builds cleanly before starting work. set -euo pipefail echo [1/3] Installing dependencies... npm install echo [2/3] Running type checks... npm run check echo [3/3] Building project... npm run build echo Init complete. All checks passed. echo Run npm run dev to launch the application.有了这类脚本信号 1 就不会出现启动方式已被显式声明Agent 无需猜测。三、信号 2结构与产品不匹配——欠定义任务的必然产物信号是否创建了与预期产品不符的目录或抽象当任务缺少约束时Agent 会发明目录结构和抽象层。这与信号 1 同源但后果更隐蔽本地看起来合理的结构放到产品语境里就是错位的。仓库配套的 failure-pattern-demo.ts 用可运行代码模拟了这一过程。它定义了一个模拟模型的决策函数modelDecide给定添加搜索端点任务模型只依据已提供的上下文做决定——没有auth就写不带认证的路由没有rate-limit就漏掉限流没有test-standards就不写测试。运行方式npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts从源码结构看该演示刻意复刻了四步失败模式文件头注释failure-pattern-demo.ts中写明上下文不完整 → 局部合理的改动 → 无全局验证 → 过早完成。每一步单独看都看起来没问题这正是结构失配的根源Agent 基于它看到的局部上下文做局部决策产品结构是否合理需要全局标准来判定而全局标准恰恰缺失。修复方法用架构约定约束结构。Project 01 solution 的 AGENTS.md 是教科书式的例子——它把 Electron 项目强制划分为四个严格层src/main/主进程负责BrowserWindow生命周期与 IPC 注册禁止引入渲染层代码src/preload/唯一桥接层只用contextBridge.exposeInMainWorld暴露类型化 APIsrc/renderer/React TypeScript UI 层只能通过window.knowledgeBase与主进程通信禁止直接importNode 模块src/services/主进程内的纯业务逻辑只能依赖src/shared/。把这类边界写进规则文件后创建与产品不符的抽象就会在结构上被规则直接拦截。四、信号 3只有 UI 外壳就停下——缺少验证回路的标志信号是否在做出可见 UI 外壳、没有完整流程后就停止这是验证差距verification gap的典型外显。Lecture 01 指出没有测试、没有 lint、或验证命令从未被传达时Agent 写代码、看一眼、觉得没问题、宣布完成——就像学生没有答案就交卷。更值得警惕的是 Anthropic 观察到的context anxiety上下文焦虑当 Agent 感到上下文快被耗尽时会加速收尾、跳过验证、选简单方案而非最优方案。欠定义任务示例 对此的预测是agent 经常在获得表面成功后就停止。UI 能渲染但导入/查询的完整数据流没打通——这就是只有外壳。修复方法写显式的 Definition of Done且必须是机器可验证的条件。Lecture 01 给出了通用模板Completion criteria: - New endpoint GET /api/search?qxxx - Supports pagination, default 20 items - Results include highlighted snippets - All new code passes pytest - Type checking passes (mypy --strict)仓库中的落地形态则是 feature_list.json它把窗口启动文档列表面板问答面板数据目录四个功能拆成条目每个条目带statuspass/fail/not-started和evidence证据字符串。question-panel的条目写明证据是QuestionPanel 渲染文本输入与 Ask 按钮在回车或点击时提交到window.knowledgeBase.qa.ask——这就是把UI 外壳升级为完整流程的证据要求。而 AGENTS.md 中 DoD 的第一条TypeScript compiles without errors (npm run check)则是把验证命令直接绑定到完成定义上。五、信号 4 与 5状态断裂与不可延续——长期任务的致命伤信号 4是否留下帮助未来执行继续的笔记或工件 信号 5新会话能否在五分钟内理解发生了什么这两个信号针对的是跨会话任务。Lecture 01 明确警告超过 30 分钟的任务若没有持久状态失败率会大幅上升——上一次会话的发现全部丢失每个新会话都要重新探索项目。Project 01 的 solution 展示了状态工件应该长什么样除AGENTS.md、feature_list.json、init.sh外还有claude-progress.md会话进度记录。它的使用流程是先读规则文件再跑init.sh确认构建干净然后读feature_list.json看功能当前状态最后对照进度文件继续工作。这套流程让一个新会话能在几分钟内重建上下文——这正是信号 5 的合格标准五分钟内理解发生了什么。修复方法让延续性成为显式产物而不是 Agent 的自觉。Lecture 01 的诊断循环diagnostic loop把每次失败当作 harness 缺陷信号运行 → 观察失败 → 归因到某个层 → 修复该层 → 重跑。信号 4/5 修复的落点就是状态层把探索结论、已完成项、下一步计划持久化到仓库内的文件中。六、把五个信号接入五层归因模型Lecture 01 给出的是五个诊断层specification规格、context上下文、environment环境、verification feedback验证反馈、state状态。五个失败信号与五层之间存在稳定的映射关系可用作归因表失败信号首选归因层修复动作仓库示例1. 启动方式错误/乱猜environment提供init.sh固化安装、检查、构建链路2. 目录/抽象与产品不符specification / context在AGENTS.md中写死分层边界与架构约定3. 只有 UI 外壳即停verification feedback写机器可验证的 DoD用feature_list.json记录证据4. 未留下延续工件state维护claude-progress.md、session-handoff 等进度文件5. 新会话无法快速理解state / context根目录AGENTS.md 可执行的 init 流程这条表的核心判断来自 Lecture 01 的中心论点如果同一个模型在结构良好的相似任务上能成功就假设是 harness 问题。像修车先查油路而不是怪发动机一样归因顺序永远是先查 harness后换模型。七、实战演练用 Project 01 跑一次信号驱动的对照实验仓库的 Project 01 是这一清单的最佳练兵场它是一个基线 vs 最小 harness 的对照实验# 1. 先用弱 harness仅 prompt跑一遍 cd projects/project-01/starter npm install # 把 starter/task-prompt.md 的内容作为 prompt 交给 Agent # 要求它完成窗口启动、文档列表、问答面板、数据目录 # 2. 再用显式 harness完整规则跑同一任务 cd ../solution npm install # 要求 Agent 在动代码前先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md # 3. 对照评估 # - 任务完成了吗 # - 重试了几次 # - Agent 是否过早宣布完成README 给出了精确的对照特征表window-launch对应src/main/main.ts与src/preload/preload.tsdocument-list对应src/renderer/components/DocumentList.tsxquestion-panel对应src/renderer/components/QuestionPanel.tsxdata-directory对应src/services/persistence-service.ts。检查时把五次信号清单逐项打在两次运行的结果上就能量化prompt-only 运行与从显式规则与验证工件出发的运行之间的完成率差距。八、把清单固化为日常习惯最后把这份清单变成每个任务结束时的固定收尾动作运行后立即过清单按五个信号逐项打勾任何一个为是即判定本次执行存在 harness 缺陷归因到层用第六节的映射表把信号落到 specification / context / environment / verification / state 五层之一修复后留痕在AGENTS.md、feature_list.json或进度文件中记录本次缺陷与修复避免同一失败模式复发量化追踪像 Lecture 01 建议的那样记一份简单日志成功/失败、责任层几轮之后瓶颈自然显现。如 Lecture 01 所总结模型能力与执行可靠性是两回事失败时先检查 harness再怀疑模型每一次失败都是 harness 存在结构性缺陷的信号。这份五问清单就是把这些原则落到每次执行审查中的最小可行工具。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐为什么能力强大的 AI Agent 仍然会失败learn-harness-engineering 第一课的 Harness 工程思维入门为什么能力强大的 AI Agent 仍然会失败learn harness engineering 第一课的 Harness 工程思维入门 本教程来自 lear规格不足的任务为什么能力再强的 Agent 也会失败——learn-harness-engineering 的实战拆解规格不足的任务为什么能力再强的 Agent 也会失败——learn harness engineering 的实战拆解 导读 本文围绕 learn harnlearn-harness-engineering 实战弱 Harness 运行的失败信号自检清单Failure Signals Checklistlearn harness engineering 实战弱 Harness 运行的失败信号自检清单Failure Signals Checklist 导读上一篇ZLMediaKit WebRTC推流SRTP初始化失败问题分析与解决下一篇深度解析RocksDB前缀提取器避免使用陷阱与高效解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考