【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇技术指南围绕本仓库 Aula 07第 07 讲Defina Limites Claros de Tarefa para os Agentes为智能体划定清晰任务边界展开。它剖析了 AI 智能体过度越界overreach与欠完成under-finish这对共生问题并给出 WIP1、可执行完成证据、外部化范围表面、已验证完成率VCR四条可落地的 Harness 治理方案。读完你将掌握如何在CLAUDE.md/AGENTS.md中为智能体编写工作规则如何把范围漂移变成机器可检测的违规以及如何用本仓库提供的scope-tracker.ts等源码佐证这些原则的工程实现。引言为什么能干的智能体反而交不出可用功能你让 Claude Code 给这个项目加用户认证它开始改数据库 schema、写路由、动前端组件然后——既然都动手了——顺手重构错误处理中间件。两小时后你回来检查12 个文件被修改新增 800 行代码却没有一个功能能端到端跑通。这是几乎所有长时运行long-running编码智能体的通病它们天生带有再顺手多做一点的冲动——看到相关联的东西就在同一流程里一起处理。问题在于同时做太多件事几乎可以保证没有任何一件能做得好。正如本讲docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md指出的Anthropic 的工程博客Effective Harnesses for Long-Running Agents明确表示当提示词过于宽泛时智能体倾向于同时启动多件事而不是先完成一件再做下一件OpenAI 的 Codex 工程实践也得出了相同结论——没有显式范围控制的任务完成率会急剧下降。这不是模型问题而是 Harness 问题——你没有划出那条边界。注意力是有限资源C/k 的数学这不是比喻是数学。假设智能体的上下文能力为 C它同时激活了 k 个任务那么每个任务平均只能分到 C/k 的推理资源。当 C/k 低于完成单个任务所需的最小阈值时一个都完不成。Claude Code 的真实行为很有说服力。让它加用户注册功能它可能会创建 User 模型编写注册路由发现需要邮箱验证于是加一个邮件服务发现密码需要加密引入 bcrypt发现错误处理不一致重构全局错误中间件发现测试文件结构混乱重组目录六步之后每一步都只做了一半没有端到端验证半成品代码之间产生复杂耦合下一个接手会话将彻底迷失。Anthropic 的实验数据直接印证了这一行为采用小步下一步small next step策略等价于 WIP1的智能体任务完成率比使用宽泛提示词的智能体高 37%。更有意思的是智能体生成的代码行数与功能实际完成度呈弱负相关——写的代码越多完成的功能越少。这是贪多嚼不烂的数据级证明。WIP1 工作流唯一在途任务WIP 是 Kanban看板方法论中的Work-in-Progress Limit在制品限制。对智能体而言最安全的默认值是WIP1一次只允许一个任务处于激活状态完成一个再开始下一个。本讲的流程如下为什么 WIP1 能奏效因为推理预算被集中而非摊薄核心概念本讲的四个关键术语Overreach越界智能体在单个会话中激活的任务数超过理想值。这不是主观判断而是可量化的同时做 5 个功能、却没有一个通过端到端验证就是overreach。Under-finish欠完成通过端到端验证的任务数占全部已激活任务数的比例低于预期阈值。代码写了但测试没过就是under-finish。完成证据Completion Evidence任务从进行中转为已完成所必须满足的、可验证的条件。没有它智能体会用代码看起来没问题冒充行为通过了测试。范围表面Scope Surface一种 DAG 结构每个节点是一个工作单元边表示依赖关系状态被限制为四种not_started、active、blocked、passing。完成压力Completion PressureHarness 通过 WIP 限制与完成证据要求施加的约束力迫使智能体先完成当前任务再开始新任务。Overreach 与 Under-finish 是一枚硬币的两面这两个问题并不独立而是互相强化overreach稀释注意力 → 注意力被稀释导致under-finish→ 留下的半成品代码增加系统复杂度 → 又进一步诱发下一个任务的overreach。这是一个恶性循环。用 Kanban 的语言来说利特尔法则Littles Law告诉我们 L λ × W当在制品 L 过高同时在做太多事时每个任务的前置时间 W 必然变长。对智能体意味着每个功能从开始到已验证完成耗时更长失败概率随之上升。这也是人类世界的老问题——Steve McConnell 在Rapid Development中记录了范围蔓延scope creep是项目失败的首要原因。但人类至少保有我已经做得够多了的直觉而智能体完全没有对模型来说生成下一个念头几乎零成本——写一句既然都在这了顺便把这个也修了只消耗几个 token但每一次额外改动都在进一步稀释智能体的注意力。正确的做法四条可落地的 Harness 规则1. 强制 WIP1这是最直接、最有效的方法。在你的 Harness 中明确告知智能体任何时刻只允许一个任务处于active状态。在 Claude Code 的CLAUDE.md或 Codex 的AGENTS.md中写入## 工作规则 - 一次只做一个功能 - 只有当前功能通过端到端验证后才能开始下一个功能 - 不要在实现功能 A 时顺手重构功能 B这套规则在本仓库的实践项目中有完整落地。参考 projects/project-04/solution/AGENTS.md 的 Working Rules 一节## Working Rules - Work on one feature at a time. - Do not mark a feature complete just because code was added. - Keep changes within the selected feature scope unless a blocker forces a narrow supporting fix. - Do not silently change verification rules during implementation. - Prefer durable repo artifacts over chat summaries.注意最后一条优先使用仓库中的持久化产物而不是聊天摘要——这正是外部化范围表面第 3 条在真实项目中的体现。2. 为每个任务定义显式的完成证据完成不等于代码写完了而是行为验证通过了。在功能列表中每个条目都要带一条验证命令F01: 用户注册 验证: curl -X POST /api/register -d {email:testexample.com,password:123456} | jq .status 201 状态: passing完成证据必须可执行——代码看起来没问题不算数curl 返回 201才算数。project-04 的 Definition Of Done 把这一点固化成了验收标准目标行为已实现、要求的验证确实运行过、证据被记录、仓库可从标准启动路径重启、架构检查脚本零违规。3. 外部化范围表面用一个机器可读的文件JSON 或 Markdown记录所有任务的状态。任何新会话读这个文件就能立刻知道哪个任务处于激活状态什么行为算完成哪些验证已经通过本讲的配套模板 next-task-template.md 给出了最小结构# 下一个任务模板 - 当前最高优先级功能 - 为什么下一个是这个功能 - 什么算通过 - 本步骤中绝不能改动的内容其中本步骤中绝不能改动的内容是对overreach的显式约束——直接告诉智能体哪些区域在这个工作单元里是禁区。而 scope-surface-example.md 展示了范围表面的原子化拆解示范以本仓库 Electron 知识库应用加索引为例任务 - 为 Electron 知识库应用添加索引 坏的范围形状 - 实现索引 好的范围形状 - 解析导入的文档 - 将文档切分为 chunk - 持久化 chunk 元数据 - 在 UI 中暴露索引状态 - 添加重新索引动作注意坏的形状与好的形状之间的区别前者是一个无法验证的大黑盒后者是五个各自携带完成证据的原子工作单元。4. 监控已验证完成率VCRHarness 应持续跟踪 VCRVerified Completion Rate 已验证任务数 / 已激活任务数并在 VCR 1.0 时阻止激活新任务。这把完成度从模糊感觉变成了硬性门禁。源码佐证scope-tracker.ts 如何捕获范围漂移本讲的代码示例 scope-tracker.ts 提供了一个可运行的演示它读取功能列表与变更日志强制执行单激活功能策略——给定一份变更日志标记任何超出激活功能范围的改动演示范围漂移是如何发生的、追踪器又是如何抓住它的。核心数据结构是两个接口对应源码 scope-tracker.tsinterface Feature { id: string; name: string; status: active | pending | done; } interface ChangeLogEntry { step: number; file: string; description: string; featureId: string; // 该改动声称属于的功能 }示例数据中F-001搜索端点为active其余三个功能为pendingscope-tracker.ts。变更日志则模拟了智能体的真实行为第 13 步还在做搜索路由第 4 步就漂移到了删除端点F-002第 5 步又漂到限流中间件F-003第 7 步再漂到用户面板F-004第 9 步又回到F-002scope-tracker.ts。追踪逻辑本身非常朴素——这正是它的优雅之处trackScope先把所有active功能的 ID 收集成一个集合然后逐条检查每个变更的featureId是否属于该集合scope-tracker.tsfunction trackScope( featureList: Feature[], changes: ChangeLogEntry[] ): ScopeCheckResult[] { const activeFeatures featureList.filter((f) f.status active); const activeIds new Set(activeFeatures.map((f) f.id)); ... return changes.map((change) ({ ... inScope: activeIds.has(change.featureId), ... })); }运行方式仓库提示的命令路径按仓库根目录调整npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts输出会生成一张带OK/DRIFT标记的变更明细表并汇总总变更数、激活范围内F-001的变更数、范围外漂移变更数、被触碰的功能总数最后逐一列出漂移功能及其未授权改动数量scope-tracker.ts。这个示例印证了本讲的核心理念没有范围追踪器时智能体悄无声息地做了多个无关功能有了追踪器漂移立即被标记单激活功能策略得以强制执行。而禁止静默更改验证规则改动必须留在所选功能范围内这类约束正是 projects/project-04/solution/AGENTS.md 中可执行化的同一原则。真实案例8 个功能的 REST API 项目对照实验一个含 8 个功能的 REST API 项目对比两种策略无约束模式智能体在第 1 个会话同时激活 5 个功能产出约 800 行代码、分散在 12 个文件。端到端测试通过率仅20%——只有用户注册可用。其余 4 个功能的问题包括数据库 schema 建了但缺少校验逻辑、路由定义了但返回格式错误。到第 3 个会话结束8 个功能只完成 3 个。WIP1 模式智能体在第 1 个会话只做用户注册产出约 200 行代码、分散在 4 个文件。端到端测试100% 通过提交的是干净且经过验证的实现。到第 4 个会话结束8 个功能完成 7 个第 8 个被外部依赖阻塞。结果总代码更少800 行对 1200 行但有效代码更多完成率87.5% 对 37.5%。对照实验的复现方法同样写进了本讲练习同一项目跑两遍——一遍无约束、一遍强制 WIP1——对比已验证完成率、代码总行数与有效代码占比。配套治理工具clean-state-checklistWIP1 原则要长期生效还需要配套的仓库健康检查。project-04 的 clean-state-checklist.md 给出了会话结束/提交前检查清单可视为完成证据的扩展形态构建npm run check无类型错误、npm run build成功架构bash scripts/check-architecture.sh零违规、渲染层无fs/path导入、服务层无 Electron IPC、主进程与服务层无 React 导入运行时应用可无错启动、结构化日志正常输出、文档导入与索引可用、QA 能返回带引用的回答数据完整性索引无空 chunk、QA 历史跨重启持久化、文档元数据与真实文件一致仓库git status 无意外文件、无敏感数据暂存、最终摘要记录当前状态/验证运行/未解决风险。这份清单的价值在于它把完成从一次性的主观判断变成了每次提交前可勾选的客观门禁——与本讲完成证据必须可执行的主张一脉相承。主要结论WIP1 是智能体 Harness 最安全的默认配置——先完成一个再开始下一个不要尝试并行化。完成证据必须可执行——代码看起来没问题不算数curl 返回 201才算数。范围表面必须外部化为文件——不能只在对话中提及而要写成仓库内机器可读的持久化产物。Overreach 与 under-finish 是共生现象——解决一个另一个也会随之改善。做得少但完成永远胜过做得多但半途而废——智能体生成的代码行数与功能完成率呈负相关。质量永远胜过数量。练习任务原子化选一个宽泛需求例如实现用户管理系统拆成至少 5 个原子工作单元。每个单元写明(a) 单一行为描述、(b) 一条可执行验证命令、(c) 依赖关系。然后检查该分解是否满足 WIP1 约束——可对照 scope-surface-example.md 的好形状标准。对照实验同一项目跑两遍——一遍无约束、一遍强制 WIP1。对比已验证完成率、代码总行数与有效代码占比。完成证据审计回看一次最近的智能体运行输出把每个代码改动归类为已完成行为未完成行为或支撑性脚手架scaffolding并为每个未完成行为补上缺失的验证命令——可借助 scope-tracker.ts 的输出格式建立审计表。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐用 Next Task Template 为 AI Agent 划定单任务边界在 learn-harness-engineering 中落地 WIP1 与完成证据用 Next Task Template 为 AI Agent 划定单任务边界在 learn harness engineering 中落地 WIP1 与完learn-harness-engineering 实战用「下一任务模板」为 Agent 划定任务边界落实 WIP1learn harness engineering 实战用「下一任务模板」为 Agent 划定任务边界落实 WIP1 本篇文章以 learn harnes为 Agent 划定任务边界用 WIP1 与完成证据根治 Overreach 与 Under-finishlearn-harness-engineering 第七讲为 Agent 划定任务边界用 WIP1 与完成证据根治 Overreach 与 Under finishlearn harness engineerin上一篇探秘Electrum Personal Server自托管的比特币轻钱包解决方案下一篇终极信号处理学习资源Python-for-Signal-Processing项目的Notebook使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
