learn-harness-engineering 干净状态检查清单Clean State Checklist实战指南如何阻止 Agent 过早宣告胜利【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读本文聚焦 learn-harness-engineering 项目中Agent 过早宣告胜利premature victory declaration这一核心故障模式系统讲解干净状态检查清单Clean State Checklist这一关键 harness 工具它定义了会话结束时系统必须满足的最小状态约束是外部化完成判定、阻断虚假胜利的核心手段。读完本文你将掌握清单的四项检查标准、三层验证架构的实现思路并能结合仓库中的真实清单文件、victory-detector 可执行示例与多个练习项目在自己的 agent 工作区中落地一套可执行的完成判定体系。问题背景为什么 Agent 总是提前交卷在 Lecture 09Evita que los agentes declaren victoria demasiado pronto 中作者描述了一个典型场景你让 Agent 实现密码重置功能它修改了数据库 schema、写完 API endpoint、加上邮件模板单元测试全绿然后自信地说搞定了。但真正运行起来才发现——邮件服务配置缺失、数据库迁移跑到一半失败、端到端流程一次都没跑过。这不是孤立事件。Guo 等人在 2017 年 ICML 上的经典论文已经证明现代神经网络在系统性地过度自信——模型报告的置信度显著高于其真实精度。AI 编码 Agent 同样如此它觉得自己完成了实际上还差得远。因此 harness 必须用外部化、基于执行的验证来替代 Agent 的感觉。这种虚假完成几乎总是遵循同一条滑坡路径La pendiente resbaladiza代码看起来正确语法对、逻辑合理、静态分析无明显错误→ harness 没有强制完整执行验证 → Agent 跳过真实运行或只跑部分测试跑了单元测试跳过集成测试跑了测试不查覆盖率→代码看起来没问题被当作功能已完成的证据 → 提前交卷。任务规格、代码实现、运行时行为这三者之间的每次转换都可能引入偏差每次跳过的验证都会加剧信息不对称。干净状态检查清单文档原文与四项核心标准本仓库docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md用最简形式给出了该清单的完整定义共四条这是整个完成判定体系的最低约束La app arranca sin reparación manual—— 应用无需手动修复即可启动构建必须通过、标准启动路径必须可用而不是需要人工修一下才能跑。El progreso actual está registrado—— 当前进度已记录已完成/进行中/未开始的子任务及其状态必须沉淀为机器可读的记录如 feature_list.json、session-handoff.md。No queda ningún paso de importación o indexación a medias sin documentar—— 不允许存在未记录的半完成导入或索引步骤临时产物、半途而废的迁移、未跑完的索引任务必须清理或显式记录。El siguiente agente puede ejecutar la ruta estándar de inicio y verificación inmediatamente—— 下一个 Agent 可以立即执行标准的启动与验证路径环境初始化、代码库加载、上下文获取、任务选择等路径都不能被破坏。中文版本位于 docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md内容一致可作为对照阅读。这四项标准之所以干净而非复杂是因为它们指向一个共同目标让下一个会话无需诊断历史遗留问题即可直接开工。这正是 Lecture 12《Leave a Clean Handoff at the End of Every Session》中clean state概念的最小化表达——该讲展开为五个维度构建通过、测试通过、进度记录、无残留产物、启动路径可用而本清单用四条语句浓缩了其中最关键的可执行判定。详细展开可参考 Lecture 12 完整讲稿。三层验证架构把感觉完成变成验证完成干净状态清单不是孤立文件它必须挂在可执行的完成判定链路上。Lecture 09 给出了三层验证模型Verificación de terminación en tres capas第 1 层语法与静态分析。成本最低、信息量最少但必须通过——这是最小验证相当于先保证单词拼写正确。第 2 层运行时行为验证。执行测试、应用启动检查、关键路径校验——这是完成判定的核心证据。只写出来不行必须跑起来。第 3 层系统级确认。端到端测试、集成验证、用户场景模拟——这是对抗过早宣告的最后防线。只跑起来不行必须跑得对。三条验证呈严格递进关系第 1 层失败不得进入第 2 层第 2 层失败不得进入第 3 层。与之配套的是完成优先级约束Restricción de prioridad de finalización先验证功能正确性再处理性能最后才谈风格在核心功能通过验证之前禁止重构。Knuth 的过早优化是万恶之源在 Agent 场景下有了新含义——重构会改变已验证代码与未验证代码之间的边界可能破坏原本隐式正确的代码路径。相关核心概念速览Lecture 09 定义了五个与清单配套的关键概念构成理解该工具的理论框架过早完成声明Declaración prematura de finalizaciónAgent 声称任务完成但仍有未满足的正确性规格。核心问题在于Agent 基于代码层面的局部置信度做判断而系统层面的正确性需要全局验证。置信度校准偏差Sesgo de calibración de confianzaAgent 自报完成置信度与实际完成质量之间的系统性差距。对多文件复杂任务这个偏差显著为正——Agent 永远比实际表现更自信。完成标准Criterios de terminación在 harness 中定义的一组清晰、可执行的判定条件Agent 必须全部满足才能宣告完成。Done从主观判断变成客观判定。验证-校验双门Verificación-Validación de doble puerta第一层验证检查代码是否正确实现了规定行为第二层校验检查系统级行为是否满足端到端需求两层都必须通过。运行时反馈信号Señales de retroalimentación en tiempo de ejecución程序运行的日志、进程状态、健康检查是 harness 判断完成质量的客观依据。为什么单元测试通过不等于任务完成这是最常见的陷阱也是最危险的。单元测试的设计哲学——隔离被测单元、mock 掉依赖——恰恰使它们无法发现组件间问题。Lecture 09 给出三类典型失败接口不兼容render 进程传给 preload 脚本的文件路径是相对路径但 preload 期望绝对路径各自单元测试用了 mock 全部通过只有端到端测试才能暴露问题。状态传播错误数据库迁移改了表 schema但 ORM 的缓存层仍持有旧 schema 的缓存条目单元测试每次提供全新 mock 环境暴露不了跨层状态不一致。环境依赖代码在测试环境全部 mock中行为正确在真实环境却因配置差异、网络延迟或服务不可用而失败。更隐蔽的问题来自两处顺手重构是完成判定的毒药。Claude Code 有个常见行为模式核心功能还没通过验证就开始重构代码、优化性能、改进风格。重构改变了已验证与未验证代码的边界可能破坏原本隐式正确的路径——就像没做完大题就去重抄选择题答案浪费时间还可能抄错。自评存在系统性偏差。Anthropic 2026 年的研究发现了更深层的失败模式当 Agent 被要求评估自己的工作它会系统性地给出过度积极的评价——即使人类观察者认为质量明显不达标。在主观任务如设计美学中尤其严重。解决方案不是让 Agent更客观生成和评估用同一个模型天然倾向对自己宽容而是把工人和检验员分开一个独立、被调教成苛刻的评估 Agent远比让生成 Agent 自评有效。Lecture 09 引用的实验数据佐证了这一点——同样的模型Opus 4.5、同样的 promptbuild a 2D retro game editor仅凭 harness 差异就从裸跑 20 分钟 $9 且核心功能不可用变成planner generator evaluator 三 Agent 6 小时 $200、游戏完全可玩。如何构建你的干净状态清单与完成判定1. 在 CLAUDE.md 中显式声明 Definition of Done完成判定不应由 Agent 自己做。harness 必须独立执行终止验证以运行时信号为输入而非 Agent 的置信度。Lecture 09 建议在CLAUDE.md中写入## Definition of Done - Feature complete end-to-end verification passed, not code is written - Required verification levels: 1. Unit tests pass 2. Integration tests pass 3. End-to-end flow verification passes - Do not proceed to level 2 if level 1 fails - Do not proceed to level 3 if level 2 fails2. 为 Agent 设计红笔批注式的错误信息OpenAI 在 Codex 实践中引入了一个特别有效的模式给 Agent 的错误信息必须包含修正指令。不要像偷懒的阅卷老师那样只画个红叉要像好老师一样在页边写下你应该这样改。不要用Test failed而要用Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html.这种具体、可操作的反饋能让 Agent 无需人工干预地自我纠错。3. 捕获运行时信号有效的运行时信号包括应用是否成功启动并达到就绪状态关键功能路径在运行时是否成功执行数据库写入、文件操作等副作用是否正确临时资源是否已清理。这些信号是清单第 1 条无需手动修复即可启动和第 3 条无未记录半成品的客观判据。仓库中的真实清单从 4 条到 30 项的落地范例本仓库并非只有理论。多个练习项目把这份 4 条清单扩展成了可直接复用的完整落地版本展示了干净状态如何逐级深化。Project 03多会话连续性场景的清单projects/project-03/solution/clean-state-checklist.md 将 4 条核心标准展开为五个分组、数十项可勾选检查Build Verificationnpm install无错、npm run check零 TypeScript 错误、npm run build产出 dist/。Feature Verification窗口以正确尺寸与深色主题启动、文档导入、文档详情元数据、View Content、Show Chunks、Index Document、状态栏索引状态与计数、问答面板带引用与置信度0.85 有引用 / 0.30 无引用、重启持久化、删除功能——共 14 项功能点全部勾选。Scope Control Verificationfeature_list.json全部为 pass、每项 feature 有 evidence 描述实现内容、无 fail 或 not-started、AGENTS.md含 one-feature-at-a-time 策略。Code Quality无未经注释的any、全部具名导出、IPC 通道只在src/shared/types.ts定义、renderer 不导入 Node.js 模块、services 不导入 renderer 代码。Documentationdocs/ARCHITECTURE.md与docs/PRODUCT.md已更新、session-handoff.md已填写、claude-progress.md有会话日志。其中Scope Control Verification分组直接对应清单第 2 条当前进度已记录——feature_list.json 就是机器可读的进度记录载体每个 feature 带id、name、description、status、evidence、testedAt字段例如grounded-qa的 evidence 记录了 QaService 如何检索 chunks、按关键词重叠打分、返回 top 2 引用置信度 0.85/0.30 的取值依据都写在其中。Project 06可观测性收官项目的 30 项全检projects/project-06/solution/clean-state-checklist.md 进一步扩展为八个分组约 30 项检查并明确要求Run this checklist before committing and at the end of each session。除了构建、架构边界、运行时功能外新增了Logging所有日志为可解析 JSON、含 timestamp/level/service/message、文档导入发 INFOdocumentId、filename、size、索引发 INFOchunkCount、durationMs、QA 发 INFOconfidence、citationCount、durationMs。Data Integrity索引文档无空 chunk、问答历史与反馈跨重启持久、元数据与实际文件一致、clean state reset 删除所有数据文件。Performancebash scripts/benchmark.sh无错、3 文件导入 1s、样本数据索引 1s、单问查询延迟 1s。Repositorygit status 无意外文件、无敏感数据、dist/ 不入库、claude-progress.md、feature_list.json、session-handoff.md全部同步。Scriptscleanup-scanner.sh无陈旧产物、benchmark.sh跑完全套任务、init.sh通过所有验证步骤。该项目的 quality-document.md 则是清单第 2 条的进阶形态——一张持续追踪代码库健康度的质量文档按维度打分Build Compile、Feature Completeness、Structured Logging、Test Coverage、Benchmarking、Cleanup Scanner 等 15 个维度整体评级 A并明确标注Verified Against30 项检查全过、evaluator-rubric.md5.0/5、15/15 功能 pass、benchmark 与 cleanup-scanner 全部通过。这与 Lecture 12 的质量文档让代码库健康度可追踪主张完全一致。可运行演示victory-detector.ts代码目录 中的 victory-detector.ts 用 TypeScript 模拟了Agent 声称完成 vs 实际验证的差距。它定义了Task含claimedComplete与一组VerificationCheck每个 check 同时记录claimedAgent 说的与actual真实情况严重度分critical/warning两级verifyTask()计算声明通过数、实际通过数与gaps声称通过但实际失败run()输出逐任务明细表与总体汇总False victories、Total undetected gaps。三个内置案例完美复现了本清单要防的故障Add search endpoint声称完成但认证中间件未加、集成测试根本没跑Fix pagination bug只测了 happy path、回归测试缺失Refactor auth module旧代码未删、两个现有测试被改挂。运行方式npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts该命令在仓库根目录执行说明文件内给出的运行命令与此路径一致可对照 victory-detector.ts 头部注释。运行后你会看到所有任务都被 Agent 声明为 COMPLETE但验证结果显示多项 critical 检查存在 GAP——这正是指南要传达的核心信息没有显式验证过早宣告就永远不会被拦截。实战案例密码重置功能的正确验证路径Lecture 09 给出了一个完整案例演示清单如何在实际任务中拦截虚假胜利任务实现用户密码重置功能涉及数据库操作、邮件发送、API endpoint 修改。过早交付路径Agent 修改数据库 schema、写 API endpoint、加邮件模板、跑单元测试通过、宣告完成——卷子写满了。实际缺陷(1) 端到端流程未测——重置链接的真实发送与验证从未确认(2) 数据库迁移部分执行后失败导致 schema 不一致(3) 目标环境缺少邮件服务配置。harness 干预强制终止验证——(1) 启动完整应用验证重置 endpoint 可达(2) 执行完整重置流程(3) 校验数据库状态一致性。所有缺陷在会话内被发现节省了 5–10 倍的后期修复成本——独立阅卷人发现了真正的问题。关键要点与动手练习关键要点Agent 在系统性过度自信——置信度校准偏差是客观现实卷子写满了不等于考好了。完成判定必须外部化——harness 独立验证不要相信 Agent 的感觉学生不能给自己打分。三层验证缺一不可——语法过、行为过、系统过逐层推进。错误信息要像好老师的红笔批注——包含具体修正步骤让 Agent 能自我纠错。核心功能验证通过前禁止重构——完成优先级约束是防止过早优化的关键。清单是完成判定的必要组件——把 4 条核心标准挂到构建、功能、运行时、文档等可执行检查上干净状态才会从口号变成门槛。动手练习来自 Lecture 09设计完成验证函数为数据库迁移 API 修改任务设计完整终止验证列出每项所需运行时信号及其通过/拒绝标准在真实任务上运行并记录发现的隐藏问题。测量校准偏差选 10 类编码任务记录 Agent 自报完成置信度 vs 实际完成质量计算偏差值并分析其与任务复杂度的关系。多层防御实验在相同任务集上跑三种配置——(a) 仅静态分析(b) 加单元测试(c) 完整三层验证——对比过早完成声明比例与漏检缺陷数。延伸阅读Lecture 09 完整讲稿西语Lecture 12Every Session Must Leave a Clean State英语Project 03Multi-Session Continuity 项目与清单Project 05让 Agent 验证自己的工作Grounded QA VerificationProject 06运行时可观测性与调试含 30 项清单与质量文档【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 learn-harness-engineering 干净状态检查清单（Clean State Checklist）实战指南：如何阻止 Agent 过早宣告胜利
learn-harness-engineering 干净状态检查清单Clean State Checklist实战指南如何阻止 Agent 过早宣告胜利【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读本文聚焦 learn-harness-engineering 项目中Agent 过早宣告胜利premature victory declaration这一核心故障模式系统讲解干净状态检查清单Clean State Checklist这一关键 harness 工具它定义了会话结束时系统必须满足的最小状态约束是外部化完成判定、阻断虚假胜利的核心手段。读完本文你将掌握清单的四项检查标准、三层验证架构的实现思路并能结合仓库中的真实清单文件、victory-detector 可执行示例与多个练习项目在自己的 agent 工作区中落地一套可执行的完成判定体系。问题背景为什么 Agent 总是提前交卷在 Lecture 09Evita que los agentes declaren victoria demasiado pronto 中作者描述了一个典型场景你让 Agent 实现密码重置功能它修改了数据库 schema、写完 API endpoint、加上邮件模板单元测试全绿然后自信地说搞定了。但真正运行起来才发现——邮件服务配置缺失、数据库迁移跑到一半失败、端到端流程一次都没跑过。这不是孤立事件。Guo 等人在 2017 年 ICML 上的经典论文已经证明现代神经网络在系统性地过度自信——模型报告的置信度显著高于其真实精度。AI 编码 Agent 同样如此它觉得自己完成了实际上还差得远。因此 harness 必须用外部化、基于执行的验证来替代 Agent 的感觉。这种虚假完成几乎总是遵循同一条滑坡路径La pendiente resbaladiza代码看起来正确语法对、逻辑合理、静态分析无明显错误→ harness 没有强制完整执行验证 → Agent 跳过真实运行或只跑部分测试跑了单元测试跳过集成测试跑了测试不查覆盖率→代码看起来没问题被当作功能已完成的证据 → 提前交卷。任务规格、代码实现、运行时行为这三者之间的每次转换都可能引入偏差每次跳过的验证都会加剧信息不对称。干净状态检查清单文档原文与四项核心标准本仓库docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md用最简形式给出了该清单的完整定义共四条这是整个完成判定体系的最低约束La app arranca sin reparación manual—— 应用无需手动修复即可启动构建必须通过、标准启动路径必须可用而不是需要人工修一下才能跑。El progreso actual está registrado—— 当前进度已记录已完成/进行中/未开始的子任务及其状态必须沉淀为机器可读的记录如 feature_list.json、session-handoff.md。No queda ningún paso de importación o indexación a medias sin documentar—— 不允许存在未记录的半完成导入或索引步骤临时产物、半途而废的迁移、未跑完的索引任务必须清理或显式记录。El siguiente agente puede ejecutar la ruta estándar de inicio y verificación inmediatamente—— 下一个 Agent 可以立即执行标准的启动与验证路径环境初始化、代码库加载、上下文获取、任务选择等路径都不能被破坏。中文版本位于 docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md内容一致可作为对照阅读。这四项标准之所以干净而非复杂是因为它们指向一个共同目标让下一个会话无需诊断历史遗留问题即可直接开工。这正是 Lecture 12《Leave a Clean Handoff at the End of Every Session》中clean state概念的最小化表达——该讲展开为五个维度构建通过、测试通过、进度记录、无残留产物、启动路径可用而本清单用四条语句浓缩了其中最关键的可执行判定。详细展开可参考 Lecture 12 完整讲稿。三层验证架构把感觉完成变成验证完成干净状态清单不是孤立文件它必须挂在可执行的完成判定链路上。Lecture 09 给出了三层验证模型Verificación de terminación en tres capas第 1 层语法与静态分析。成本最低、信息量最少但必须通过——这是最小验证相当于先保证单词拼写正确。第 2 层运行时行为验证。执行测试、应用启动检查、关键路径校验——这是完成判定的核心证据。只写出来不行必须跑起来。第 3 层系统级确认。端到端测试、集成验证、用户场景模拟——这是对抗过早宣告的最后防线。只跑起来不行必须跑得对。三条验证呈严格递进关系第 1 层失败不得进入第 2 层第 2 层失败不得进入第 3 层。与之配套的是完成优先级约束Restricción de prioridad de finalización先验证功能正确性再处理性能最后才谈风格在核心功能通过验证之前禁止重构。Knuth 的过早优化是万恶之源在 Agent 场景下有了新含义——重构会改变已验证代码与未验证代码之间的边界可能破坏原本隐式正确的代码路径。相关核心概念速览Lecture 09 定义了五个与清单配套的关键概念构成理解该工具的理论框架过早完成声明Declaración prematura de finalizaciónAgent 声称任务完成但仍有未满足的正确性规格。核心问题在于Agent 基于代码层面的局部置信度做判断而系统层面的正确性需要全局验证。置信度校准偏差Sesgo de calibración de confianzaAgent 自报完成置信度与实际完成质量之间的系统性差距。对多文件复杂任务这个偏差显著为正——Agent 永远比实际表现更自信。完成标准Criterios de terminación在 harness 中定义的一组清晰、可执行的判定条件Agent 必须全部满足才能宣告完成。Done从主观判断变成客观判定。验证-校验双门Verificación-Validación de doble puerta第一层验证检查代码是否正确实现了规定行为第二层校验检查系统级行为是否满足端到端需求两层都必须通过。运行时反馈信号Señales de retroalimentación en tiempo de ejecución程序运行的日志、进程状态、健康检查是 harness 判断完成质量的客观依据。为什么单元测试通过不等于任务完成这是最常见的陷阱也是最危险的。单元测试的设计哲学——隔离被测单元、mock 掉依赖——恰恰使它们无法发现组件间问题。Lecture 09 给出三类典型失败接口不兼容render 进程传给 preload 脚本的文件路径是相对路径但 preload 期望绝对路径各自单元测试用了 mock 全部通过只有端到端测试才能暴露问题。状态传播错误数据库迁移改了表 schema但 ORM 的缓存层仍持有旧 schema 的缓存条目单元测试每次提供全新 mock 环境暴露不了跨层状态不一致。环境依赖代码在测试环境全部 mock中行为正确在真实环境却因配置差异、网络延迟或服务不可用而失败。更隐蔽的问题来自两处顺手重构是完成判定的毒药。Claude Code 有个常见行为模式核心功能还没通过验证就开始重构代码、优化性能、改进风格。重构改变了已验证与未验证代码的边界可能破坏原本隐式正确的路径——就像没做完大题就去重抄选择题答案浪费时间还可能抄错。自评存在系统性偏差。Anthropic 2026 年的研究发现了更深层的失败模式当 Agent 被要求评估自己的工作它会系统性地给出过度积极的评价——即使人类观察者认为质量明显不达标。在主观任务如设计美学中尤其严重。解决方案不是让 Agent更客观生成和评估用同一个模型天然倾向对自己宽容而是把工人和检验员分开一个独立、被调教成苛刻的评估 Agent远比让生成 Agent 自评有效。Lecture 09 引用的实验数据佐证了这一点——同样的模型Opus 4.5、同样的 promptbuild a 2D retro game editor仅凭 harness 差异就从裸跑 20 分钟 $9 且核心功能不可用变成planner generator evaluator 三 Agent 6 小时 $200、游戏完全可玩。如何构建你的干净状态清单与完成判定1. 在 CLAUDE.md 中显式声明 Definition of Done完成判定不应由 Agent 自己做。harness 必须独立执行终止验证以运行时信号为输入而非 Agent 的置信度。Lecture 09 建议在CLAUDE.md中写入## Definition of Done - Feature complete end-to-end verification passed, not code is written - Required verification levels: 1. Unit tests pass 2. Integration tests pass 3. End-to-end flow verification passes - Do not proceed to level 2 if level 1 fails - Do not proceed to level 3 if level 2 fails2. 为 Agent 设计红笔批注式的错误信息OpenAI 在 Codex 实践中引入了一个特别有效的模式给 Agent 的错误信息必须包含修正指令。不要像偷懒的阅卷老师那样只画个红叉要像好老师一样在页边写下你应该这样改。不要用Test failed而要用Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html.这种具体、可操作的反饋能让 Agent 无需人工干预地自我纠错。3. 捕获运行时信号有效的运行时信号包括应用是否成功启动并达到就绪状态关键功能路径在运行时是否成功执行数据库写入、文件操作等副作用是否正确临时资源是否已清理。这些信号是清单第 1 条无需手动修复即可启动和第 3 条无未记录半成品的客观判据。仓库中的真实清单从 4 条到 30 项的落地范例本仓库并非只有理论。多个练习项目把这份 4 条清单扩展成了可直接复用的完整落地版本展示了干净状态如何逐级深化。Project 03多会话连续性场景的清单projects/project-03/solution/clean-state-checklist.md 将 4 条核心标准展开为五个分组、数十项可勾选检查Build Verificationnpm install无错、npm run check零 TypeScript 错误、npm run build产出 dist/。Feature Verification窗口以正确尺寸与深色主题启动、文档导入、文档详情元数据、View Content、Show Chunks、Index Document、状态栏索引状态与计数、问答面板带引用与置信度0.85 有引用 / 0.30 无引用、重启持久化、删除功能——共 14 项功能点全部勾选。Scope Control Verificationfeature_list.json全部为 pass、每项 feature 有 evidence 描述实现内容、无 fail 或 not-started、AGENTS.md含 one-feature-at-a-time 策略。Code Quality无未经注释的any、全部具名导出、IPC 通道只在src/shared/types.ts定义、renderer 不导入 Node.js 模块、services 不导入 renderer 代码。Documentationdocs/ARCHITECTURE.md与docs/PRODUCT.md已更新、session-handoff.md已填写、claude-progress.md有会话日志。其中Scope Control Verification分组直接对应清单第 2 条当前进度已记录——feature_list.json 就是机器可读的进度记录载体每个 feature 带id、name、description、status、evidence、testedAt字段例如grounded-qa的 evidence 记录了 QaService 如何检索 chunks、按关键词重叠打分、返回 top 2 引用置信度 0.85/0.30 的取值依据都写在其中。Project 06可观测性收官项目的 30 项全检projects/project-06/solution/clean-state-checklist.md 进一步扩展为八个分组约 30 项检查并明确要求Run this checklist before committing and at the end of each session。除了构建、架构边界、运行时功能外新增了Logging所有日志为可解析 JSON、含 timestamp/level/service/message、文档导入发 INFOdocumentId、filename、size、索引发 INFOchunkCount、durationMs、QA 发 INFOconfidence、citationCount、durationMs。Data Integrity索引文档无空 chunk、问答历史与反馈跨重启持久、元数据与实际文件一致、clean state reset 删除所有数据文件。Performancebash scripts/benchmark.sh无错、3 文件导入 1s、样本数据索引 1s、单问查询延迟 1s。Repositorygit status 无意外文件、无敏感数据、dist/ 不入库、claude-progress.md、feature_list.json、session-handoff.md全部同步。Scriptscleanup-scanner.sh无陈旧产物、benchmark.sh跑完全套任务、init.sh通过所有验证步骤。该项目的 quality-document.md 则是清单第 2 条的进阶形态——一张持续追踪代码库健康度的质量文档按维度打分Build Compile、Feature Completeness、Structured Logging、Test Coverage、Benchmarking、Cleanup Scanner 等 15 个维度整体评级 A并明确标注Verified Against30 项检查全过、evaluator-rubric.md5.0/5、15/15 功能 pass、benchmark 与 cleanup-scanner 全部通过。这与 Lecture 12 的质量文档让代码库健康度可追踪主张完全一致。可运行演示victory-detector.ts代码目录 中的 victory-detector.ts 用 TypeScript 模拟了Agent 声称完成 vs 实际验证的差距。它定义了Task含claimedComplete与一组VerificationCheck每个 check 同时记录claimedAgent 说的与actual真实情况严重度分critical/warning两级verifyTask()计算声明通过数、实际通过数与gaps声称通过但实际失败run()输出逐任务明细表与总体汇总False victories、Total undetected gaps。三个内置案例完美复现了本清单要防的故障Add search endpoint声称完成但认证中间件未加、集成测试根本没跑Fix pagination bug只测了 happy path、回归测试缺失Refactor auth module旧代码未删、两个现有测试被改挂。运行方式npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts该命令在仓库根目录执行说明文件内给出的运行命令与此路径一致可对照 victory-detector.ts 头部注释。运行后你会看到所有任务都被 Agent 声明为 COMPLETE但验证结果显示多项 critical 检查存在 GAP——这正是指南要传达的核心信息没有显式验证过早宣告就永远不会被拦截。实战案例密码重置功能的正确验证路径Lecture 09 给出了一个完整案例演示清单如何在实际任务中拦截虚假胜利任务实现用户密码重置功能涉及数据库操作、邮件发送、API endpoint 修改。过早交付路径Agent 修改数据库 schema、写 API endpoint、加邮件模板、跑单元测试通过、宣告完成——卷子写满了。实际缺陷(1) 端到端流程未测——重置链接的真实发送与验证从未确认(2) 数据库迁移部分执行后失败导致 schema 不一致(3) 目标环境缺少邮件服务配置。harness 干预强制终止验证——(1) 启动完整应用验证重置 endpoint 可达(2) 执行完整重置流程(3) 校验数据库状态一致性。所有缺陷在会话内被发现节省了 5–10 倍的后期修复成本——独立阅卷人发现了真正的问题。关键要点与动手练习关键要点Agent 在系统性过度自信——置信度校准偏差是客观现实卷子写满了不等于考好了。完成判定必须外部化——harness 独立验证不要相信 Agent 的感觉学生不能给自己打分。三层验证缺一不可——语法过、行为过、系统过逐层推进。错误信息要像好老师的红笔批注——包含具体修正步骤让 Agent 能自我纠错。核心功能验证通过前禁止重构——完成优先级约束是防止过早优化的关键。清单是完成判定的必要组件——把 4 条核心标准挂到构建、功能、运行时、文档等可执行检查上干净状态才会从口号变成门槛。动手练习来自 Lecture 09设计完成验证函数为数据库迁移 API 修改任务设计完整终止验证列出每项所需运行时信号及其通过/拒绝标准在真实任务上运行并记录发现的隐藏问题。测量校准偏差选 10 类编码任务记录 Agent 自报完成置信度 vs 实际完成质量计算偏差值并分析其与任务复杂度的关系。多层防御实验在相同任务集上跑三种配置——(a) 仅静态分析(b) 加单元测试(c) 完整三层验证——对比过早完成声明比例与漏检缺陷数。延伸阅读Lecture 09 完整讲稿西语Lecture 12Every Session Must Leave a Clean State英语Project 03Multi-Session Continuity 项目与清单Project 05让 Agent 验证自己的工作Grounded QA VerificationProject 06运行时可观测性与调试含 30 项清单与质量文档【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考