【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读在 harness engineering智能体工程实践中会话结束时留下干净状态是决定多轮 Agent 协作能否长期可用的关键纪律而 clean-state-checklist.md 正是这一纪律的落地模板一份可以在每次会话结束时逐项勾选的验收清单。本文将以该清单模板为骨架结合本仓库 第 12 课、第 9 课 的理论讲解与 project-03、project-04 的真实工程清单系统讲解清单每一项的含义、背后的原理以及如何把一份模板清单裁剪成适合自己仓库的可执行验收单。读完本文你将掌握把会话结束从模糊的感觉做完了升级为客观可验证的干净状态的完整方法。一、清单模板本体六项验收逐条拆解仓库中葡萄牙语版模板 docs/pt-BR/resources/templates/clean-state-checklist.md 给出的是一份最精简、最通用的干净状态清单共六项翻译并逐条解读如下O caminho de inicialização padrão ainda funciona.标准启动路径仍然可用即npm run dev或等价的启动命令依然能拉起应用。这是干净状态最基础的入口条件下一会话的 Agent 打开仓库后第一步必然是启动应用来建立运行期上下文如果启动路径已损坏后续一切验证都无法进行。O caminho de verificação padrão ainda roda.标准验证路径仍然可运行即npm test/npm run check/npm run build等标准验证命令仍然能跑通。它确保上一会话引入的改动没有破坏既有验证链路而不是只保证新功能在我机器上能跑。O progresso atual está registrado no log de progresso.当前进度已记录在进度日志中进度不能只存在于 Agent 的记忆里——会话一旦结束记忆即失效。进度必须落到机器可读的产物中如claude-progress.md、session-handoff.md或feature_list.json让下一会话打开即知做到哪一步。O estado do recurso reflete o que está realmente passando versus o que não foi verificado.功能状态如实反映已通过与未验证的差异这条是防止过早宣告胜利的关键feature_list.json中的每个功能只能标记为已通过验证或尚未验证绝不能把代码写完了但没跑过端到端伪装成通过。Nenhuma etapa inacabada foi deixada sem documentação.没有未完成步骤被遗留且无文档说明半途而废的步骤如只做了一半的迁移、未完成的重构如果不加说明下一会话的 Agent 只能靠猜测来推断哪些是故意的、哪些是临时的——这正是 第 9 课 指出的信息不对称来源。A próxima sessão pode continuar sem a necessidade de reparos manuais.下一会话无需人工修复即可继续这是六项条款的总验收标准环境初始化、代码库加载、上下文获取、任务选择——整条链路必须畅通让下一个 Agent 可以直接开工而不是先花 30 分钟考古上一会话到底做了什么。与模板配套的还有一份更贴近索引/导入型应用场景的变体见 lecture-09 的 code 目录应用无需人工修复即可启动、当前进度已记录、没有遗留未文档化的部分导入/索引步骤、下一个 Agent 能立即执行标准启动与验证流程。对比可见模板是通用骨架具体项目应在此基础上替换为自身的启动命令与验证命令。二、为什么需要这份清单熵增是默认状态干净状态需要主动维护清单看似只有六行背后却对应着 harness 工程最核心的一条经验法则熵增是默认状态干净状态必须靠纪律维持。第 12 课 用 Lehman 软件演化定律说明了这一点持续变更的系统若无主动管理复杂度必然上升。对 AI 编码 Agent 而言每一会话都会引入新改动若不在会话结束清理技术债会指数级累积。OpenAI 在五个月的 Codex 实验中观察到一个显著现象Agent 会照抄仓库中已有的模式即使这些模式本身不一致或欠优——就像公共区域的第一杯咖啡没人收拾第二个人就会想反正已经脏了再放一杯一周后桌面堆满杯子。代码库的腐化遵循完全相同的机制。因此 OpenAI 的解决方案不是周五手动清理 AI 留下的烂摊子他们最初每周五要花 20% 时间做这件事显然不可扩展而是系统性手段把黄金规则写进仓库如优先使用共享工具包而非临时手写的 helper不要对数据结构做随意假设——规则要具体、机械、可自动验证建立周期性清理流水线由后台 Codex 任务定期扫描偏离、更新质量指标、提交针对性重构 PR把人类判断一次性固化、持续复用评审意见、重构 PR、用户反馈的 bug 全部转化为文档更新或直接编码进工具。这份 clean-state-checklist.md 模板正是上述系统性手段在会话粒度上的最小落点把清理从一次性的冲动行为变成每次会话结束的强制检查点。三、干净状态不只是代码能编译五个不可妥协的维度第 12 课 明确指出干净状态 ≠ 代码能编译。编译通过是最低要求还远不够。一个完整定义下的干净状态必须满足五个条件维度含义对应清单项Build 通过无构建错误下一会话无需先修构建第 1、2 项测试通过包括会话之前就已存在的测试不得破坏既有功能且需在 CI 中验证而非在我机器上能跑第 2 项进度已记录完成/进行中/未开始的子任务及其验收标准写入机器可读产物第 3 项无过期产物移除调试日志、临时文件、被注释的代码、TODO 标记第 5 项启动路径可用环境初始化、代码加载、上下文获取、任务选择整条链路畅通第 1、6 项进度记录之所以重要是因为好的进度日志能将下一会话开头的诊断时间减少 60%80%。而临时产物debug 日志、临时文件、注释代码、TODO 标记会显著抬高下一会话的认知负载——Agent 需要花大量精力分辨哪些代码是有意的、哪些是临时的。第 12 课 用 Mermaid 流程图给出了会话结束时的标准判定链路反方向则是脏状态的恶性循环会话带着失败测试、未清理的临时文件、未记录的进度结束 → 下一会话必须先搞清楚发生了什么 → 再在已经混乱的仓库上继续改 → 产生更多调试文件、更多被破坏的检查、更模糊的进度 → 循环往复。第 12 课给出的一组实测数据令人警醒一个不设清理策略、用 Agent 开发 12 周的项目build 成功率从第 1 周的 100% 掉到第 12 周的 68%测试成功率从 100% 掉到 61%新会话启动时间从 5 分钟恶化到超过 60 分钟并遗留 103 个过期产物而采用会话结束完整干净状态检查 每周清理循环的对照项目12 周后 build 成功率仍达 97%、测试成功率 95%、新会话启动 9 分钟、仅 11 个过期产物。实验组每会话只多花约 5 分钟清理却在整个周期内省下数十小时的混乱成本。四、把模板清单改造成自己仓库的验收单来自本仓库的真实案例模板是通用骨架落地必须项目化。本仓库的实战项目给出了两个层次分明的真实范例。4.1 project-03面向功能 作用域的清单projects/project-03/solution/clean-state-checklist.md 将模板扩展为五个分组、数十项可勾选项Build Verificationnpm install无错、npm run check零 TypeScript 错误、npm run build产出 dist/ 输出——对应模板第 1、2 项Feature Verification窗口尺寸与暗色主题、文档列表空态、导入 .txt/.md、元数据展示、分块与索引、状态栏、QA 引用与置信度、跨重启持久化、删除功能——逐条把功能状态如实反映通过与否落到具体 UI 行为Scope Control Verificationfeature_list.json所有功能为pass、每项功能附实现证据、无fail或not-started、AGENTS.md含一次只做一个功能策略、功能依赖已文档化——这是模板第 4 项状态如实反映的工程化展开Code Quality无无注释的any、统一具名导出、IPC 通道只在src/shared/types.ts定义、renderer 不 import Node 模块、service 不 import renderer 代码——把干净下沉到架构约束层面Documentationdocs/ARCHITECTURE.md与docs/PRODUCT.md已更新、session-handoff.md已填写、claude-progress.md有会话日志——对应模板第 3、5 项。这份清单证明了模板六项 → 项目几十项的裁剪路径每一项模板条款都可以替换成自己仓库里真实存在的命令、文件路径与可勾选行为。4.2 project-04面向架构 运行时可观测性的清单projects/project-04/solution/clean-state-checklist.md 则展示了另一种维度划分特别强调提交前与每会话结束时运行Buildnpm run check无类型错误、npm run build成功Architecturebash scripts/check-architecture.sh无违规、renderer 无fs/pathimport、service 代码无 Electron IPC、service/main 无 React import——用脚本把架构约束变成可自动验证的检查Runtime应用npm run dev无错启动、控制台输出结构化日志、文档导入正常检查IMPORT_DOCUMENT事件日志、各尺寸文档索引正常、QA 带引用返回检查ASK_QUESTION事件日志——把启动路径可用细化为可观察的运行时信号与 第 11 课可观测性属于 harness 内部 一脉相承Data Integrity索引文档无空 chunk、QA 历史跨重启持久化、文档元数据与真实文件一致Repositorygit status 无意外文件、无敏感数据.env、凭据被暂存、最终摘要记录当前状态/验证运行/未解决风险、且AGENTS.md、docs/ARCHITECTURE.md与清单本身仍与真实文件匹配。project-04 清单的亮点在于清单本身也要与仓库保持一致——当清单描述的文档路径已不存在时清单就成了新的债务来源。此外仓库中 project-05 与 project-06 的 solution 目录也各自维护了一份适配自身场景的清单可作为不同技术栈/不同阶段项目裁剪时的对照样本。五、配套概念与落地要点让干净状态真正被执行第 12 课 给出了让清单真正生效的六个关键概念与做法5.1 概念支撑Clean state干净状态会话结束须满足五条件——build 通过、测试通过、进度已记录、无过期产物、启动路径可用缺任一条件会话都不算完成。Session integrity会话完整性类比数据库事务——要么完整提交并留下干净状态要么回滚到最近的一致状态不存在中间地带。Quality document质量文档持续记录各模块质量评分的活动产物而非一次性分析新会话读它即可知道该优先修复哪个模块。Cleanup loop清理循环定期的维护型会话系统性降低代码库熵值——是例行操作不是应急修补。其典型任务见 cleanup-loop.md扫描过期文档、扫描结构违规、更新质量评级、提交针对性清理 PR、清理后重跑固定切片的 benchmark。Harness simplificationharness 简化随模型能力演进定期移除已无必要的 harness 组件——今天的必要约束三个月后可能只是多余负担。Idempotent cleanup幂等清理清理操作无论执行多少次结果一致保证在失败重试场景下依然安全。5.2 两个落地模式即时清理每会话结束移除会话中产生的临时产物、更新功能列表状态、确保 build 与测试通过。这是引用计数式清理——用完即清。周期清理每周全系统扫描处理累积的结构性问题、更新质量文档、跑 benchmark 检测偏离。这是追踪式清理——按固定节奏做全面维护。5.3 写入 harness 的完成定义要让清单不止于倡议必须把它写进 Agent 的指令文件把完成定义改为会话完成 任务通过验证 干净状态检查通过两者缺一即未完成。参考 第 12 课 给出的CLAUDE.md片段## 会话收尾检查清单 - [ ] Build 通过npm run build - [ ] 所有测试通过npm test - [ ] 功能列表已更新 - [ ] 无残留调试代码console.log、debugger、TODO - [ ] 标准启动路径可用npm run dev同时第 9 课 的完成判定外部化原则同样适用于清单检查不要依赖 Agent 自我感觉而是由 harness 用运行时信号应用是否成功启动并就绪、关键路径是否在运行时执行成功、副作用是否正确发生、临时资源是否清理独立执行验证。清单第 4 项功能状态如实反映通过与未验证正是这一原则的直接产物——把已通过端到端验证与仅写了代码未验证严格区分是堵住 Agent过早宣告胜利这一系统性问题最有效的护栏。六、行动建议从模板到落地的最小路径复制模板替换命令以 docs/pt-BR/resources/templates/clean-state-checklist.md 为起点把标准启动路径标准验证路径替换为仓库真实的npm run dev、npm run check、npm run build、npm test明确进度与功能状态的载体约定进度写入哪个文件如claude-progress.md、session-handoff.md功能状态写入哪个文件如feature_list.json并写明未验证≠通过添加架构与数据约束参照 project-04 清单 增加脚本化架构检查、运行时事件日志检查、数据完整性检查固化到指令文件将清单要点写入CLAUDE.md/AGENTS.md的会话收尾检查清单与功能列表feature list等 harness 原语协同工作坚持幂等所有清理脚本必须可重复执行且无副作用如rm -f /tmp/debug-*.log用-f保证文件不存在时不报错git checkout -- .env.local恢复到已知状态清理后重跑npm run test确认没有破坏任何东西定期复审清单本身像 project-04 要求的那样确保清单描述的路径、命令与仓库现状一致否则清单本身就会变成新的技术债。核心结论所谓下次再清理等于永远不清理——熵增是默认状态只有主动的、以清单为载体的干净状态纪律才能对抗它。把这份六项模板变成自己仓库里每次会话结束的硬性验收单是让多会话 Agent 协作从每 12 周腐化到不可用走向长期稳定可维护的关键一步。进一步了解完整理论可精读 第 12 课全文 与 第 9 课全文并对照 project-03 与 project-04 的真实清单进行裁剪实践。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐干净状态检查清单Clean State Checklist为 Agent 会话收尾建立可验证的完成标准干净状态检查清单Clean State Checklist为 Agent 会话收尾建立可验证的完成标准 导读 本文围绕 learn harness englearn-harness-engineering 干净状态检查清单Clean State Checklist实战指南让每个 Agent 会话都以可继续的状态收尾learn harness engineering 干净状态检查清单Clean State Checklist实战指南让每个 Agent 会话都以可继续的Learn Harness Engineering用 Clean State Checklist 为每个 Agent 会话画上干净的句号Learn Harness Engineering用 Clean State Checklist 为每个 Agent 会话画上干净的句号 导读 在多会话mu上一篇深度解析OpenCore Legacy Patcher如何实现老款Mac硬件适配的终极方案下一篇浏览器端AI推理实战ONNX Runtime Web WebAssembly 本地跑 ONNX 模型完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
