learn-harness-engineering 第 08 讲:特征列表是 harness 原语——用 pass-gate 策略把"done"变成可验证的工程事实
learn-harness-engineering 第 08 讲:特征列表是 harness 原语——用 pass-gate 策略把"done"变成可验证的工程事实
导读
本篇文章围绕 learn-harness-engineering 仓库中《Lección 08. Usa listas de funciones para limitar al agente》及其配套的 pass-gate-policy.md 展开,系统讲解"特征列表(feature list)"为什么是 harness 的根基数据结构,以及"通过门禁策略(pass-gate policy)"如何把抽象的"做完了"变成可执行、可验证、可审计的工程事实。读完本文,你将掌握:特征列表的最小 JSON 格式与状态机设计、pass-gate 的四大放行条件、如何用仓库自带的 feature-list-validator.ts 校验列表健康度、以及如何把门禁规则固化进 CLAUDE.md/AGENTS.md 让多会话 Agent 项目不再返工。
一、问题原点:Agent 根本不知道什么叫 "done"
给一个 Agent 下达"搭建一个电商网站"的任务,它忙完告诉你 "done"。检查代码后发现:用户登录能用,但购物车的 checkout 按钮毫无反应,支付流程根本没接上。问题出在哪里?你从未定义过"done"的含义,于是 Agent 启用了自己的默认标准——"我写了很多代码,看起来挺完整"。
这不是个别现象。课程用一句直白的类比点破本质:你让朋友"买点水果",他拎回来一袋柠檬——他的"水果"和你的"水果"不是同一种水果。同样,Claude Code、Codex 这类 Agent 不会自动理解你要的"done"是"用户能端到端完成浏览商品、加入购物车、结算付款",而很可能只把它解释成"写一个 Cart 组件和 addToCart 方法"。
再看一条常见的进度笔记:
Did user auth, shopping cart mostly done, still need payments
"mostly done" 到底完成了多少?购物车通过了哪些测试?支付被什么阻塞?新会话面对这种笔记,答案全是"没人知道"。结果就是:新会话要花 20 分钟推断项目状态,甚至把已经做完的功能重新实现一遍。课程引用了 Anthropic 工程数据的结论:良好的进度记录可以把会话启动时的状态诊断时间降低 60%~80%。
二、pass-gate 策略:什么条件下才允许"通过"
本讲配套的 pass-gate-policy.md 用八行文字定义了整个 harness 的核心放行规则——一个功能条目只允许从 passes: false 变为 passes: true,且必须同时满足以下四个条件:
- 期望的工作流已被执行(el flujo de trabajo esperado ha sido ejecutado):不是"写了代码",而是按该功能定义的验证流程实际跑了一遍;
- 成功证据已被记录(la evidencia de éxito está registrada):验证通过的结果、commit 哈希、测试输出等被落盘到列表条目中,供后续会话审计;
- 被测试路径上不存在阻塞性错误(no hay errores bloqueantes en la ruta probada):关键路径无阻断,而不是"语法没报错";
- 实现没有让应用处于损坏或歧义状态(la implementación no deja la app en un estado roto o ambiguo):功能通过后应用整体仍处于干净、明确的状态。
这四条规则就是课程反复强调的 pass-state gating(通过态门禁):功能从 active 晋升到 passing 的唯一路径是验证命令成功执行。而且这一转变是不可逆的——就像考试通过后不能事后改分。Agent 无权直接把某个条目改成 passing,它只能发起验证请求,由 harness 执行验证命令并裁决是否放行。
三、功能状态机:not_started / active / blocked / passing
特征列表不是一个静态清单,而是一个由 harness 掌控的状态机。课程给出了两个 Mermaid 图,第一个定义"一行功能条目"的数据构成:
flowchart LR
Feature["一行功能条目"] --> Behavior["行为描述<br/>例如: POST /cart/items 返回 201"]
Feature --> Check["验证命令<br/>要执行的精确检查"]
Feature --> State["状态<br/>not_started / active / blocked / passing"]
Behavior --> Complete["只有三个字段齐备<br/>该条目才可用"]
Check --> Complete
State --> Complete
第二个图描述了 harness 的运转闭环:
flowchart LR
List["feature_list.json / features.md"] --> Scheduler["调度器选择下一个 not_started 条目"]
Scheduler --> Agent["Agent 只处理这一个条目"]
Agent --> Verifier["执行该条目的验证命令"]
Verifier -->|通过| Passing["标记为 passing<br/>并写入证据"]
Verifier -->|失败| Active["保持 active"]
Verifier -->|依赖问题| Blocked["标记为 blocked"]
Passing --> Handoff["更新 handoff 笔记<br/>与当前进度"]
Active --> Agent
要点在于:状态迁移由 harness 控制,Agent 不能自由改状态。not_started(未开始)→ active(进行中)→ passing(已通过)是主路径;出现依赖问题则挂起为 blocked;验证失败则退回 active 继续迭代。这套模型让"项目做到哪了"不再是模糊印象,而是一份可查询的工程事实。
四、为什么特征列表必须是"原语"而非笔记
课程给出了一个关键区分:文档是给人读的,原语是给系统执行的。文档可以视而不见,原语无法跳过。类比数据库 trigger 与业务层 check:前者由数据库引擎强制,任何 SQL 都无法绕过;后者依赖应用代码正确性,可能被意外漏掉。
作为 harness 原语,特征列表同时服务于四个组件:
- Scheduler(调度器):读取状态,挑选下一个
not_started条目——像工厂里的生产排程系统; - Verifier(验证器):执行验证命令,裁决是否允许状态迁移——像质检岗;
- Handoff reporter(交接报告器):从列表自动生成会话交接摘要——像自动化的换班报告;
- Progress tracker(进度追踪器):统计状态分布,输出项目健康度指标——像仪表盘。
正因为调度、验证、交接、统计都依赖同一份数据,特征列表才被称为"harness 的脊柱"(columna vertebral):脊柱断了,整个身体都会瘫痪。这也与 OpenAI 的 harness-engineering 文章强调的"外部化工件(externalize artifacts)"原则一致——功能状态必须存放在仓库中机器可读的文件里,而不是散落在无结构的对话文本中。
五、落地实操:最小特征列表格式
课程强调:不需要复杂系统,一个结构化 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/es/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": ""
}
]
}
模板的三个顶层规则直接呼应 pass-gate 策略:同一时刻只有一个 active 功能(避免 Agent 多头并行失控)、通过必须附证据(呼应"成功证据已被记录")、不许跳过验证(呼应"工作流必须被实际执行")。status_legend 则把四个状态的语义写死在数据里,新会话无需任何额外解释即可正确解读。
六、源码级佐证:feature-list-validator.ts 如何执行门禁
课程配套代码 feature-list-validator.ts 给出了 pass-gate 策略的可执行实现,它把"验证规则"翻译成了 TypeScript 代码。从源码结构看,它依次做三件事:
1. 模式校验(validateSchema):检查每条目的 id、category、description 是否缺失或类型错误,并要求 verification 必须为数组、passes 必须为布尔值——这对应三元组的完整性要求;
2. 证据校验(checkEvidence):这是门禁的核心逻辑——markedPassWithoutEvidence = entry.passes === true && !hasVerification,即标记为通过但没有任何验证命令的条目会被标记为 FLAGGED。这正是 pass-gate 的代码化表达:没有验证手段的"通过"不可信;
3. 结构化报告输出:按 Feature ID / Schema / Passes / Verifications / Evidence 逐行输出表格,最后给出汇总——Total features、Schema valid、Marked as passing、With verification evidence、Flagged (pass without evidence),并在存在违规时输出警告。
运行方式(脚本注释中给出的用法,可作用于任意包含 feature_list.json 的项目目录):
npx tsx docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts [path-to-dir]
不传参数时默认读取脚本所在目录下的 feature_list.json。脚本还内置了演示数据集:一个 verification: [] 却标记 passes: true 的条目("System hallucination rate is below 5%")会被明确标记为 FLAGGED: passes without evidence!——这就是对"凭感觉宣布胜利"的直接拦截。
配套数据 code/feature_list.json 展示了符合规范的真实条目,例如 qna-001:行为是"用户可就导入文档提问并得到带引用的回答",验证命令列出了"导入 markdown 文档 → 打开问答面板 → 就已知内容提问 → 确认返回答案 → 确认展示引用"五步,passes 初始为 false。
再看真实项目中的应用:projects/project-02/solution/feature_list.json 中每条已通过功能都带有 evidence 与 testedAt 字段,例如 document-import 条目记录证据为 "ImportPanel triggers window.knowledgeBase.documents.import(filePath), App.tsx refreshes document list on success",把实现细节、IPC 调用链和测试时刻一并落盘——这就是 pass-gate 第二条"成功证据已被记录"的实践形态。
七、把门禁规则写进 CLAUDE.md / AGENTS.md
仅靠 JSON 文件还不够,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-04/starter/AGENTS.md 也体现了同样的纪律:"Work on one feature at a time"(一次只做一个功能)、"Run npm run check before committing"。注意最后一条规则的精妙之处:Agent 被禁止直接修改状态,状态更新只能由验证脚本完成——这把 pass-gate 从"建议"升级为"机制",Agent 无法再通过自报完成度来伪造进度。
八、校准粒度:"一个会话能做完"的边界
粒度是特征列表设计的隐藏难点。课程给出的校准标尺是——每个功能都应"一个会话内可完成":
- 太宽:"Implementar el carrito"(实现购物车)——一个会话做不完,永远处于 active;
- 太窄:"Crear el campo name en el modelo Cart"(给 Cart 模型加 name 字段)——管理成本超过收益;
- 刚好:"El usuario puede añadir items al carrito"(用户可以把商品加入购物车)——可验证、可完成、边界清晰。
课程用切牛排类比:既不该端整块牛排上桌,也不该磨成肉末——切成一口能吃下的块。粒度校准直接决定后文要讲的验证严格度与返工率。
九、真实案例:备忘录模式 vs 脊柱模式
课程给出一个 10 个功能的电商平台对照实验,比较两种追踪方式:
-
备忘录模式(Modo memo):Agent 用无结构笔记。3 个会话后笔记变成"做了 user auth 和 product list,购物车差不多但有 bug,支付没开始"。新会话要花 20 分钟推断状态,最终把已完成功能重新实现一遍——就像购物清单上写着"牛奶、面包、那个东西",到了超市还是不知道买什么。
-
脊柱模式(Modo columna vertebral):每个功能有明确状态和验证命令。新会话读一遍列表,3 分钟内就掌握全局:F01-F05 是
passing,F06 是active,F07-F10 是not_started,直接接着 F06 干,零返工。
课程给出的量化结论:使用结构化特征列表的项目,功能完成率比自由记录方式高 45%,且没有出现重复实现。这正是 pass-gate 与状态机组合的收益——可验证的进度取代了靠猜的进度。
十、核心要点回顾
- 特征列表是 harness 的脊柱,不是给人类的备忘录。Scheduler、Verifier、Handoff reporter、Progress tracker 全部依赖它;
- 每条目必须包含三元组:行为描述 + 验证命令 + 当前状态,缺一项即不完整;
- 状态迁移由 harness 掌控:Agent 不能自行改状态,通过验证是唯一的晋升路径,且不可逆;
- 特征列表是项目"要做什么"的唯一事实来源(single source of truth),与对话历史之间不允许出现矛盾;
- 未通过的功能数量就是 harness 施加给 Agent 的背压(back-pressure),压力归零即项目完成;
- 粒度校准到"一个会话可完成"。
十一、动手练习
课程设计了三个练习,可在本仓库基础上直接实践:
- 特征列表设计:定义最小 JSON 模式,包含 id、行为描述、验证命令、当前状态、证据引用,用 5 个功能描述一个真实项目;
- 验证严格度对比:选 3 个功能,分别设计"宽松验证"(如"代码没有语法错误")与"严格验证"(如"端到端测试通过"),用 feature-list-validator.ts 对比误报率;
- 单一事实来源审计:检查一个 Agent 项目,找出与特征列表矛盾的范围信息(对话中的隐含需求、代码里的 TODO 注释等),制定把所有信息统一收敛进列表的方案。
延伸阅读可参考课程提到的 Building Effective Agents(Anthropic,将特征列表明确视为控制 Agent 范围的 "core data structure")、Harness Engineering(OpenAI,"外部化工件"原则)、Design by Contract 契约式设计与 How Google Tests Software 中的行为规格实践——它们的理念与特征列表三元组结构一脉相承。对应的实战项目见 project-04(增量索引与运行时反馈) 与 project-02(Agent 可读工作区),以及本讲全套代码 code/。