【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本讲围绕 AI 编码 agent 多会话开发的痛点——上一个会话留下的脏状态拖垮下一个会话展开系统讲解**清洁状态Clean State**的五个维度、熵增的成因与数据证据以及六条可落地的工程做法。读完本篇你将掌握如何用会话退出检查清单 双模式清理 质量文档 Harness 简化 幂等清理的完整方案让每个会话结束时都留下可立即续接的干净仓库并了解本仓库中 Project 06 的真实落地实现。这一讲要解决的问题在使用 AI 编码 agent 进行持续开发时一个常见问题是每个 agent 会话结束时如果没有刻意清理代码库的状态会越来越混乱。典型场景是——一个 agent 会话修改了 20 个文件、提交代码后退出下一个会话启动时却发现构建失败、测试变红、临时调试文件散落各处、功能清单和进度记录没有更新。新会话不得不花大量时间诊断上一个会话到底做了什么才能开始工作。OpenAI 和 Anthropic 都明确指出长期可靠性取决于操作纪律单次运行成功并不够。每个会话结束时的状态质量直接决定下一个会话的效率。可以类比 Git 的最佳实践——每个提交都应该是原子且可编译的变更而不是一堆未完成代码的堆积。会话结束时的状态就是下一个会话的起点。核心概念本讲引入六个贯穿全文的概念它们共同构成了清洁交接的方法论骨架清洁状态Clean State会话退出时系统必须满足五个条件——构建通过、测试通过、进度已记录、无过时工件、启动路径可用。缺任何一个都不算做完了。会话完整性Session Integrity类比数据库事务——一个会话的工作要么全部完成并留下清洁状态要么回滚到最后一个一致状态不存在做了一半但还行的中间地带。质量文档Quality Document对代码库中每个模块持续记录质量评分的活动工件。它不是一次性评估而是追踪代码库在变强还是变弱的连续记录。清理循环Cleanup Loop定期执行的维护会话目标是系统性降低代码库的熵。它属于常规保养而非紧急修复——就像汽车定期换机油而不是等发动机报警。Harness 简化Harness Simplification随着模型能力提升定期移除不再必要的 Harness 组件。今天必须有的约束三个月后可能就成了多余开销。幂等清理Idempotent Cleanup清理操作无论执行多少次结果都一样。这保证了清理失败时重跑一遍也是安全的。熵增是默认状态Lehman 的软件演化定律告诉我们一个持续变更的系统如果没有主动管理复杂性必然增加。这对 AI 编码 agent 尤其成立——每个会话都引入变更如果不在退出时清理技术债务会指数级累积。OpenAI 在 5 个月的 Codex 实验中观察到agent 会复制仓库中已有的模式哪怕那些模式是不一致或次优的。随着时间推移这种复制必然导致整体质量漂移。打个比方第一个人在公共区域放了一个杯子第二个人路过时心想反正已经乱了自己也放了一个。一周后桌上就堆满了。代码库的退化是同样的过程——越乱越不管越不管越乱形成熵增的正反馈循环。OpenAI 团队最初每周五花 20% 的工作时间手动清理 agent 留下的烂摊子但显然不可持续。他们最终找到了系统性的解决方案把好习惯写进仓库规则如优先使用共享工具包不要手写 ad-hoc 辅助函数不要瞎猜数据结构查类型定义或用类型安全 SDK。这些规则是具体的、机械的、可以自动检查的。建立周期性清理流程一组后台任务定期扫描偏离规则的代码更新质量评分自动开重构 PR大多数 PR 可以在 1 分钟内审查并自动合并。人类经验捕获一次持续执行每次代码审查意见、重构 PR、用户报的 bug都转化为文档更新或直接编码进检查工具文档不够时就把规则提升为自动检查的代码。一句话总结技术债是高息贷款持续小额还款远比攒到一次性爆雷好得多。12 周实测数据有没有清理策略的差距下面是一个使用 agent 持续开发 12 周的项目的实际对比数据来自本讲原文档的观测记录。没有清洁策略时间构建通过率测试通过率新会话启动时间第 1 周100%100%5 分钟第 4 周95%92%15 分钟第 8 周82%78%35 分钟第 12 周68%61%60 分钟有清洁策略时间构建通过率测试通过率新会话启动时间第 1 周100%100%5 分钟第 12 周97%95%9 分钟12 周下来两组之间的构建通过率相差 29 个百分点测试通过率相差 34 个百分点新会话启动时间相差 85%。这是观测到的差异而非理论推演。清洁状态的五个维度清洁状态远不止代码能编译。它是对以下五个维度的综合评估下面的流程图展示了会话退出时的完整判定路径而两个相反方向的退出方式会走向截然不同的循环构建的维度代码能否无错误地构建这是最基础的底线——下一个会话不应该一上来就先修别人的构建错误。测试的维度所有测试是否通过包括会话开始前就存在的旧测试——本次改动不能破坏已有功能。而且验证必须在 CI 环境里跑而不是在我机器上能过就行。进度的维度当前进度是否记录在机器可读的工件中具体包括三类信息已完成的子任务及其通过标准、正在进行但未完成的子任务及其当前卡点、尚未开始的子任务。好的进度记录可以减少 60%80% 的会话启动诊断时间。工件的维度是否残留了过时的、来源不明的临时工件调试日志、临时文件、被注释掉的代码、TODO 标记都会增加下一个会话的认知负担。新会话看到一堆console.log(debug)和临时方案回头改时根本分不清哪些是有意的、哪些是垃圾。启动的维度标准启动路径是否可用下一个会话能否不靠人工干预直接开始工作环境初始化、代码库加载、上下文获取、任务选择——这些路径中任何一个被破坏新会话就无法自行启动。以后再清理等于永远不清理最常见的心理陷阱是这次来不及清理了下次再弄。但下次的 agent 根本不知道你上次留下了什么——它看到的只是一堆混乱的代码和不确定的状态必须花大量时间推断这段代码里哪些是有意的哪些是临时的。更糟的是每个会话都有自己的任务目标新会话来是为了做新功能不是为上一个会话收拾残局。它通常会忽略混乱、在混乱之上开始新工作然后引入更多混乱——这正是熵增的正反馈循环。正确的做法六条工程实践1. 把清洁状态变成完成的必要条件在 Harness 中明确定义会话完成 任务通过验证 AND 清洁状态检查通过缺任何一个都不算完成。在项目的 CLAUDE.md 或 AGENTS.md 中写入退出检查清单## Session Exit Checklist - [ ] Build passes (npm run build) - [ ] All tests pass (npm test) - [ ] Feature list updated - [ ] No debug code remaining (console.log, debugger, TODO) - [ ] Standard startup path available (npm run dev)这里需要解释功能清单feature list它是一份机器可读的文件记录项目中所有功能项的完成状态每项包含三个信息——这个功能具体做什么、用什么命令验证它、当前状态是什么未开始/进行中/已阻塞/已通过。调度器靠它选择下一个要做的任务验证器靠它判断是否做完交接器靠它生成进度报告。没有功能清单agent 就会用自己的标准判断完成而这个标准几乎一定低于你的标准。本仓库的 projects/project-06/solution/feature_list.json 就是这种机制在真实项目中的样例——15 项功能全部以pass状态收尾每一项都附有验证证据。2. 双模式清理策略把清理拆成两种模式配合使用即时清理每个会话结束时清理本次会话创建的临时工件、更新 feature list 状态、确保构建和测试全部通过。原则是谁产生的垃圾谁清掉类似引用计数。定期清理每周一次做一次全面系统扫描处理累积的结构性问题、更新质量文档、运行基准测试检测整体质量是否漂移。原则是定期全身体检不让小问题拖成大病。3. 维护质量文档质量文档是一份持续更新的文件对代码库中每个模块打分和评价。新会话打开它就能立刻掌握上次会话后每个模块的健康状况。示例# Quality Document ## User Authentication Module (Quality: A) - Verification passing: Yes - Agent understandable: Yes - Test stability: Stable - Architecture boundaries: Compliant - Code conventions: Followed ## Payment Module (Quality: C) - Verification passing: Partial (payment callback untested) - Agent understandable: Difficult (logic spread across 3 files) - Test stability: Unstable (2 flaky tests) - Architecture boundaries: Violations present - Code conventions: Partially followed有了这份文档新会话一上来就知道应该优先处理评分最低的模块。从这个角度说质量文档是 Harness 可观测性的一部分——它让 agent 的运行结果在代码库层面可见。本仓库的 projects/project-06/solution/quality-document.md 给出了一个完整样例对构建、功能完整性、日志、QA、索引、持久化等 15 个维度逐一打分并给出证据最终整体评级 A。4. 定期简化 HarnessHarness 中每个组件的存在都源于模型在某个方面尚无法独立完成。随着模型能力演进这些前提会逐渐过时——今天必须有的约束三个月后可能就成了多余开销。Anthropic 的实验直观展示了这一点他们最初的 Harness 包含任务拆分机制因为当时的模型无法一次性处理太大任务当更强的模型发布、模型自己就能规划步骤后该机制反而成了多余步骤移除后 Builder Agent 能够连续工作两小时以上而不偏离方向。Evaluator 的情况则不同——当任务难度逼近模型能力上限时它依然有用任务简单时它可能就是多余的。因此保留还是移除某个组件取决于任务难度与模型能力的相对关系。推荐做法每月挑选一个 Harness 组件暂时禁用跑一遍基准任务。如果结果没有退化就永久移除如果退化则恢复或替换为更轻量的替代方案。5. 清理操作必须幂等幂等的含义是一个操作无论执行一次还是一百次结果都一样。清理脚本必须具备这个特性因为清理失败时你会重跑——如果重跑产生不同结果说明脚本本身有 bug。示例# Idempotent cleanup operations rm -f /tmp/debug-*.log # -f ensures no error when files dont exist git checkout -- .env.local # Restore to known state, safe to run repeatedly npm run test # Verify cleanup didnt break anything6. 高吞吐量改变了合并策略当 agent 的产出远超人类审查能力时传统合并策略需要调整。OpenAI 团队的经验是在 agent 每天开出约 3.5 个 PR 的环境里减少阻塞型合并检查是正确的——PR 应尽快合并测试偶尔的假失败flake用后续运行修正不必无限期卡住进度。关键的判断标准是修正一个 bug 的平均成本 vs 等待人类审查一个 PR 的平均成本哪个更低当前者更低时快速合并 快速修正优于慢慢审查。注意这条规则的前提是 agent 的高产出远超人类审查带宽在低产出环境里快速合并没有意义。仓库中的真实落地Project 06 的清洁状态工程本仓库的 Project 06Capstone 将本讲原则完整落到了真实项目里可以作为直接参考的样板工程clean-state-checklist.md一份覆盖构建、架构边界、运行时、日志、数据完整性、性能、仓库、脚本共 8 大类、约 30 项的退出检查清单。它把构建通过、测试通过、进度已记录、工件干净、启动可用五个维度细化成了可勾选、可执行的机器指令例如渲染进程代码不得导入fs/path所有 IPC 通道必须定义在 src/shared/types.tsbash scripts/cleanup-scanner.sh报告无陈旧工件。AGENTS.md明确定义了 Definition of Done——TypeScript 无错误编译、应用可启动、功能进入feature_list.json且状态为pass、遵守 Electron 分层边界、结构化日志覆盖所有服务操作、文档已更新、clean-state-checklist.md全部通过。这正是任务通过验证 AND 清洁状态检查通过的工程化表达。quality-document.md15 个维度的持续评分记录包含构建、功能完整性、可观测性、性能等证据对应本讲的质量文档概念。session-handoff.md会话交接文档的实例——记录已完成事项、剩余事项、关键决策、修改过的文件清单与阻塞项让新会话无需猜测即可续接。配套工具基准运行器与清理扫描器本讲附带 code/ 目录包含可直接运行的工具源码benchmark-runner.ts读取一批带通过标准pass criteria的基准任务定义模拟执行并输出对比报告——逐任务展示 ID、类别、通过与否、标准达成数、期望/实际耗时与偏差并对失败任务输出失败原因最后按类别汇总通过率。运行方式npx tsx docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts。它直接服务于本讲的第 2 个练习基准对比实验与第 4 节Harness 简化实验——通过有/无某组件两轮基准运行的结果对比判断该组件应该保留、移除还是替换。cleanup-scanner.ts扫描项目目录中的陈旧工件、死代码与结构违规输出带严重级别critical/warning/info的清理报告。检查项包括临时文件*.tmp、*.bak、*.swp、源码树中的日志文件、TODO:/FIXME:/HACK:标记、缺失.gitignore、源码目录内的构建产物与node_modules、会话遗留标记文件如WIP.md、scratch.ts、debug.ts、空目录、.env等敏感文件。运行方式npx tsx docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts [path]默认扫描当前目录。这正是即时清理 定期清理中可自动化的落地形态。cleanup-loop.md定期清理循环的任务清单——扫描旧文档、扫描结构违规、更新质量评级、创建定向清理 PR、清理后重跑固定基准切片。benchmark-comparison-template.mdHarness A/B 对比的模板记录完成率、平均重试次数、人工审查前发现的 bug 数并引导分析哪个 Harness 改变了结果、哪个改变了获取结果的成本。实际案例12 周 Electron 应用的对照实验一个使用 agent 持续开发的 Electron 应用12 周的演化过程数据来自本讲原文档无清洁策略对照组每个会话做完功能就退出不做额外清理。到第 12 周时构建通过率 68%、测试通过率 61%、新会话启动 60 分钟以上、过时工件 103 个。有清洁策略实验组每个会话结束时执行完整清洁检查 每周一次清理循环。到第 12 周时构建通过率 97%、测试通过率 95%、新会话启动 9 分钟、过时工件 11 个。到第 12 周实验组的构建通过率比对照组高 29 个百分点测试通过率高 34 个百分点新会话启动时间减少 85%。每个会话只多花约 5 分钟做清理12 周下来却省下了几十个小时的混乱时间。核心要点清洁状态是会话完成的必要条件——不是可选的收拾而是完成定义的一部分。代码写完了但状态是脏的就不算做完。五个维度缺一不可构建、测试、进度、工件、启动。每一条都要在退出时显式检查不能靠感觉应该没问题。功能清单让 agent 知道做完的标准——没有清单agent 用自己的标准判断完成那个标准几乎一定比你低。质量文档让代码库的健康状况可追踪——知道哪里在退化才能主动修复不知道问题在哪儿就只能等它爆发。定期简化 Harness——随着模型能力提升主动移除不再必要的组件。以后再清理等于永远不清理——熵增是默认方向只有主动的清洁操作才能对抗它。每次多花五分钟是长期回报最高的投资。延伸阅读本系列其他讲义的关联主题仓库内路径第八讲 为什么功能清单是 Harness 的原语——如何用功能清单给 agent 明确的完成标准第九讲 为什么 agent 会过早宣告完成——如何通过验证机制避免 agent 过早说做完了第十讲 为什么端到端测试会改变结果——为什么端到端测试是唯一可靠的完成验证第十一讲 为什么可观测性必须内置于 Harness——如何通过可观测性让 agent 的运行状态不再是黑盒第五讲 为什么长任务会丢失连续性——会话交接的前置知识如何让新会话快速接上另外本讲的原始思想可追溯到外部公开资料此处仅作来源说明不提供链接Robert C. Martin 的《Clean Code》为代码整洁提供了系统原则OpenAI 的《Harness Engineering》阐述了以可重复性为核心的 Harness 设计要求Anthropic 的《Effective Harnesses for Long-Running Agents》强调了干净会话退出对长期可靠性的关键作用Lehman 的软件演化定律论文则证明了无主动维护时系统复杂性必然增长。练习设计你的清洁状态检查表为你的代码库设计一个会话退出检查表覆盖全部五个维度构建、测试、进度、工件、启动。在接下来的 5 个连续会话中坚持执行记录每个维度的违反次数。基准对比实验选定一个固定任务集分别在两种 Harness 配置下运行——一种要求清洁状态检查通过才算完成另一种不要求。使用 benchmark-comparison-template.md 比较两组的完成率、重试次数和漏网 bug 数量。Harness 简化实践从你的 Harness 里选一个组件暂时禁用它跑一遍基准任务。比较有它和没有它的结果然后决定是保留、移除还是换成更轻量的替代方案。质量文档入门为你的项目创建第一份质量文档。挑选 35 个核心模块给每个模块打分A/B/C/D标注具体的扣分原因。在接下来的 4 周里每周更新一次评分观察质量是在变好还是变差。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 第 12 讲每次会话结束时都必须留下干净交接Clean Handofflearn harness engineering 第 12 讲每次会话结束时都必须留下干净交接Clean Handoff 导读 本讲围绕 learn会话交接的艺术为 learn-harness-engineering 构建每次会话结束都留下干净状态的 Harness 纪律会话交接的艺术为 learn harness engineering 构建每次会话结束都留下干净状态的 Harness 纪律 导读本篇文章聚焦 lear会话收尾工程在 learn-harness-engineering 中让每个 AI Agent 会话都留下干净状态会话收尾工程在 learn harness engineering 中让每个 AI Agent 会话都留下干净状态 本篇技术指南以 learn harne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考