【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本讲是 learn-harness-engineering 系列中关于「任务边界控制」的核心一课直接回答了工程师们最常遇到的一个问题——为什么能力很强的 Agent 在接到一个简单需求后会改出一堆文件却没有任何一个功能端到端可用。本文以第七讲的完整内容为主体结合仓库中的scope-tracker.ts漂移检测器、任务模板以及 project-04 的真实工程实践系统讲解越界与收尾不足的数学根源、WIP1 工作流、可执行完成证据、范围表面外部化与 VCR 监控四条落地规则读完即可在自己的 harness如 CLAUDE.md / AGENTS.md中落地一套可验证的任务边界控制方案。问题场景一句加上用户认证换来 800 行无法工作的代码你对 Claude Code 说给这个项目加上用户认证它随即开始改数据库 schema、写路由、改前端组件——顺带还把错误处理中间件重构了一遍。两个小时后你回来检查12 个文件被修改、800 行新代码却没有一个功能能端到端跑通。Agent 天生带着一种顺手多做一点的冲动看到相关的东西就顺路处理掉就像一个人本想去超市买一瓶酱油出来时却推着满满一购物车。问题是人类买多了最多只是多花钱而同时做太多事的 Agent 几乎注定一件事都做不好。Anthropic 的《Effective harnesses for long-running agents》工程博客明确指出当 prompt 过于宽泛时Agent 倾向于同时启动多件事而非先把一件事做完。OpenAI 的 Codex 工程实践也得出了相同结论——没有显式范围控制的任务完成率会急剧下滑。这不是模型问题而是 harness 问题你没有画下边界。根因注意力是有限的资源这并非比喻而是数学。假设 Agent 的上下文容量为 C它同时激活了 k 个任务那么每个任务平均只能分到C/k的推理资源。当 C/k 低于完成单个任务所需的最低阈值时一个都完不成。就像胃容量有限一次塞进十个汉堡结果只是消化不良十次。Claude Code 的真实行为极具说服力。你让它添加用户注册它可能会创建 User 模型编写注册路由意识到需要邮箱验证于是加上邮件服务发现密码需要哈希于是引入 bcrypt注意到错误处理不一致于是重构全局错误中间件发现测试文件结构混乱于是重新整理目录。六步之后每一步都只做了一半没有端到端验证半成品代码之间耦合复杂下一个接手收拾残局的会话会完全迷失方向。就像同时煮六道菜的人——每道菜都在锅里但没有一道上桌全都糊了。Anthropic 的实验数据直接支持这一点采用小步下一步策略等价于 WIP1的 Agent任务完成率比使用宽泛 prompt 的 Agent高出 37%。更有意思的是Agent 生成的代码行数与实际功能完成度呈弱负相关——代码写得越多功能完成得越少。贪多嚼不烂被数据证实了。WIP1 工作流Kanban 方法论中的WIP 限制Work-in-Progress Limit是解决这一问题的核心武器限制同时在飞行中的任务数量。对 Agent 而言WIP1 是最安全的默认值——先完成一个再启动下一个。从特征队列到提交的完整闭环如下推理预算的分配对比则解释了为什么 WIP1 能提高完成率核心概念概念定义与要点越界OverreachAgent 在单个会话中激活了超出最优数量的任务。这是可量化、可判定的——做了 5 个功能端到端通过 0 个就是越界。收尾不足Under-finish在所有激活任务中通过端到端验证的任务比例低于阈值。代码写了但测试不通过就是收尾不足。WIP 限制Work-in-Progress Limit源自 Kanban限制同时进行中的任务数量。对 Agent 而言 WIP1 最安全——像自助餐一样别把盘子堆满吃完一盘再回来。完成证据Completion Evidence任务从进行中变为已完成必须满足的可验证条件。没有它Agent 会用代码看起来没问题替代行为测试通过。范围表面Scope Surface一种 DAG 结构每个节点是一个工作单元边是依赖关系。状态仅限四种not_started、active、blocked、passing。完成压力Completion Pressureharness 通过 WIP 限制和完成证据要求施加的约束力迫使 Agent 在启动新任务前先完成当前任务。越界与收尾不足是共生的这两个问题并非独立存在而是互相强化越界稀释注意力 → 稀释的注意力导致收尾不足 → 留下的半成品代码增加系统复杂度 → 复杂度又驱动下一个任务进一步越界。这是一个恶性循环。用 Kanban 术语表达Little 定律 L λ × W。如果在制品 L 过高同时做太多事每个任务的交付周期 W 必然拉长。对 Agent 而言这意味着每个功能从开始到验证完成耗时更长失败概率随之增大。这也是人类世界的古老问题——Steve McConnell 在《Rapid Development》中记录了范围蔓延scope creep是项目失败的首要原因。但人类至少还有我做得够多了的直觉Agent 没有生成下一个想法几乎不消耗模型额外的 token——顺手把这个也修了几乎零边际成本——但每一次额外修改都会稀释 Agent 的注意力。正确做法四条落地规则规则 1强制 WIP1这是最直接、最有效的方法。在 harness 中明确告诉 Agent任何时刻只允许一个任务处于 active 状态。在 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 中写入## 工作规则 - 一次只处理一个功能 - 当前功能通过端到端验证后才启动下一个功能 - 实现功能 A 时不要顺手重构功能 B仓库中的 project-04 starter 的 AGENTS.md 就是这一规则的实战样本其 Rules 部分只有两行Work on one feature at a time.和Run npm run check before committing.。而在 project-04 solution 的 AGENTS.md 中规则被扩充为完整的工作纪律一次只做一个功能Work on one feature at a time不要因为代码被添加了就标记功能完成除非被阻塞因素迫使否则将修改保持在选定功能范围内实现过程中不得静默修改验证规则优先使用持久的仓库产物而非聊天摘要。规则 2为每个任务定义可执行的完成证据完成不是代码写完了而是行为验证通过了。在功能列表中每个条目都必须配一条可执行的验证命令F01: 用户注册 验证: curl -X POST /api/register -d {email:testexample.com,password:123456} | jq .status 201 状态: passing仓库为此提供了配套模板 next-task-template.md在启动每个任务前要求 Agent 显式回答四个问题# 下一个任务模板 - 当前优先级最高的功能 - 该功能为何排在队列中 - 什么才算被接受通过标准 - 此步骤期间不得改动的内容最后一项此步骤期间不得改动的内容正是完成压力的来源——它把禁止越界从口头约束变成了每个会话开始时的强制声明。规则 3把范围表面外部化为文件用机器可读的文件JSON 或 Markdown记录所有任务状态。任何新会话读取该文件即可立即知道哪个任务处于活动状态什么行为算完成哪些验证已经通过仓库中的 scope-surface-example.md 演示了范围表面的好坏写法对比。任务是给 Electron 知识库应用添加索引功能糟糕的范围形状实现索引——这是一个无法验证、无法 WIP1 化的巨型任务更好的范围形状解析导入的文档将文档切分为块持久化块元数据在界面中显示索引状态添加重新索引动作。每一个子项都是原子工作单元拥有单一行为定义可以独立验证并满足 WIP1 约束。规则 4持续监控已验证完成率VCRharness 应持续跟踪VCRVerified Completion Rate 已验证任务数 / 已激活任务数并在VCR 1.0 时阻止新的任务激活。这一指标把越界行为变成了可量化的门禁只要存在未通过验证的任务Agent 就无权打开新任务。仓库配套漂移检测器与范围跟踪规则 14 如何落地为代码仓库在 code 目录 中提供了一个可以直接运行的最小实现——scope-tracker.ts。该脚本的核心思想是读取功能列表 变更日志强制执行单一活动功能策略。它定义了Feature接口状态仅限active/pending/done和ChangeLogEntry接口每条变更声明自己属于哪个 featureId然后通过trackScope()将每条变更与当前活动功能比对标记inScope或DRIFT。脚本内置了一份非常真实的变更日志展示了 Agent 是如何逐步漂移的step 1-3 : 修改 src/routes/search.ts —— F-001活动功能OK step 4 : 修改 src/routes/delete.ts —— F-002 // DRIFT step 5 : 修改 src/middleware/rate-limit.ts —— F-003 // DRIFT step 6 : 修改 src/routes/search.ts —— F-001回归OK step 7 : 修改 src/dashboard/ui.tsx —— F-004 // DRIFT step 8 : 修改 src/routes/search.ts —— F-001回归OK step 9 : 修改 src/routes/delete.ts —— F-002 // DRIFT step 10 : 修改 src/routes/search.ts —— F-001补测试OK运行后脚本会输出一张变更明细表用标记越界项并汇总范围外变更数DRIFT触及的功能总数等指标最后输出结论没有范围跟踪器时Agent 会在不知不觉中并行处理多个无关功能跟踪器捕获这种漂移并强制执行单一活动功能策略。运行方式从仓库根目录npx tsx docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts这段代码直接印证了本讲的核心主张越界不是模型缺陷而是缺少边界检查机制的 harness 缺陷——只要给 Agent 一条可判定的规则只有活动功能内的变更才算合法和一份可审计的日志漂移就无所遁形。真实世界案例8 个功能的 REST API 对比实验一个包含 8 个功能的 REST API 项目对两种策略进行对比自助餐模式无约束Agent 在会话 1 同时激活 5 个功能在 12 个文件中产出约 800 行代码。端到端测试通过率20%——只有用户注册可用。其余 4 个功能数据库 schema 建好了但缺少验证逻辑路由定义了但返回格式错误。到会话 3 结束时8 个功能只完成 3 个。单盘模式WIP1Agent 在会话 1 只做用户注册在 4 个文件中产出约 200 行代码。端到端测试100% 通过提交了一个干净、可验证的实现。到会话 4 结束时8 个功能完成 7 个第 8 个被外部依赖阻塞。结果对比总代码更少800 vs 1200 行但更有效完成率87.5% vs 37.5%。一次只咬一口反而吃得更多。在真实仓库中的印证Project 04 的边界约束实践本讲配套的练习项目是 project-04-incremental-indexing仓库中的实际工程目录为 projects/project-04名为Runtime Feedback and Structural Control。它演示了如何把本讲的四条规则真正写进 harness强制 WIP1starter 的 AGENTS.md 直接写入一次只处理一个功能完成证据 不静默改规则solution 的 AGENTS.md 明确规定Do not mark a feature complete just because code was added不要因为写了代码就标记完成并在 Definition of Done 中要求所需验证确实运行过证据记录在最终总结或任务触及的项目文档中范围表面 架构边界solution 通过 scripts/check-architecture.sh 与 docs/ARCHITECTURE.md 强制渲染层、服务层、预加载层之间的边界——任何跨层导入都被脚本拦截这就是范围表面在代码层面的落地形态可观测性支撑验证solution 的src/services/logger.ts提供 JSON 结构化日志让索引块数、内容长度、QA 置信度等验证指标可被实时观测从而支撑 VCR 判定。从源码结构看这个项目把本讲的理念边界约束 完成证据 可验证状态完整地编码进了 harness 文件与守护脚本是四条规则的端到端示范。要点总结WIP1 是 Agent harness 的默认安全设置——先完成一个再启动下一个不要试图并行化。一口吃不成胖子。完成证据必须是可执行的——代码看起来没问题不算数curl 返回 201才算数。范围表面必须外部化为文件——不能只停留在对话中要写入仓库的机器可读格式JSON / Markdown。越界与收尾不足是共生的——解决一个另一个也随之缓解。做得少但做完永远胜过做得多但半途而废——Agent 的代码行数与功能完成率呈负相关。质量永远胜过数量。延伸阅读本讲的核心论断来自两个公开来源可进一步查阅Anthropic 的《Effective harnesses for long-running agents》工程博客——对小步下一步策略等价于 WIP1的详细讨论是本文 37% 完成率提升数据的出处OpenAI 的《Harness Engineering》——对 harness 工程实践的系统性论述David Anderson《Kanban: Successful Evolutionary Change》——WIP 限制的经典出处Steve McConnell《Rapid Development》——关于范围蔓延是项目失败首要原因的实证数据。仓库内对应内容可继续阅读本讲的 英文版 与 中文版以及 code 目录 中的三个配套文件。练习任务原子化挑选一个宽泛需求例如实现一个用户管理系统拆解为至少 5 个原子工作单元。对每个单元明确(a) 单一行为定义(b) 可执行的验证命令(c) 依赖关系。最后检查拆分是否满足 WIP1 约束。对比实验在同一个项目上运行两次——一次不加约束一次强制 WIP1。对比三项指标已验证完成率、总代码行数、有效代码占比。完成证据审计回顾最近一次 Agent 运行的产出将每处代码变更分类为已完成行为未完成行为或脚手架。对每个未完成行为补充缺失的验证命令。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐为 Agent 划定任务边界用 WIP1 与完成证据根治 Overreach 与 Under-finishlearn-harness-engineering 第七讲为 Agent 划定任务边界用 WIP1 与完成证据根治 Overreach 与 Under finishlearn harness engineerinAgent 任务边界工程用 WIP1 与可执行验收证据根治 Overreach 与 Under-finishlearn-harness-engineering 第 07 讲Agent 任务边界工程用 WIP1 与可执行验收证据根治 Overreach 与 Under finishlearn harness engineeri给 Agent 划定清晰任务边界learn-harness-engineering 第 07 讲——Why Agents Overreach and Under-Finish给 Agent 划定清晰任务边界learn harness engineering 第 07 讲——Why Agents Overreach and Unde上一篇三步让你的老旧Mac焕发新生OpenCore Legacy Patcher终极指南下一篇PaddleOCR Linux GPU/CPU KL离线量化训练与推理全流程测试指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考