解析「任务描述不充分」：以 Learn Harness Engineering 第 01 讲的 underspecified-task 为例，理解强大 Agent 为何仍然失败

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文以 learn-harness-engineering 仓库中第 01 讲的配套文档 underspecified-task.md 为骨架拆解一个「能力强大但任务描述近乎空白」的典型提示词结合同目录下的 failure-pattern-demo.ts 仿真代码、failure-signals-checklist.md 检查清单以及 Project 01 的弱 Harness / 显式 Harness 对照实验说明为什么「换更强的模型」不是第一优先动作以及如何用显式的任务契约、Definition of Done 和 AGENTS.md 堵住失败缺口。读完本文你将掌握如何识别任务描述中的隐性缺口、如何用五层诊断法定位失败、以及如何把一句模糊需求改写成可验证的任务契约。一、原文案例一个「任务描述不充分」的完整样本underspecified-task.md给出的提示词极其简洁全文如下Build a desktop knowledge base app with AI question answering.翻译过来就是「构建一个带 AI 问答功能的桌面知识库应用」。它给出的约束是未指定任何约束None specified未给出启动命令No startup command given未提供目录结构指引No folder structure guidance未定义数据模型No data model defined没有显式的完成标准No explicit completion criteria这正是第 01 讲 index.md 所说的「日常需求」的极端形态含糊的规格、没有现成测试、业务规则散落在代码库各处。当 Agent 拿到这样的任务时它只能靠猜。二、这类提示词的典型结局四条可预期的失败轨迹原文档列出了这类提示词的典型产出这是理解「Harness-Induced Failure」的第一手证据Agent 临时发明一套结构the agent invents a structure ad hoc没有目录结构指引时Agent 会按自己的习惯拍脑袋建目录而不会与团队既有约定对齐应用可能能编译但无法稳定启动the app may compile but not start consistently没有启动命令说明Agent 不知道npm run dev、vite还是别的入口才是「正确启动方式」于是它可能交付一个能编译、却跑不起来的工程UI 先于可用的导入/问答路径出现the UI may appear before there is any usable ingest/query path没有数据模型定义Agent 倾向于先做出「看起来像产品」的界面外壳而真正核心的文档导入ingest与问答query链路却是空的Agent 常在「外观成功」后就停下来the agent often stops after cosmetic success没有完成标准Agent 会以「界面能显示、看起来差不多」作为完成标志而不是以「数据能进、问题能答、测试能过」作为完成标志。这四条轨迹不是猜测而是第 01 讲 index.md 总结的五大失败模式在该提示词上的具体投影需求含糊 → Agent 只能猜约定未落盘 → Agent 无从遵守环境不完整 → Agent 把精力耗在环境修复上没有验证手段 → Agent 自我感觉良好即宣布完成会话间状态丢失 → 每个新会话都要重新探索。三、源码佐证四步失败模式的仿真failure-pattern-demo.ts同目录下的 failure-pattern-demo.ts 把这个过程具象化为一个可运行的仿真。它的核心是一个modelDecide函数——一个只依据「当前可见上下文」做决策的简化「模型」function modelDecide(context: string[], task: string): string { const has (s: string) context.some((c) c.includes(s)); // The task is to add a search endpoint to the API. // Correct answer requires knowing about auth middleware and rate limiting. if (!has(auth)) { return Created new route handler /search without authentication checks; } if (!has(rate-limit)) { return Added search route with auth but forgot rate limiting; } if (!has(test-standards)) { return Implemented search with auth and rate-limit, but no tests; } return Fully implemented search endpoint with auth, rate-limit, and tests; }仿真把失败展开为四个步骤每一步在局部看都「合理」叠加起来却是坏交付物步骤名称缺什么局部结果全局影响1Incomplete Context上下文不完整auth 中间件、限流策略、测试标准路由能编译、能返回数据搜索接口未鉴权2Locally Reasonable Changes局部合理改动限流策略、测试标准路由有鉴权局部看完整无限流接口可被滥用3No Global Verification无全局验证测试标准功能看似全部实现无测试回归风险高4Premature Completion过早宣布完成测试标准Agent 满意任务标记完成任务实际未完成仿真结尾还会打印一张对比表统计「Agent 实际拥有的上下文」与「任务真正需要的上下文」之间的缺口GAP。运行方式在文件头注释中给出npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts注意这个路径是文件头注释里针对仓库原位置的写法在当前仓库根目录下对应文件为 docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts。这个仿真的价值在于它证明了「Agent 在局部上下文缺失时做出的每一步决定都有内在合理性」——问题从来不是模型不聪明而是它根本没看见它需要看见的东西。四、复盘清单用 failure-signals-checklist 审查一次弱 Harness 运行当一次运行结果不理想时不要急着说「模型不行」。failure-signals-checklist.md 提供了五个可操作的自检问题Agent 是询问了如何启动应用还是自己猜错了Did the agent ask, or infer incorrectly, how to start the app?——对应「没有启动命令」这一约束缺失它是否创建了与预期产品不符的目录或抽象Did it create directories or abstractions that do not match the intended product?——对应「没有目录结构指引」它是否在做出一个可见的 UI 外壳后、在完整工作流尚未成型时就停了下来Did it stop after making a visible UI shell without a complete workflow?——对应「UI 先于 ingest/query 路径出现」它是否留下了能让后续运行接续的笔记或产物Did it leave notes or artifacts that help a future run continue?——对应「跨会话状态丢失」一个新会话能否在五分钟内理解此前发生了什么Could a fresh session understand what happened in under five minutes?——这是对「可接续性」的量化检验。把这五个问题对照underspecified-task.md的约束列表会发现它们是一一对应的每一个缺失的约束都会在检查清单里命中一个问题。这说明失败不是随机的而是结构性的——只要任务描述不充分失败轨迹就高度可预测。五、为什么会失败Capability Gap 与 Harness 的定义第 01 讲 index.md 给出了几个理解上述现象的关键术语Capability Gap能力落差模型在基准测试上的表现与真实任务表现之间的巨大鸿沟。截至 2025 年底最强编码 Agent 在 SWE-bench Verified 上也只有约 50–60% 的通过率而那是「精心挑选、带现成测试」的任务日常含糊需求只会更低。Harness马具/驭具模型权重之外的一切工程基础设施——指令、工具、环境、状态管理、验证反馈。「不是模型权重就是 Harness。」Harness-Induced FailureHarness 引发的失败模型能力足够但执行环境存在结构性缺陷。Anthropic 的控制实验同一提示词、同一模型 Opus 4.5裸跑 20 分钟 $9 核心功能不可用带 planner/generator/evaluator 三 Agent 架构的完整 Harness 跑 6 小时 $200 游戏完整可玩已经证明了这一点。Verification Gap验证落差Agent 对自身输出的信心与实际正确性之间的差距。「Agent 说完成而实际没完成」是最常见的失败模式。Diagnostic Loop诊断循环执行 → 观察失败 → 归因到具体 Harness 层 → 修复该层 → 重新执行。这是 Harness 工程的核心方法论。Definition of Done完成定义一组可以用命令验证的条件测试通过、lint 干净、类型检查通过。没有显式的完成定义Agent 就会发明一个自己的完成定义——这正是underspecified-task.md中「agent often stops after cosmetic success」的根源。六、修复方案从「一句话需求」到「可验证任务契约」underspecified-task.md的教训指向一条明确出路把缺失的约束一项一项补齐。第 01 讲给出的最低限度方案包含三件事1. 写出显式的 Definition of Done不要只说「加个搜索功能」要把它说清楚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)回到原案例一个「桌面知识库 AI 问答」应用的最小完成定义至少应该覆盖启动命令是什么、窗口能否正常打开、文档导入路径ingest是否可用、问答路径query是否可用、数据目录如何创建与持久化、类型检查与测试是否通过。2. 在仓库根目录放一个 AGENTS.mdAGENTS.md告诉 Agent 项目的技术栈、架构约定和验证命令。第 01 讲的结论非常直接一份AGENTS.md可能比升级到更贵的模型更有效——这不是玩笑。3. 建立诊断循环并记录日志把每次失败归因到五层防御层之一任务说明层、上下文提供层、执行环境层、验证反馈层、状态管理层。用一张简单日志记录「成功/失败 失败层」几轮之后就能看出瓶颈在哪一层把精力集中在那里。七、仓库实证Project 01 把「弱 Harness vs 显式 Harness」做成了可重复实验仓库里的 Project 01Baseline vs Minimal Harness把这个修复方案做成了可重复的对照实验其任务与underspecified-task.md几乎同构——同样是「桌面应用 文档 问答」starter/task-prompt.md 全文只有一句话Build an Electron app that can show documents and answer questions.这正是「弱 Harness」版本——没有 AGENTS.md、没有 feature_list.json、没有启动命令、没有完成标准solution/ 是同一应用代码的「显式 Harness」版本补上了四件套AGENTS.md、feature_list.json、init.sh、claude-progress.md。对照实验的用法见 README.md# 1. 先用 starter弱 Harness跑一次任务 cd starter npm install # 把 task-prompt.md 的内容作为提示词交给 Claude Code / Codex # 要求 Agent 完成窗口启动、文档列表、问答面板、数据目录 # 本轮不得给 Agent 任何 solution 文件 # 2. 用 solution显式 Harness跑同一个任务 cd ../solution npm install # 要求 Agent 动代码前先读 AGENTS.md、init.sh、feature_list.json、claude-progress.md # 3. 对比两次结果任务完成了吗重试了几次Agent 是否过早宣称完成显式 Harness 具体补上了什么solution/AGENTS.md明确「写任何代码前按顺序完成 5 步」读本文件 → 读 docs/ARCHITECTURE.md → 读 docs/PRODUCT.md → 运行bash init.sh验证构建 → 读 feature_list.json并定义了严格的 Electron 四层边界main / preload / renderer / services与代码约定严格 TypeScript、具名导出、IPC 通道统一在src/shared/types.ts定义。solution/feature_list.json把「知识库应用」这个含糊目标拆成 4 个可验收特性——window-launch窗口 1200x800、contextIsolationtrue、nodeIntegrationfalse、document-list文档列表面板、question-panel问答面板、data-directory数据目录持久化——每个特性都带status字段pass/fail/not-started和可核验的evidence字段。这就是「功能列表即 Harness 原语」的落地。solution/init.sh一条命令完成npm install→npm run check类型检查→npm run build构建三件事直接消除「环境不完整」这一类失败。Definition of DoneAGENTS.md 中明确列出TypeScript 编译无错npm run check→ 应用能启动且窗口可见npm run dev→ 特性在 feature_list.json 中标记为pass并附证据 → 遵守四层边界 → 运行期无 console 错误。把 starter 的一句话需求与 solution 的完整契约放在一起正好回答了underspecified-task.md提出的全部问题启动命令npm run dev、目录结构四层边界、数据模型data-directory / PersistenceService、完成标准feature_list.json Definition of Done——一个都不缺。八、结论与关键要点underspecified-task.md虽短却是理解 Harness 工程的完美入口它用最小篇幅展示了「任务描述不充分」如何系统性触发 Agent 的失败模式而仓库中的仿真代码、检查清单和 Project 01 对照实验则给出了证据链与修复路径。模型能力与执行可靠性是两回事——同一模型在裸环境与完整 Harness 下产出天差地别Anthropic 控制实验与 OpenAI 百万行实验都证明了这一点失败时先查 Harness再换模型——换模型是最贵的选项而且多数时候根本不是模型问题每次失败都是信号——你的 Harness 有结构性缺陷找到它、修好它按五层系统排查——任务未说清、上下文不足、环境配置错、缺少验证、会话间状态丢失十次有九次问题出在这五层之一一份AGENTS.md可能比升级到更贵的模型更有效——这正是 Project 01 要你亲自验证的结论。如果想继续深入可以阅读 lecture-01 完整讲义、动手运行 failure-pattern-demo.ts或按 Project 01 实验指南 亲自跑一遍弱 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 讲座 01 的失败模式拆解与 Harness 修复实战强模型为何仍然失败learn harness engineering 讲座 01 的失败模式拆解与 Harness 修复实战 本篇文章以 learn harn为什么能力强大的 AI Agent 仍然会失败learn-harness-engineering 第一课的 Harness 工程思维入门为什么能力强大的 AI Agent 仍然会失败learn harness engineering 第一课的 Harness 工程思维入门 本教程来自 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考