功能列表(Feature List)为什么是 Harness 的第一原语:基于 learn-harness-engineering 讲座 08 的通过状态门控、端到端验证与评估循环实战
功能列表(Feature List)为什么是 Harness 的第一原语:基于 learn-harness-engineering 讲座 08 的通过状态门控、端到端验证与评估循环实战
本篇文章对应仓库中 docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/(俄语讲座 08 及同目录中文版 docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)下的代码示例目录展开。该目录用四个主题统摄了本讲的核心工具链:pass 状态门控(pass-state gating)、端到端验证(end-to-end verification)、弱与强的完成标准对比(weak vs strong completion criteria) 与 评估循环示例(evaluator-loop)。读完本文,你将理解为什么功能列表是 harness 的"脊椎"而非待办清单,并能直接使用仓库配套的 feature-list-validator.ts、feature_list.json 与 pass-gate-policy.md 构建可验证、可交接、可度量的 Agent 工作流。
一、Agent 并不知道"完成"是什么意思
让 Agent 搭建一个购物网站,它做完后说"完成了"。打开代码你会发现:认证能跑,但购物车里的下单按钮没反应,支付根本没接。问题出在哪里?你从来没有定义过"完成"的标准,于是 Agent 使用了它自己的隐式标准——"我写了很多代码,而且看起来没有语法错误"。
Claude Code、Codex 这类工具不会自动知道你说的"完成"是什么。你说"加个购物车",模型的解释可能是"写一个 Cart 组件和 addToCart 方法";而你真正想要的是"用户能端到端地浏览商品、加入购物车并完成购买"。这个理解鸿沟如果不靠结构化手段弥合,Agent 就会用自己的一套标准收尾。
看一条典型的进度笔记:
Did user auth, shopping cart mostly done, still need payments
新的会话能基于这条笔记继续工作吗?"mostly done"到底完成了什么?购物车通过了哪些测试?支付被什么阻塞?答案全是"没人知道"。结果是:新会话花 20 分钟重建上下文,甚至可能把已经完成的特性重新实现一遍。
结论:必须把"完成"的定义从对话里搬出来,落到机器可读的文件中。 本讲座(以及 Anthropic、OpenAI 的工程实践)都强调同一个原则——把工件外置(artifacts out):功能状态应该活在仓库里的机器可读文件中,而不是非结构化的对话文本里。
二、功能列表是 harness 的"脊椎",不是备忘录
在许多人眼里,功能列表只是一张怕忘记而写下的便利贴。但在 harness 的世界里,功能列表是整个 harness 的脊椎:规划器靠它挑任务,验证器靠它判断完成,handoff 报告器靠它生成交接摘要。脊椎断了,身体就瘫痪了。
文档是给人读的,原语是给系统执行的。文档可以被忽略,原语无法绕过。这就像数据库里的触发器约束与应用程序层校验的区别:前者由数据库引擎强制执行,任何 SQL 都绕不过去;后者依赖代码的正确性,可能被意外绕过。功能列表作为 harness 原语,具体服务于四个组件:
- 规划器(Scheduler):读取各条目的状态,挑选下一条
not_started的功能。如同工厂的生产排产系统。 - 验证器(Verifier):执行验证命令,决定是否允许状态迁移。如同质检部门(ОТК)。
- handoff 报告器(Reporter):从功能列表自动生成会话摘要。如同自动化的交接班报告。
- 进度跟踪器(Tracker):汇总状态分布,给出项目健康度指标。如同仪表盘。
仓库里 projects/project-01/solution/AGENTS.md 的实践可以印证这一点:它把 feature_list.json 定义为"项目进度的唯一事实来源"(source of truth for project progress),并要求实现功能时把状态更新为 "pass" 并附带证据(evidence)、阻塞时置为 "fail" 并写明原因、永远不删除列表中的功能——这正是"原语"而非"备忘录"的落地形态。
三、功能条目的三元结构:行为 + 验证 + 状态
功能列表不需要复杂的系统,结构化 Markdown 或 JSON 就足够。关键在于每条功能记录必须是一个三元组:
- 行为描述(Behavior):这条功能到底是什么,例如
POST /cart/items 返回 201; - 验证命令(Verification):用于精确检验的可执行命令,例如一条 curl 加 jq 断言;
- 当前状态(State):
not_started / active / blocked / passing。
缺了任何一元的记录都是不完整的——就像缺了一条腿的三脚凳。本讲给出的最小 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"
}
仓库的官方模板 skills/harness-creator/templates/feature-list.schema.json 给出了更正式的 JSON Schema 定义(draft-07):每条功能必须有 id(建议模式 ^feat-\d+$)、name、description 与 status,可选 dependencies(前置依赖的功能 ID 列表)与 evidence(置为 done 时的验证证据),其中 status 枚举为 not-started / in-progress / blocked / done。而真实项目的落地示例见 projects/project-01/solution/feature_list.json,其中每条功能带 id、name、description、status、evidence 与 testedAt 时间戳,例如 window-launch 的 evidence 记录了"窗口以 1200x800、contextIsolation=true、nodeIntegration=false 启动"这一可复核事实。
四、功能状态机与 pass 状态门控
本讲定义了功能条目的状态机:not_started → active → blocked / passing,并且给出两条硬性规则:
- passing 门控(pass-state gating):把功能从
active提升为passing的唯一途径是成功执行该条目的验证命令。这由 harness 强制执行,Agent 不能自行改状态;Agent 只能提交验证请求,harness 执行验证命令并裁决是否放行。 - 不可逆:一旦进入
passing就不能回退。就像考试通过就是通过,成绩不能事后更改。
配套的 pass-gate-policy.md 把门控策略写成了四条可审计的标准:一条功能只有当 ① 预期场景被真实走过、② 成功证据被记录、③ 已验证路径上没有阻塞性错误、④ 实现没有把应用留在损坏或歧义状态时,才能从 passes: false 翻转为 passes: true。
本讲给出的状态流转图(mermaid)可以归纳为:功能列表 → 规划器取下一条 not_started → Agent 只做这一条 → 验证器运行该条目的验证命令 → pass 则标记 passing 并记录证据 / fail 则保持 active / 依赖问题则标记 blocked → 更新 handoff 摘要与当前进度。
五、用 validator 把"通过状态门控"变成可执行代码
讲座 code 目录的核心可运行示例是 feature-list-validator.ts。它演示了"pass 状态门控"的最小实现:读取 feature_list.json、校验 schema、并检查标记为 pass 但没有验证证据的功能,最后输出结构化报告。它可以直接对任意含 feature_list.json 的项目目录运行:
npx tsx docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts [path-to-dir]
# 不传参数时默认扫描脚本所在目录
从源码看,它由四个逻辑阶段组成:
- Schema 校验(validateSchema):逐条检查
id、category、description是否存在且为字符串,verification若存在必须是数组,passes若存在必须是布尔值; - 证据校验(checkEvidence):核心逻辑只有两行判断——
hasVerification = verification 数组非空,markedPassWithoutEvidence = passes === true && !hasVerification; - 汇总处理(processFeatureList):为每条目生成
ValidationResult; - 报告输出(run):打印表格报告,统计总数、schema 有效数、标记 passing 数、有证据数与**被标记为"pass 但无证据"**的数量,并在存在此类条目时输出
WARNING,提示"这些功能在可信之前必须补验证"。
配套的 feature_list.json 给出了真实输入示例:一条 qna-001 功能,category 为 grounded_qa,verification 是五步人工可执行的清单(导入 Markdown 文档 → 打开问答面板 → 就已知内容提问 → 确认返回答案 → 确认展示引用),passes: false。而脚本内置的演示数据集(源码 demoEntries)刻意构造了三个陷阱条目:qna-002(正常 pass + 证据)、qna-003(passes: true 但 verification 为空数组,无证据硬 pass)、missing-fields(缺 category 和 description)。运行脚本后,qna-003 会被标记为 >> FLAGGED: passes without evidence!,missing-fields 会被标记为 !! INVALID——这就是"弱完成标准"被机械识破的直接演示。
六、弱完成标准 vs 强完成标准
本讲反复对比两类完成标准:
- 弱完成标准(weak):例如"代码里没有语法错误""组件已经写好"。这类标准极易出现假阳性——代码能编译不代表行为正确,正如讲座开头的例子:购物车按钮渲染出来了,但点击无反应。
- 强完成标准(strong):例如"端到端测试通过""POST /cart/items 返回 201"。这类标准把"行为"作为裁决对象,与功能条目的
verification字段一一对应。
把这条对比映射回 validator 源码:markedPassWithoutEvidence 正是"弱标准"的形式化表达——只声明 passes: true,却不提供任何可复核的验证证据。讲座的练习 2 建议读者取 3 条功能,分别设计弱验证与强验证,再对比两者的假阳性占比——这正是"evaluator-loop"迭代改进验证命令质量的过程。
七、粒度校准:一条功能 = 一次会话能完成
功能条目的粒度必须校准在"一次会话可以完成"的尺度上:
- 太宽:"实现购物车"——一次会话根本做不完,无法形成有效状态流转;
- 太窄:"在 Cart 模型里加个 name 字段"——管理开销超过收益;
- 合适:"用户可以把商品加入购物车"——行为可验证、边界清晰。
本讲的比喻很贴切:切牛排,不能整块上,也不能剁成肉馅。粒度失控时,blocked 状态和依赖链(见 feature-list.schema.json 中的 dependencies 字段)就会失效,规划器也就无法在会话间可靠接力。
八、把规则写进 Agent 的启动指令
功能列表要真正成为原语,规则必须写进 Agent 每次会话都会读的指令文件。本讲给出了 CLAUDE.md 中的规则示例:
## Feature List Rules
- Feature list file: /docs/features.md
- Only one feature active at a time
- Verification command must pass before marking as passing
- Don't modify feature list states yourself — the verification script updates them automatically
仓库项目 projects/project-01/solution/AGENTS.md 给出了同一思路的完整实现:启动时先读 feature_list.json 查看全部功能状态,并在 "Definition of Done" 中规定——功能"完成"当且仅当 TypeScript 编译通过、应用可启动可见、feature_list.json 中状态为 "pass" 且附证据、遵守分层边界、运行期无控制台报错。这五条合起来,就是把"完成"从 Agent 的主观判断改写为可验证的客观标准。
九、备忘模式 vs 脊椎模式:一次真实的对比
本讲以"10 条功能的电商平台"为例对比两种记账方式:
- 备忘模式:Agent 用非结构化笔记。3 个会话后笔记变成"做了 auth 和商品列表,购物车基本完成但有 bug,支付未开始"。新会话花 20 分钟重建状态,最终把已完成功能重做一遍。这就像购物清单上写着"牛奶、面包和那个东西"——到了超市你照样不知道买什么。
- 脊椎模式:每条功能有明确状态与验证命令。新会话读一遍列表,3 分钟就知道 F01–F05 是
passing、F06 是active、F07–F10 是not_started,直接接着 F06 干,零返工。
讲座援引的数据(结构化功能列表项目相比自由记账完成率更高、会话启动诊断时间大幅下降、零实现重复)来自其引用的行业工程实践(Anthropic《Building Effective Agents》、OpenAI《Harness Engineering》等),作为方法论背景参考;其正确性取决于你自己的项目是否真正落实"passing 门控 + 证据记录"两条纪律——这正是可以在仓库项目中直接做对照实验的(例如对比 projects/project-01/solution/feature_list.json 与后续项目的 feature 列表演进)。
十、两个核心机制与三条练习
最后回到本讲的两个机制性结论:
- 单一事实来源(Single Source of Truth):所有"要做什么"的信息都来自同一份功能列表,不允许功能列表与对话历史、代码 TODO 注释相互矛盾。讲座的练习 3 正是要求读者审计现有项目,找出与功能列表冲突的隐式需求,并设计合并计划。
- 反向压力(Backpressure):尚未达到
passing的功能数量,就是 harness 施加给 Agent 的压力;压力归零意味着项目完成。这为"什么时候算结束"提供了一个客观、可度量的答案——不需要靠 Agent 宣布"我完成了"。
讲座配套的三条练习值得逐一实践:① 设计最小 JSON 功能列表 schema(含 id、行为描述、验证命令、状态、证据链接),并用它描述一个 5 条功能的真实项目;② 为 3 条功能分别设计弱/强验证并比较假阳性率;③ 对现有 Agent 项目做单一事实来源审计。完成这三条练习后,再回到 code/ 目录运行 validator 检查自己的列表,你就能完整走通"定义功能 → 写验证命令 → 运行门控 → 生成证据 → 交接下一条"的评估循环,让功能列表真正成为你 harness 的脊椎。