Harness 工程第 08 讲：用功能列表（Feature List）约束 Agent 的作业边界

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本讲来自 learn-harness-engineering 课程的 日文原版讲稿配套代码位于 code/实践项目见 项目 04增量索引与运行时反馈。导读当你让 Agent 构建一个电商网站它回来说“done”但购物车的结算按钮什么都没接——问题不在于 Agent 能力不足而在于你从未告诉它“done”到底意味着什么。本讲围绕 harness 工程的核心概念——功能列表feature list展开为什么它不只是给人类看的备忘而是整个 harness 的“背骨”如何用“行为描述 验证命令 当前状态”三要素定义机器可读的功能条目以及如何让调度器、验证器、交接报告器围绕它协同工作。读完你将掌握一套可直接落地的功能列表 JSON 格式、状态机与 pass-state gating 策略并用本仓库附带的feature-list-validator.ts校验器立刻实践。一、Agent 并不天生知道“完成”是什么意思无论是 Claude Code 还是 Codex模型都不会自动理解你口中“完成”的含义。你说“添加购物车功能”模型的默认解释可能是“写出 Cart 组件和 addToCart 方法”而你真正想要的是“用户可以浏览商品、加入购物车、并端到端地完成结账”。没有功能列表时这个理解落差会一直存在Agent 最终只能采用自己的隐式标准——通常是“代码没有明显的语法错误”。这正是原文档中那个经典反例让朋友“买点水果”他却买回了柠檬因为他的“水果”和你的“水果”不是同一个集合。要消除这种歧义你需要的是端到端的行为验证而不是一句模糊的指令。再看一条典型的进度备忘Did user auth, shopping cart mostly done, still need payments新开一个 Agent 会话它能从这行文字回答出以下问题吗“mostly done”到底完成了什么购物车通过了哪些测试支付功能被什么阻塞答案全是“没人知道”。就像对医生说“我最近肚子疼不过还行”医生无法据此开药。结果就是新会话花 20 分钟猜测项目状态甚至把已完成的功能重新实现一遍。原文档引用的行业数据显示好的进度记录能把会话启动时的诊断时间减少 60%80%。二、功能状态机一行功能条目 两段流转功能列表之所以能成为 harness 的“背骨”是因为它把模糊的进度描述收敛成了机器可读的状态机。原文档给出了两张 mermaid 图这里完整复述并解读。第一张图说明“什么才是一条可用的功能行”第二张图说明“harness 如何驱动功能流转”注意第二张图的回边Active -- Agent即验证失败后 Agent 回到该条目继续工作直到验证通过为止而Passing -- Handoff表示只有通过验证的功能才会被写入交接报告。这张图事实上定义了整个 harness 的循环调度 → 作业 → 验证 → 状态迁移 → 交接。三、核心概念六条你必须内化的原则原文档把功能列表的理论内核浓缩为六条核心概念逐条展开如下功能列表是 harness primitive原语它不是“可选的规划工具”而是其他所有 harness 组件依赖的基础数据结构。就像数据库表结构一样你不可能说“主键就省了吧”。三要素结构每个功能条目都是(行为描述, 验证命令, 当前状态)的三元组。行为告诉 Agent 做什么验证告诉它什么算完成状态告诉它现在进展到哪。缺任何一个条目都不完整——如同一把三脚椅少了一条腿。状态机模型每个条目只有not_started、active、blocked、passing四种状态且状态迁移由 harness 控制Agent 不能随意改动。Pass-state gating通过态门控功能从active晋升到passing的唯一途径是验证命令成功执行。该迁移不可逆——一旦passing就回不去了就像考试及格后不能事后改分。Single source of truth单一事实来源所有“该做什么”的信息都必须出自这一个功能列表不许在功能列表与会话历史之间制造矛盾。Back-pressure背压尚未通过的功能数量就是 harness 施加给 Agent 的压力。压力归零 项目完成。四、为什么功能列表必须是“原语”而不是“文档”文档是给人读的原语是给系统执行的。文档可以被无视原语则无法被绕过。可以类比数据库的触发器约束与应用层检查的区别前者由数据库引擎强制任何 SQL 都跳不过后者依赖应用代码写得正确可能被意外绕过。作为 harness 原语的功能列表扮演的就是数据库层约束的角色——Agent 无法绕过它。具体来说功能列表被四个 harness 组件消费组件职责类比Scheduler调度器读取状态挑选下一个not_started功能工厂的生产计划系统Verifier验证器执行验证命令裁决是否允许状态迁移质量检验员Handoff reporter交接报告器依据功能列表自动生成会话交接摘要自动化的交班报告Progress tracker进度跟踪器汇总状态分布给出项目健康度指标仪表盘五、正确做法四个步骤落地功能列表步骤 1定义最小功能列表格式不需要复杂系统结构化 Markdown 或 JSON 文件即可关键是每个条目具备三要素。原文档给出的最小 JSON 示例{ id: F03, behavior: POST /cart/items with {product_id, quantity} returns 201, verification: curl -X POST http://localhost:3000/api/cart/items -H Content-Type: application/json -d {\product_id\:1,\quantity\:2} | jq .status 201, state: passing, evidence: commit abc123, test output log }字段语义说明id功能唯一标识用于跨会话引用如 F03、qna-001behavior可验证的行为描述越具体越好端点 参数 期望返回verification一次可执行的检查命令或检查步骤列表这是“完成”的客观判据state当前状态取值限定在not_started / active / blocked / passingevidence证据引用例如 commit hash、测试输出日志证明该状态有据可查。仓库中的真实项目正是这样实践的。例如 project-01 的 feature_list.json 里每条功能都包含id、name、description、status取值为pass/fail/not-started、evidence与testedAt时间戳project-02 的 feature_list.json 则进一步体现了“跨会话继承”前四条功能直接写evidence: Carried over from P1 -- verified working用一条可验证的证据链说明“上一项目已验证本会话直接继承”这正是功能列表支撑多会话连续性的实际用法。本讲配套代码目录里还有一个真实的验证命令集合示例 feature_list.json其verification字段不是单条命令而是一组可勾选的人工/自动化检查步骤例如“导入 markdown 文档 → 打开 QA 面板 → 提问已知内容 → 确认返回答案 → 确认展示引用”说明验证可以从“一条 curl”到“一组端到端步骤”按需伸缩。步骤 2让 harness 控制状态迁移pass-state gatingAgent 不能直接把功能状态改成passing它只能提交验证请求。由 harness 执行验证命令再裁决是否放行迁移。这就是“pass-state gating”。仓库配套目录中的 pass-gate-policy.md 把这个策略写成了一份可执行的验收清单功能只有同时满足以下全部条件才允许从passes: false迁移到passes: true预期的工作流已经实际运行过成功证据已被记录已测试路径上不存在阻塞性错误实现没有把应用留在损坏或状态不明的境地。步骤 3把规则写进 CLAUDE.md / AGENTS.md为了让 Agent 遵守规则必须把约束写进其启动时必读的指令文件。原文档给出的模板## Feature List Rules - Feature list file: /docs/features.md - Only one feature active at a time - Verification command must pass before marking as passing - Dont modify feature list states yourself — the verification script updates them automatically仓库项目把这条规则落实到了AGENTS.md中。以 project-01 的 AGENTS.md 为例它要求 Agent 在写任何代码前按顺序完成通读本文件 → 阅读docs/ARCHITECTURE.md→ 阅读docs/PRODUCT.md→ 运行bash init.sh验证构建 →读取feature_list.json查看所有功能当前状态。它还显式定义了 “Definition of Done”完成定义其中第 3 条就是“功能必须出现在feature_list.json中状态为pass且附有证据”并在“Working with the Feature List”一节明确规定status只能取pass/fail/not-started实现完成即更新为pass并附证据被阻塞则置为fail并写明原因永远不得从列表删除功能。这些规则与原文档的模板一脉相承是“约束写在指令文件里、状态由脚本更新”的工程化样板。步骤 4校准粒度每个功能条目的范围应控制在“一个会话内可完成”。太宽则完不成太窄则管理成本上升。原文档的判例✅ 好的粒度“用户可以把商品加入购物车”❌ 太宽“实现整个购物车”❌ 太窄“在 Cart 模型上创建 name 字段”就像切牛排既不是整块端上桌也不是剁成肉馅。六、配套工具用 feature-list-validator.ts 自动校验功能列表原文档配套的 feature-list-validator.ts 是“让 harness 控制状态迁移”这一原则的最小可运行实现。它读取任意目录下的feature_list.json做两件事Schema 校验检查每条功能是否具备id字符串、category字符串、description字符串、verification数组、passes布尔值证据校验检查是否存在“标记为 pass 却没有验证证据”的功能条目passes true但verification为空数组并在报告中以FLAGGED: passes without evidence!标出。运行方式对任意包含feature_list.json的目录npx tsx docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts [path-to-directory]不传目录参数时默认校验脚本自身所在目录。它的输出是一张结构化的 Markdown 风格表格每个功能 ID 对应的 Schema 是否 OK、是否标为 PASS、验证命令数量、证据是否存在以及异常备注表示无证据却标 pass!!表示 schema 非法最后给出汇总包括总功能数、schema 通过数、标记 passing 数、带证据数、以及被标记的功能数量并在有异常时打印警告WARNING: N feature(s) marked as pass without any verification evidence.脚本还内置了三个演示条目来展示典型问题一个验证证据完整的正常条目qna-002、一个verification: []却passes: true的“无证据假通过”条目qna-003会被旗帜标红、以及一个缺失category和description的 schema 非法条目missing-fields。从这个 200 行不到的脚本可以直观看到 pass-state gating 的底层原理验证器不信任 Agent 的自述只信任证据字段是否非空、命令是否真实存在——这正是“文档可以被无视原语无法被绕过”的代码级体现。七、实战对比自由笔记 vs 功能列表背骨原文档给出一个 10 功能电商平台的对照案例“备忘模式”Memo modeAgent 用非结构化笔记追踪进度。3 个会话后笔记变成“user auth 和 product list 做完了shopping cart 大体完成但有 bugpayments 未开始”。新会话需要 20 分钟推断状态最终把已完成功能重新实现了一遍——就像购物清单只写着“牛奶、面包、还有那个东西”到了店里依然不知道买什么。“背骨模式”Structured mode每个功能都有明确状态与验证命令。新会话读取功能列表3 分钟内就知道F01–F05 是passingF06 是active进行中F07–F10 是not_started。直接从 F06 续作零返工。原文档给出的量化结论使用结构化功能列表的项目相比自由格式追踪功能完成率高出约 45%重复实现为零。八、要点回顾功能列表是 harness 的背骨不是给人类看的备忘调度器、验证器、交接报告器全都依赖它。每个功能条目必须有三要素行为描述 验证命令 当前状态缺一不可。状态迁移由 harness 控制Agent 不能自行改状态验证通过是唯一的晋升路径。功能列表是项目的单一事实来源所有“做什么”的信息都从它导出。粒度校准到“一个会话可完成”太宽完不成太窄管不过来。九、延伸阅读仓库内本讲中文版讲稿docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md配套代码目录验证器、示例 feature_list、pass-gate 策略docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/实践项目项目 04 运行时反馈与作用域控制projects/project-04-incremental-indexing/index.md真实项目的功能列表实例project-01 solution、project-02 solution把功能列表规则写进 Agent 指令文件的样板project-01 AGENTS.md行业背景方面原文档提及 Anthropic 的 “Building Effective Agents” 与 OpenAI 的 “Harness Engineering” 均强调同一原则成果物必须外部化——功能状态应存放在仓库内的机器可读文件中而不是散落在非结构化的会话文本里。十、练习功能列表设计定义一份最小功能列表 JSON schema包含id、行为描述、验证命令、当前状态、证据引用五要素并用它描述你手上真实项目的 5 个功能。验证严苛度对比挑 3 个功能分别设计“宽松验证”如“代码无语法错误”与“严格验证”如“端到端测试通过”比较两者的误报率差异。单一来源原则审计检查一个现有 Agent 项目找出与功能列表相矛盾的作用域信息会话中的隐式要求、代码里的 TODO 注释等并设计把所有信息统一收编进功能列表的方案。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐功能清单Feature List即 Harness 原语用可验证的三元结构与状态机约束 Agent 行为learn-harness-engineering 第 08 讲功能清单Feature List即 Harness 原语用可验证的三元结构与状态机约束 Agent 行为learn harness engineerin用功能列表Feature List约束 Agent 行为从备忘录到 Harness 原语用功能列表Feature List约束 Agent 行为从备忘录到 Harness 原语 功能列表feature list在许多开发者眼里不过是随把功能列表做成 Harness 原语用 Feature-List 约束 Agent 作用域与完成判定把功能列表做成 Harness 原语用 Feature List 约束 Agent 作用域与完成判定 导读这是 learn harness engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考