【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇文章基于 learn-harness-engineering 仓库的《Lecture 08. Use Feature Lists to Constrain What the Agent Does》讲座对应 docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md英文原版见 docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md展开。Feature List功能清单在许多人眼里只是一张备忘便签但在 Harness 工程中它是整个 Harness 的脊椎骨调度器靠它选任务、验证器靠它判定完成、交接报告器靠它生成摘要。读完本文你将掌握为什么 Agent 永远不知道完成意味着什么、如何用三元组结构 四态状态机把完成变成可验证的机器事实以及如何在本仓库的真实项目中落地这份清单。为什么 Agent 永远不知道完成意味着什么你让 Agent 搭建一个电商网站。它干完后告诉你好了。你打开代码——用户认证能跑但购物车里的结算按钮点了没反应支付流程压根没接。问题出在哪你从没告诉它完成的定义于是它动用了自己的隐性标准我写了一大堆代码看起来差不多完整了。无论 Claude Code 还是 Codex都不会自动知道你说的完成是什么。你说加一个购物车功能模型的解释可能是写一个 Cart 组件和 addToCart 方法而你的真实意图是用户能端到端地浏览商品、加入购物车、完成下单。这个理解鸿沟在没有 Feature List 时永远无法弥合——Agent 使用它自己的隐性标准通常是代码没有明显的语法错误而你需要的是端到端的行为验证。这就像你让朋友买点水果他拎回一袋柠檬你的水果和他的水果不是同一种水果。看一条典型的进度记录Did user auth, shopping cart mostly done, still need payments换一个全新的 Agent 会话能靠这条记录回答以下问题吗mostly done到底做到哪一步了购物车通过了哪些测试支付被什么卡住了答案是没人知道。结果就是新会话花 20 分钟推断项目状态还可能把已经做好的功能重做一遍。Anthropic 的工程数据显示良好的进度记录能把会话启动时的诊断时间缩短 60–80%。这正是本仓库课程体系里反复出现的主题——Lecture 05. Why Long-Running Tasks Lose Continuity 讲连续性问题、Lecture 09. Why Agents Declare Victory Too Early 讲过早宣布胜利而 Feature List 正是同时解决这两类问题的底层数据结构。Feature 状态机一条记录 行为 验证 状态一个 Feature 条目不是一行文字而是三件套。本仓库的讲座用两张状态图定义了它的完整语义第一张图一条 Feature 行 三个字段第二张图Harness 驱动的工作流在真实项目中这个清单就叫feature_list.json。本仓库对每个实践项目都维护了它的真实实例例如 projects/project-01/solution/feature_list.json 中window-launch一条{ id: window-launch, name: Window Launch, description: Electron app opens a BrowserWindow with correct dimensions and preload script, status: pass, evidence: npm run dev launches window at 1200x800 with contextIsolationtrue and nodeIntegrationfalse, testedAt: 2026-03-30T10:00:00Z }注意evidence字段——它记录的不是我写完了而是运行npm run dev后窗口以 1200x800 打开且 contextIsolationtrue、nodeIntegrationfalse。这正是验证必须留下证据的落地方式。核心概念Feature List 为什么是 Harness 原语三元组结构每个 Feature 条目必须同时包含三个元素行为描述behavior、验证命令verification、当前状态state。行为告诉 Agent 做什么验证告诉它什么算完成状态告诉它现在做到哪了。缺任何一个条目就不完整——就像三条腿的凳子少了一条腿。四态状态机每个条目的状态只有四种not_started未开始、active进行中、blocked被阻塞、passing已通过。状态迁移由 Harness 控制Agent 无权自行改状态。passing 门禁Pass-State GatingFeature 从active进入passing的唯一途径是验证命令成功执行。这个迁移不可逆——一旦passing就不能回头就像考试及格了不能事后改分。本仓库对这条门禁给出了白纸黑字的策略文件docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md一条 Feature 只有在同时满足以下条件时才能从passes: false变为passes: true期望的工作流已被实际走通the expected workflow has been exercised成功的证据已被记录the evidence of success is recorded被测路径上没有阻塞性错误no blocking error is present in the tested path实现没有把应用留在损坏或歧义状态the implementation does not leave the app in a broken or ambiguous state单一事实源Single Source of Truth所有要做什么的信息必须只来自一份 Feature List。清单与对话历史之间不允许出现矛盾——聊天记录是不可靠的临时介质而清单是可审计的机器文件。反向压力Back-pressure尚未达到passing的 Feature 数量就是 Harness 施加给 Agent 的压力。压力为零 项目完成。这是一条可量化的完成判据不是Agent 说做完了而是passing数量 总数。为什么 Feature List 必须是原语而非文档文档是给人读的原语是给系统执行的。文档可以被忽略原语无法被绕过。这就像数据库触发器约束 vs 应用层校验前者由数据库引擎强制执行任何 SQL 都绕不过去后者依赖应用代码的正确性可能被意外绕过。Feature List 作为 Harness 原语具体服务四个组件调度器Scheduler读取状态挑选下一个not_started的 Feature——像工厂的生产排程系统。验证器Verifier执行验证命令裁决是否允许状态迁移——像质检科ОТК。交接报告器Handoff reporter从 Feature List 自动生成会话交接摘要——像自动换班报告。进度跟踪器Progress tracker汇总状态分布给出项目健康度指标——像仪表盘。本仓库的实践项目就严格遵循这个模式。以 projects/project-01/solution/AGENTS.md 为例项目把feature_list.json明确写进了启动规则和完成定义启动时第 5 步Readfeature_list.jsonto see the current state of all features读取清单了解全部 Feature 的当前状态Definition of Done 第 3 条feature 必须出现在feature_list.json中且status为pass并附有证据Working with the Feature List 一节feature_list.json是项目进度的单一事实源实现一个 Feature 后把状态更新为pass并附上证据而 projects/project-03/solution/feature_list.json 展示了多会话场景下的真实演化——前 7 条 Feature 的 evidence 写着 Carried over from P2 -- verified working从项目 02 继承并已验证后续的document-chunking、metadata-extraction、grounded-qa则各自带着精确的证据描述如 IndexingService.chunkDocument() splits on paragraph boundaries, merges paragraphs until ~500 chars。这正是新会话 3 分钟接管、零返工的仓库级证据。实战操作四步把 Feature List 落地第一步定义最小格式不需要复杂系统——结构化 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 }本仓库提供了可直接复用的完整模板docs/ru/resources/templates/feature_list.json。它比最小示例更工程化包含了项目级元数据与规则声明{ project: replace-with-project-name, last_updated: YYYY-MM-DD, rules: { single_active_feature: true, passing_requires_evidence: true, do_not_skip_verification: true }, status_legend: { not_started: Work has not begun., in_progress: The feature is the current active task., blocked: Work cannot continue until a documented blocker is resolved., passing: Required verification has passed and evidence is recorded. }, features: [ { id: chat-001, priority: 1, area: chat, title: Create a new conversation, user_visible_behavior: A user can click New Chat and see a fresh empty conversation., status: not_started, verification: [ Open the app., Click New Chat., Verify a new conversation appears in the sidebar., Verify the main panel shows an empty conversation state. ], evidence: [], notes: } ] }模板把三条硬规则同时只有一个 active、passing 必须有证据、不得跳过验证直接写进rules字段并配status_legend说明四个状态的精确语义——这份清单本身就是机器可读的契约。第二步把状态迁移交给 HarnessAgent 不能直接把 Feature 改为passing。它只能提交验证请求Harness 执行验证命令并裁决是否允许迁移。这就是passing 门禁。本仓库提供了一个可运行的验证器脚本docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts。它会读取feature_list.json、校验 schema并重点检查标记为 pass 却没有验证证据的条目。运行方式npx tsx docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts [path-to-dir]不传目录时默认校验脚本所在目录。它输出的报告中每一行 Feature 都标注 SchemaOK/INVALID、PassesPASS/FAIL、Verifications验证步骤数、EvidencePresent/MISSING并对无证据却标记 pass的条目打上 FLAGGED标记最后输出汇总若存在被标记条目WARNING: N feature(s) marked as pass without any verification evidence.若全部健康All passing features have verification evidence. Feature list is healthy.这个脚本从代码层面印证了门禁语义——checkEvidence()的逻辑是hasVerification verification 是非空数组markedPassWithoutEvidence passes true !hasVerification。也就是说通过与有证据在 Harness 中是强绑定的这正是 passing 门禁的可执行实现。对应的样例数据在 docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json一条grounded_qaFeature 带 5 步人工验证清单、passes: false等待真实执行。第三步把规则写进 CLAUDE.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本仓库的做法更完整——projects/project-01/solution/AGENTS.md 用一整节 Working with the Feature List 声明feature_list.json是项目进度的事实源、每条 Feature 有pass/fail/not-started状态、实现后要更新状态并附证据。把同样的规则写进你自己的CLAUDE.md或AGENTS.mdAgent 每次启动都会先读到这份契约。第四步校准粒度每条 Feature 的规模应当是一个会话内能完成。太宽完不成太窄管理开销失控✅ 用户可以把商品加入购物车——好粒度❌ 实现整个购物车——太宽❌ 在 Cart 模型上创建 name 字段——太窄讲座的原话很形象像切牛排——既不是整块牛排也不是肉馅。实战对比便签模式 vs 脊椎模式一个 10 个 Feature 的电商平台两种记账方式对比便签模式Memo modeAgent 用非结构化笔记跟踪进度。3 个会话后笔记变成做了 auth 和商品列表购物车差不多好了但有 bug支付还没开始。新会话花 20 分钟推断状态最后把已完成的 Feature 重做了一遍。就像购物清单上写着牛奶、面包、那个东西——到了超市你还是不知道该拿什么。脊椎模式Structured mode每个 Feature 都有清晰状态和验证命令。新会话读一遍清单3 分钟就知道F01–F05 是passingF06 是activeF07–F10 是not_started。直接接着 F06 干零返工。讲座给出的量化结论使用结构化 Feature List 的项目Feature 完成率比自由形式记账高出 45%且零重复实现。需要注意的是该数字来自讲座原文引用属于课程作者的经验性数据本仓库中你可以通过 projects/project-01 至 projects/project-06 各项目的feature_list.json与session-handoff.md观察同一模式在真实项目中的演化来印证其机制。与相邻课程的关系Feature List 不是孤立概念它在 Harness 工程课程中承上启下Lecture 03. Why the Repository Must Become the System of RecordFeature List 就是仓库成为记录系统的具体载体之一Lecture 07. Why Agents Overreach and Under-Finish边界失控问题的解药正是清单 门禁Lecture 10. Why End-to-End Testing Changes Results端到端测试为验证命令提供执行介质Lecture 12. Why Every Session Must Leave a Clean State干净状态 清单状态一致 交接笔记完整Project 04. Runtime Feedback and Scope Control实战项目把运行时反馈 范围控制 增量索引作为 Harness 机制组合落地。练习Feature List 设计定义一份最小 JSON schema包含id、行为描述、验证命令、当前状态、证据引用。用它对一个 5 个 Feature 的真实项目建模可直接参考 docs/ru/resources/templates/feature_list.json 起步。验证严格度对比取 3 个 Feature分别设计弱验证例如代码没有语法错误和强验证例如端到端测试通过对比两种方式下的误报率。可借助 feature-list-validator.ts 观察无证据却标 pass会被如何标记。单一事实源审计审查一个现有的 Agent 项目找出与 Feature List 矛盾的范围信息对话中的隐性需求、代码里的 TODO 注释等设计一份把所有信息统一进清单的方案。关键结论Feature List 是 Harness 的脊椎骨不是给人看的便签。调度器、验证器、交接报告器全都依赖它。每个条目必须是三元组行为描述 验证命令 当前状态。缺一项就不完整。状态迁移由 Harness 控制——Agent 不能自行改状态通过验证是唯一的升级路径。Feature List 是项目的单一事实源——所有做什么的信息都从这一份清单派生。粒度校准到一个会话可完成太宽完不成太窄管不动。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐用 Feature List 约束 Agent 行为learn-harness-engineering 中的 Harness 原语与状态机实践用 Feature List 约束 Agent 行为learn harness engineering 中的 Harness 原语与状态机实践 本文以 lea功能清单Feature List即 Harness 原语用可验证的三元结构与状态机约束 Agent 行为learn-harness-engineering 第 08 讲功能清单Feature List即 Harness 原语用可验证的三元结构与状态机约束 Agent 行为learn harness engineerin用 Feature List 约束 Agent 行为Harness 工程中完成的单一事实来源用 Feature List 约束 Agent 行为Harness 工程中完成的单一事实来源 本讲义的代码示例位于 docs/en/lectures/le上一篇猫抓浏览器插件免费快速搞定网页视频下载一位设计师的24小时实测记录下一篇OpenCloud活动日志系统用户行为追踪与审计策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考