功能清单是 Harness 原语:用 feature_list.json 与验证器门控 Agent 完成标准(learn-harness-engineering 第 08 讲实战解析)

原创2026-10-10 18:06:521,669 阅读

功能清单是 Harness 原语:用 feature_list.json 与验证器门控 Agent 完成标准(learn-harness-engineering 第 08 讲实战解析)

本篇技术指南围绕 learn-harness-engineering 课程第 08 讲「功能清单是 harness 原语」及其配套代码示例展开,系统讲解为什么 agent 无法自己判断 "done"、功能清单为何必须由三元组与状态机构成,以及如何用 feature_list.json + 验证器脚本实现通过状态门控(pass-state gating)、端到端验证和宽松/严格完成标准的对比。读完你就能在自己的 agent 项目中落地一份机器可读的功能清单,并借助仓库中的真实验证器源码理解底层实现。

为什么 agent 不知道 "done" 是什么意思

一个常见场景:让 agent 做一个电商网站,跑完之后它告诉你"做完了"。打开代码一看,用户认证有了,但购物车的结算按钮点了没反应,支付流程根本没接上。问题根源在于:你从未告诉过它"做完"的具体标准,于是它启用了自己的隐式标准——"代码写了不少,看起来挺完整"。

课程正文(docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md,中文版见 docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)指出:Claude Code、Codex 这类编码 agent 都不会自动理解你心里的"做完"。"加一个购物车功能"在模型那里可能等于"写一个 Cart 组件和 addToCart 方法",而你的真实意图是"用户能从浏览商品到下单支付完整走通"。这个理解鸿沟在没有功能清单时永远存在——agent 判断完成的标准通常退化为"代码没有明显的语法错误",而你需要的是端到端的行为验证。

课程给了一个更生活化的类比:就像让朋友"买点水果",他拎回来一袋柠檬。他的"水果"和你的"水果"不是同一种东西。

再看一种常见的进度记录:

做了用户认证、购物车基本完成了、还需要做支付

新会话看到这条记录能回答出"基本完成意味着什么?购物车通过了哪些测试?支付的阻塞条件是什么?"吗?答案全是"不知道"。这正是非结构化笔记的致命伤。课程结论是:把进度和验证结果记录在版本化文件中,让下一次会话可以直接检查项目状态——这呼应了 Anthropic 与 OpenAI 在 harness 工程实践中反复强调的"工件必须外部化"原则:功能状态应当是仓库里机器可读的文件,而不是对话里的非结构化描述。课程正文只引述了这一机制,并未量化启动耗时的节省,我们也不做任何性能数字的引申。

功能清单的三元组与状态机

功能清单在很多人眼里是"备忘录":写下来怕忘,写完扔到一边。但在 harness 的世界里,它是整个 harness 的基础结构——调度器靠它选任务,验证器靠它判完成,交接器靠它生成报告。没有它,这些组件就失去了可依赖的共识。

课程给出的最小模型是三元组结构:每个功能项必须同时具备三个要素:

要素 含义 示例
行为描述(behavior) 告诉 agent 要做什么 POST /cart/items 返回 201
验证命令(verification) 告诉它怎么算做完 执行某个具体的 curl / 测试命令
当前状态(state) 告诉它现在进行到哪一步 not_started / active / blocked / passing

缺了任何一项,这个功能项就不完整。下图是课程正文中的三元组关系示意:

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 控制,而不是 agent 想改就能改。完整的状态流转如下:

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["更新交接说明<br/>和当前进度"]
    Active --> Agent

围绕这张状态机,课程提炼出六个核心概念,构成"功能清单作为原语"的完整理论基础:

  • 功能清单是 harness 原语:不是"可选的规划工具",而是所有 harness 组件依赖的基础数据结构。就像数据库里的主键,你不能说"这轮先跳过主键"。
  • 三元组结构:(行为描述, 验证命令, 当前状态),缺一项就不完整。
  • 状态机模型:四种状态 not_started、active、blocked、passing,转移由 harness 控制。
  • 通过状态门控(pass-state gating):从 active 到 passing 的唯一方式是验证命令执行成功,且该转移不可逆——一旦 passing 就不能退回去,就像考试通过后不能修改成绩。
  • 单一权威来源(single source of truth):项目里所有"该做什么"的信息都必须从这一个功能清单派生,不允许清单与对话记录矛盾。
  • 反向压力(back-pressure):尚未通过的功能项数量就是 harness 对 agent 施加的压力;压力归零 = 项目完成。

为什么功能清单必须是原语

课程做了一个关键区分:文档是给人看的,原语是给系统执行的。文档可以被忽略,原语不能被绕过。

最贴切的类比是数据库触发器约束 vs 应用层检查:前者由数据库引擎强制执行,任何 SQL 都无法跳过;后者依赖应用代码的正确性,可能被意外遗漏。功能清单作为 harness 原语,扮演的正是"数据库级别约束"的角色——agent 无法绕过它,因为它不是"建议"而是"被系统读取的数据"。

具体来说,功能清单服务四个 harness 组件:

  1. 调度器(Scheduler):读状态,选下一个 not_started 的功能,像工厂的生产排程系统。
  2. 验证器(Verifier):执行验证命令,判断是否允许状态转移,像质检工位。
  3. 交接报告器(Handoff reporter):从功能清单自动生成会话交接摘要,像自动化的换班报告。
  4. 进度追踪器(Progress tracker):统计各状态分布,给出项目健康度指标,像仪表盘。

代码示例:feature_list.json 与验证器

第 08 讲代码目录(code/)的索引页(code/index.md)明确列出了本目录承载的四个示例主题:状态门控(gating de estado de aprobación)、端到端验证(verificación end-to-end)、宽松 vs 严格完成标准(criterios de completitud débiles vs fuertes)、评估循环示例(ejemplos de bucle evaluador)。下面逐一结合真实源码展开。

feature_list.json 真实示例

仓库提供了一个最小但完整的清单文件(code/feature_list.json):

[
  {
    "id": "qna-001",
    "category": "grounded_qa",
    "description": "User can ask a question about an imported document and receive an answer with visible citations.",
    "verification": [
      "Import a markdown document",
      "Open the Q&A panel",
      "Ask a question about known content",
      "Verify the answer is returned",
      "Verify one or more citations are displayed"
    ],
    "passes": false
  }
]

注意这里的字段命名:id、category、description、verification(数组)、passes(布尔)。它和课程正文教学 JSON 中的 behavior/verification/state/evidence 是同一思想的不同命名实现——验证器脚本(见下)只认这套字段名,课程正文则用更语义化的名字做讲解。两种命名都满足三元组的本质:做什么(description/behavior)、怎么验证(verification)、当前状态(passes/state)。

值得注意的是,这个示例的 verification 是多步行为清单(导入文档 → 打开问答面板 → 提问 → 验证回答 → 验证引用),而不是一行 curl。这正是"端到端验证"思想的体现:完成标准绑定的是用户可观察的行为结果,而不是"代码写没写出来"。

feature-list-validator.ts:schema 与证据双重校验

配套的验证器(code/feature-list-validator.ts)是理解"harness 如何控制状态转移"的最佳源码样本。它可以直接对任何含 feature_list.json 的目录运行:

# 默认校验脚本所在目录
npx tsx docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts

# 或显式指定目标目录
npx tsx docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts /path/to/project

它的校验逻辑分两层,正好对应课程"宽松 vs 严格"两种完成标准的对比:

第一层:schema 校验(validateSchema)。逐条检查每个条目:id 和 category、description 必须是字符串;verification 若存在必须是数组;passes 若存在必须是布尔值。任何缺失或类型错误都会被记入 schemaErrors,最终导致该条目标为 INVALID。

第二层:证据校验(checkEvidence)。这是整份脚本的灵魂,直接实现 pass-state gating 的"不可逆"语义:

const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;
const markedPassWithoutEvidence = entry.passes === true && !hasVerification;

即:一个条目标成 passes: true 却没有任何验证步骤,就会被标记为 "FLAGGED: passes without evidence!"。验证器只做两件事——判定 schema 是否合法、判定"通过"是否有证据——然后把结果汇总成结构化报告(run)。这就是课程说的"agent 不能自己把状态改成 passing,只能提交验证请求,由 harness 执行命令并决定是否允许转移"的代码化形态。

演示数据与输出解读

脚本在读取真实 feature_list.json 之外,还注入了三组演示数据(demoEntries),恰好覆盖了课程要对比的几种情形:

条目 情形 判定
qna-001(真实文件) 有完整 5 步验证、passes: false schema OK,尚未通过
qna-002(演示) 有验证步骤、passes: true 通过且有证据,健康
qna-003(演示) verification: [](空数组)但 passes: true FLAGGED:无证据标通过
missing-fields(演示) 缺 category 和 description schema INVALID

运行后输出一张表格 + 汇总(SUMMARY),最后给出健康度结论:若有 passes: true 但无验证证据的条目,会打印 WARNING: N feature(s) marked as "pass" without any verification evidence.,并提示"这些功能在获得验证之前不可信";反之打印 All passing features have verification evidence. Feature list is healthy.。

这个设计把"宽松验证(代码无语法错误)会带来假阳性"的抽象论述,变成了可执行的工程红线:没有验证步骤的"通过"本身就是不合格的。

通过门控策略(pass-gate-policy)

代码目录里的 pass-gate-policy.md 用一份策略文档规定了从 passes: false 到 passes: true 的唯一通道。一个功能只有在同时满足以下四个条件时才允许通过门控:

  • 预期工作流已被执行(el flujo de trabajo esperado ha sido ejecutado):验证跑的是真实行为路径,而不是"代码能编译";
  • 成功证据已被记录(la evidencia de éxito está registrada):通过结论必须有可复查的记录;
  • 被测路径上没有阻塞性错误(no hay errores bloqueantes en la ruta probada);
  • 实现没有让应用处于破坏或模糊状态(la implementación no deja la app en un estado roto o ambiguo)。

这份策略文档与验证器脚本是一体两面:策略定义"何时允许通过",验证器在代码层强制"通过必须附带证据"。策略是给 agent 和人读的契约,验证器是给系统执行的守卫——这正是"文档 vs 原语"区分在实践中的落地。

仓库配套:harness-creator 中的功能清单原语

功能清单不是孤立的文件,它在仓库的 harness-creator 技能(skills/harness-creator/SKILL.md)中被定义为五大子系统之一。SKILL.md 的核心模型把每个有用的编码 agent harness 拆成五块:

子系统 最小产物 职责
Instructions AGENTS.md / CLAUDE.md 启动路径、工作规则、定义完成
State feature_list.json、progress.md 当前功能、状态、证据、下一步
Verification init.sh 或文档化命令 声称完成前必须跑通的检查
Scope 功能依赖与完成标准 防止越界与半成品
Lifecycle session-handoff.md、会话收尾例行 让下一次会话可重启

功能清单横跨 State 与 Scope 两个子系统:既是状态追踪的单一权威来源,又是范围控制的执行器。

模板中的 feature_list.json

create-harness 脚本(scripts/create-harness.mjs)生成的最小模板(templates/feature-list.json)给出了另一个字段范式:

{
  "features": [
    {
      "id": "feat-001",
      "name": "Project Setup",
      "description": "Confirm the project can install dependencies, run verification, and start from a clean checkout",
      "dependencies": [],
      "status": "not-started",
      "evidence": ""
    }
  ]
}

这里多了两个关键字段:dependencies(依赖追踪) 和 evidence(证据字段)。依赖把功能组织成有向链(feat-002 依赖 feat-001,feat-003 依赖 feat-002……),对应课程中 blocked 状态的来源判断;evidence 字段则从数据结构层面保证了"通过必须有证据可写"。状态取值 not-started 对应课程正文的 not_started,命名风格不同、语义一致。

AGENTS.md 模板与定义完成

指令模板(templates/agents.md)把功能清单嵌入了 agent 的日常行为约束,这些规则全部可以在模板源码中找到对应行:

  • 启动工作流:写代码前必须"读 feature_list.json 查看当前功能状态"、"从清单中选一个未完成的功能"(第 5、13 行附近);
  • 工作规则:"一次只做一个功能"、"不要在没有跑验证命令的情况下声称完成"、"会话结束前更新 progress.md 和 feature_list.json"、"不要修改与当前功能无关的文件"(Stay in scope)、"留下干净状态,让下一次会话能立即跑 ./init.sh";
  • 定义完成(Definition of Done):一个功能只有同时满足"目标行为已实现、必需验证真实跑过、证据已记录在 feature_list.json 或 progress.md、仓库仍可从标准启动路径重启"才算完成;
  • 升级路径:遇到范围歧义时"重新读 feature_list.json 中的 done 定义"。

注意一个细节:模板把 feature_list.json 明确定义为 "source of truth"(单一权威来源),这与课程核心概念完全一致。

自动评分:validate-harness 如何检查功能清单

仓库还把"功能清单是否合格"做成了可自动评分的检查项。评分核心在 scripts/lib/harness-utils.mjs 的 scoreHarness(harness-utils.mjs)中:

  • State 子系统:检查 feature_list.json 或 feature-list.json 是否存在、jsonFeatureList 校验是否通过、progress.md 是否存在、进度日志是否支持重启;
  • Scope 子系统:检查指令中是否有 "One feature at a time" 规则、清单是否追踪 dependencies、状态是否显式(status)、是否有范围边界文档、是否有完成门控(Definition of Done)。

其中 jsonFeatureList(harness-utils.mjs)要求顶层是 features 数组,且每个功能必须同时具备字符串类型的 id、name、description、status——这相当于把"三元组必须完整"做成了机器可判定的规则。运行入口是 scripts/validate-harness.mjs,五子系统各按 1–5 分计,总分默认 70 分及格:

node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project

这一整套"模板生成 → 规则约束 → 自动评分"的链路,正是课程"功能清单是原语而非建议"论断的工程实现:它不是一个靠 agent 自觉遵守的文档,而是被脚本读取、被评分器校验的数据结构。

实施方法:把功能清单落到项目里

课程正文给出了四个可操作的步骤,此处结合仓库证据逐条展开:

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"
}

与仓库 feature_list.json 的字段(id/category/description/verification/passes)对照,可见核心是稳定的:id 定位功能、行为描述、验证命令、状态、证据。建议把验证命令写成真实可执行的一条命令或一份步骤清单——正如仓库示例中 qna-001 的 5 步验证那样。

2. 让 harness 控制状态转移

agent 不能直接把状态改成 passing。它只能提交验证请求,由 harness 执行验证命令、根据结果决定是否允许转移。仓库中 feature-list-validator.ts 的 markedPassWithoutEvidence 检查就是这条规则的可执行版本——任何"无证据的通过"都会被标记并告警。

3. 在 CLAUDE.md 里写清楚规则

课程给出的规则块:

## 功能清单规则
- 功能清单文件: /docs/features.md
- 每次只激活一个功能项
- 功能项验证命令必须通过才能标为 passing
- 不要修改功能清单的状态,由验证脚本自动更新

对照仓库 templates/agents.md,会发现这正是"One feature at a time"、"Verification required"、"Update artifacts"、"由脚本自动更新"等规则的语言化呈现。规则文件负责约束 agent 行为,清单文件负责承载事实,两者职责分离。

4. 粒度校准

每个功能项应控制在"一次会话能完成"的范围:太粗做不完,太细管理开销大。课程给了三个对比刻度:

  • 好粒度:"用户可以添加商品到购物车"
  • 太粗:"实现购物车"
  • 太细:"创建 Cart 模型的 name 字段"

教学示意:备忘录 vs 结构化

课程用一个电商平台开发任务(10 个功能项)对比两种追踪方式(明确标注为教学示意,数字用于解释机制而非实验测量):

备忘录模式:agent 用非结构化笔记记录进度。3 个会话后笔记变成"做了用户认证和商品列表、购物车基本完成但还有 bug、支付没开始"。新会话需要 20 分钟推断状态,最终重复实现了已完成的功能。

结构化模式:每个功能项有明确状态和验证命令。新会话读取功能清单,3 分钟内知道:F01–F05 是 passing,F06 是 active,F07–F10 是 not_started,直接从 F06 继续,零重复。

这组对比可以直接映射到仓库证据:非结构化笔记对应"对话里的非结构化描述"(被课程否定的做法),结构化模式对应 feature_list.json + 验证器的机制。课程正文明确说明此处的分钟数是教学设定值,非实验结论。

关联实战:Project 04

第 08 讲在课程路线中对应实战项目 Project 04. 用运行反馈修正 agent 的行为(projects/project-04/README.md 明确列出 Lecture 08 为关联课程)。该项目的主题是运行时反馈与结构边界控制:在 starter/ 中埋入一个分块 bug(超长文件可能产生空 chunk),要求 agent 借助结构化日志定位它,并用架构边界检查脚本(scripts/check-architecture.sh)防止越界。

其参考实现(projects/project-04/solution/AGENTS.md)是功能清单思想的延伸应用:虽然该阶段刻意不引入 feature_list.json(说明文件明确写道"Do not assume feature_list.json... exist in this project. Those artifacts are introduced in other project stages."),但它完整继承了"Definition of Done"与"一次只做一个功能"的门控精神,并补充了可验证的完成条件(npm run check 通过、check-architecture.sh 无违规、证据记录在最终摘要中)。这体现了课程体系的递进设计:功能清单作为原语先在理论课上确立,再在不同项目阶段以不同形态落地。

核心要点

  • 功能清单是 harness 的基础结构,不是给人看的备忘录。调度器、验证器、交接器、进度追踪器都依赖它。
  • 每个功能项必须有三元组:行为描述 + 验证命令 + 当前状态。缺一项就不完整,像缺了一条腿的三脚凳。
  • 状态转移由 harness 控制,agent 不能自己改状态;通过验证是唯一的升级路径,且 passing 不可逆。
  • 功能清单是项目的单一权威来源:所有"该做什么"的信息都从这里派生,不允许与对话记录矛盾。
  • 粒度控制在"一次会话能完成"的范围:太粗做不完,太细管不过来。
  • "通过"必须有证据:仓库验证器把"passes: true 但无验证步骤"直接标记为告警,这是 pass-state gating 的机器可执行形态。

仓库内延伸阅读

练习

  1. 功能清单设计:定义一个最小化的功能清单 JSON schema,包含 id、行为描述、验证命令、当前状态、证据引用,并用它描述一个包含 5 个功能的真实项目。
  2. 验证严格性对比:选 3 个功能,分别设计"宽松"验证(如"代码无语法错误")和"严格"验证(如"端到端测试通过"),对比两种验证下的假阳性率。
  3. 单一来源原则审查:审查一个已有的 agent 项目,找出与功能清单矛盾的范围信息(对话里的隐式需求、代码里的 TODO 注释等),设计统一方案把所有信息收敛到功能清单中。
登录后查看全文
learn-harness-engineering