【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文以 learn-harness-engineering 仓库课程 07 配套示例 scope-surface-example.md 为核心讲解范围表面Scope Surface这一 harness 工程核心原语如何把一句含糊的实现索引拆成一组可验证的原子工作单元并用机器可读文件外置全部任务状态。读完本文你将掌握 WIP1 工作流、可执行完成证据Completion Evidence的定义方法、范围漂移Scope Drift的检测手段以及如何在 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 中落地这些约束。一、一个坏的范围形状足以毁掉整次 Agent 会话课程 07 的配套示例文件docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md用一个极简的对照实验点明了整节课的核心问题任务 - 给 Electron 知识库应用添加索引功能Add indexing to the Electron knowledge app 坏的范围形状Bad scope shape - 实现索引 更好的范围形状Better scope shape - 解析导入的文档 - 将文档分割为块 - 持久化块的元数据 - 在界面中显示索引状态 - 添加重新索引动作实现索引听起来是句人话但对 Agent 而言它是一口吞不下的整块牛排。Claude Code 收到这样一条指令后会在一个会话里同时激活解析文档“分块”“建索引库”“改 UI”“写测试”等多个隐性任务正如课程主文档docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md描述的真实行为链创建一个 User 模型 → 写注册路由 → 发现需要邮件验证而顺手加邮件服务 → 发现密码要哈希而引入 bcrypt → 发现错误处理不一致而重构全局错误中间件 → 发现测试目录混乱而重组目录。六步之后每件事都只做了一半。这正是范围表面要解决的问题把宽泛需求显式分解为粒度可控、状态可追踪、完成可验证的工作单元列表。上例中的五个分解项每一项都是一个原子工作单元work unit可以独立进入进行中状态并独立验证。二、范围表面的定义DAG、四状态与机器可读文件课程 07 给出的正式定义是范围表面Scope Surface一种 DAG 结构其中每个节点是一个工作单元每条边是一个依赖关系。节点的状态被严格限制为四种not_started未开始、active进行中、blocked被阻塞、passing已通过。这意味着你要做三件事把任务拆成节点每个节点描述且只描述一个行为例如解析导入的文档。显式声明依赖边哪些节点必须先完成例如分割为块依赖解析文档持久化块元数据依赖分割为块。把整张图外置成文件用 JSON 或 Markdown 记录所有节点状态而不是只在对话里口头约定。第三点至关重要课程把它列为关键结论之一范围表面必须以文件形式外置——不能只在对话中提到而要以机器可读的格式记录在仓库中。任何新会话只要读这个文件就能立刻知道三件事哪个任务处于 active什么行为算完成哪些验证已经通过这正是仓库的 project-04-incremental-indexing 所演示的多会话连续性基础——会话之间不靠聊天记录续命靠仓库里的持久化工件续命。三、为什么要拆Overreach 与 Under-finish 的恶性循环范围表面不是洁癖而是对 Agent 注意力瓶颈的数学回应。课程 07 给出了一个简洁模型假设 Agent 的上下文容量为 C同时激活 k 个任务则每个任务平均只能分到 C/k 的推理资源一旦 C/k 低于完成单个任务所需的最小阈值所有任务都无法完成。由此定义两个孪生问题越界OverreachAgent 在单个会话中激活了超出最优数量的任务。这是可量化的——同时做 5 个功能但 0 个端到端通过就是越界。欠完成Under-finish在全部已激活任务中通过端到端验证的比例低于阈值。代码写了但测试不通过就是欠完成。二者是共生关系越界稀释注意力 → 稀释的注意力导致欠完成 → 留下的半成品代码抬高系统复杂度 → 下一个任务更容易越界。这是典型的恶性循环。用 Kanban 术语解释就是 Little 定律 L λ·W在制品 L 过高时每个任务的交付周期 W 必然拉长失败概率随之上升。课程 07 还转述了 Anthropic 工程博客与 OpenAI Codex 实践的两组证据采用小下一步策略等价于 WIP1的 Agent任务完成率比使用宽泛 prompt 的 Agent 高约 37%且 Agent 生成的代码行数与功能实际完成度呈弱负相关——写得越多完成的越少。WIP1 工作流四、分解原则原子、可验证、声明依赖对照上文的好形状示例可以提炼出三条分解准则准则一每个节点只描述单一行为。解析导入的文档只负责把文件变成结构化文本分割为块只负责切片。它们各自是一口能咽下的工作而实现索引是一整桌菜。**准则二每个节点都要有可执行的完成证据。**课程 07 反复强调完成不是代码写好了而是行为验证通过了。在功能列表中每个条目都必须挂一条验证命令例如F01: 用户注册User Registration 验证: curl -X POST /api/register -d {email:testexample.com,password:123456} | jq .status 201 状态: passing**准则三节点之间只通过显式依赖边联系。**任何新会话都能从图中判断出哪个节点现在可以做、哪个还在 blocked。配套的 next-task-template.md 为每个被挑选的任务强制填写四个字段把随手开干变成先回答四个问题# 下一任务模板Next Task Template - 当前最高优先级的特性是 - 这个特性为什么排在现在 - 什么算通过被视为有效的标准 - 此步骤期间不得修改的内容最后一项不得修改的内容尤其关键——它把顺手重构 B这类越界行为从源头上划出红线与课程里实现特性 A 时不要顺便重构特性 B的规则一脉相承。五、让机器盯住边界scope-tracker.ts 实战口头约定会失效把约束写进代码才可靠。课程 07 提供了配套实现 scope-tracker.ts它演示了单一活动特性策略如何被程序化执行。运行方式仓库根目录下npx tsx docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts从源码结构看它由三部分组成1. 数据模型scope-tracker.ts 第 16-27 行——Feature接口用status: active | pending | done标记每个特性的状态ChangeLogEntry记录每次代码变更声称归属的特性 IDinterface Feature { id: string; name: string; status: active | pending | done; } interface ChangeLogEntry { step: number; file: string; description: string; featureId: string; // 该变更声称属于的特性 }2. 示例数据第 33-52 行——四个特性F-001Search endpoint 为 active其余为 pending加一条 10 步的变更日志。日志模拟了典型的漂移过程第 1~3 步老老实实改search.ts第 4 步突然去写delete.ts的路由处理器标注// DRIFT第 5 步又去加限流中间件第 7 步甚至动了dashboard/ui.tsx——Agent 每走一步都在悄悄扩大战线。3. 追踪逻辑第 67-83 行——trackScope先筛出所有 active 特性构成白名单集合再逐条比对变更日志变更声称的featureId在白名单内记为inScope: true否则记为falsefunction 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), })); }运行后程序会打印一张带OK/DRIFT标记的变更明细表并汇总范围内变更数漂移变更数被触及的特性总数最后输出结论如果没有范围追踪器Agent 会在 3 个无关特性上悄悄工作追踪器抓住了这次漂移并强制执行了单一活动特性策略。这个示例的价值在于把抽象的范围边界变成了可运行的检查器——它正是 WIP1 约束的机械形态。同样的思路也出现在仓库的真实项目 harness 中project-04 解决方案里的 check-architecture.sh 用 grep 扫描源码强制三条边界——renderer 层不得 importfs/path/os/child_process等 Node 核心模块、service 层不得 import Electron IPC、service 与 main 层不得 import React任一违反都会累计违规数并最终以非零退出码失败第 78-85 行。架构边界和任务范围边界虽然对象不同但机制同源把约定降级为可执行检查让失败发生在 CI 或提交前而不是发生在用户验收时。六、在真实 Harness 中落地Project 04 的完整配置把范围表面的理念落到可运行的 harness 上仓库的 project-04 解决方案 给出了完整参考实现。其 AGENTS.md 是典型的工程化写法核心规则可直接照搬## 工作规则Working Rules - 一次只做一个特性Work on one feature at a time - 不要因为添加了代码就把特性标记为完成Do not mark a feature complete just because code was added - 保持变更在所选特性的范围内除非阻塞问题迫使你做窄幅的支撑性修复 - 实现过程中不要悄悄修改验证规则 - 优先采用持久的仓库工件而不是聊天摘要这份文件的完成定义Definition Of Done把完成标准写得可判定目标行为已实现、要求的验证确实运行过、证据已记录在最终总结或被任务触及的项目文档中、仓库能按标准启动路径重新启动、scripts/check-architecture.sh零违规通过。每一条都不是形容词而是可以被下一会话或审查者逐项核对的布尔条件。配套的 clean-state-checklist.md 则把收尾工作做成复选框清单构建通过npm run check、npm run build、架构检查通过、应用可启动、结构化日志正常输出、导入/索引/QA 事件可观测、无空分块、git 状态无意外文件、无敏感数据入库——这就是每个会话留下干净状态的可执行版本。关于索引功能本身project-04 的架构文档 docs/ARCHITECTURE.md 展示了与示例任务对应的真实分层rendererReact UI→ preloadcontextBridge 桥→ mainIPC handler→ services业务逻辑→ persistence文件系统。索引相关的 IPC 通道indexing:start、indexing:status、indexing:chunks清晰定义了启动索引查询索引状态获取文档块三个边界——这与范围表面示例中解析文档 / 分割块 / 持久化元数据 / 显示状态 / 重新索引的五个分解单元恰好一一对应可见示例并非虚构而是对真实功能面的提炼。七、监控完成率VCR 作为流量闸门范围表面外置之后还需要一个持续运转的仪表盘。课程 07 给出的指标是验证完成率VCR, Verified Completion Rate 已验证任务数 / 已激活任务数。当 VCR 1.0 时harness 应阻止新的任务激活。也就是说只有当下所有已激活任务都拿到了可执行验证的通过证据才允许从队列里解锁下一个任务——这正是上文中 WIP1 流程图里Verify --|pass| Commit分支的量化形式。课程 07 的真实案例对比了两种模式无约束模式下 Agent 在会话 1 同时激活 5 个特性、12 个文件约 800 行代码、端到端测试通过率仅 20%会话 3 结束时 8 个特性只完成 3 个WIP1 模式下 Agent 会话 1 只做用户注册、4 个文件约 200 行、测试 100% 通过会话 4 结束时 8 个特性完成 7 个第 8 个被外部依赖阻塞。总代码更少800 vs 1200 行完成率却是 87.5% vs 37.5%——少做但做完完胜多做但做一半。八、关键要点与配套练习关键要点WIP1 是 Agent harness 的默认安全设置——做完一个再开始下一个不要尝试并行。完成证据必须可执行——代码看起来没问题不算数curl 返回 201才算数。范围表面必须外置为文件——以机器可读格式记录在仓库中而非只在对话里口头提及。越界与欠完成共生——解决其一另一个也随之缓解。范围表面是 DAG——节点是工作单元边是依赖状态只有not_started/active/blocked/passing四种。配套练习源自课程 07任务原子化选一个宽泛需求如实现一个用户管理系统拆成至少 5 个原子工作单元为每个单元写出 (a) 单一行为描述、(b) 可执行验证命令、(c) 依赖关系并检查分解是否满足 WIP1 约束。对照实验同一项目跑两遍——一遍不加约束一遍强制 WIP1对比验证完成率、总代码行数与有效代码占比。完成证据审计检查最近一次 Agent 运行的产出把每处代码变更归类为已完成行为未完成行为或脚手架为每个未完成行为补上缺失的验证命令。九、结语范围表面示例虽然只有几行却是课程 07 全部工程思想的浓缩含糊的任务指令会让 Agent 在越界—欠完成—复杂度上升—再次越界的循环里空转而显式分解 状态外置 可执行验证 WIP1 约束把让 Agent 少做一点、做完一点从一句口号变成了仓库里可读、可运行、可审计的工程事实。从 scope-surface-example.md 的分解示范到 scope-tracker.ts 的漂移检测再到 project-04 的 AGENTS.md、check-architecture.sh 与 clean-state-checklist.md这套方法论在仓库里形成了从理论到代码的完整闭环——这正是 harness 工程区别于提示词调优的本质把边界画进仓库而不是画进对话。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 实战用「范围面Scope Surface」给 Agent 的索引任务划定边界learn harness engineering 实战用「范围面Scope Surface」给 Agent 的索引任务划定边界 导读 当 Agent 接为 Agent 划定任务范围边界Scope Surface 分解与 WIP1 实操指南learn-harness-engineering 实战解析为 Agent 划定任务范围边界Scope Surface 分解与 WIP1 实操指南learn harness engineering 实战解析 本文为 Agent 划定清晰任务边界learn-harness-engineering 中 WIP1 与范围控制实战指南为 Agent 划定清晰任务边界learn harness engineering 中 WIP1 与范围控制实战指南 你让 Claude Code“给这个项上一篇如何提升ApexCharts.js图表性能数据处理效率优化指南下一篇Yii 2: The Fast, Secure and Professional PHP Framework 代码质量检测PHPCS 与 PHPMD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考