【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载在 AI 编码 agent 的多会话协作中最常见的效率杀手不是 agent 能力不足而是仓促开工新会话一上来就写功能代码随后才发现测试框架未配置、环境不完整、项目结构不明大量时间耗在搞清楚这个项目怎么运作上。本讲围绕 learn-harness-engineering 课程第六讲《Make the Agent Initialize Before Every Work Session》展开系统讲解为什么初始化必须作为 agent 生命周期中的独立阶段、初始化阶段应产出哪些基础设施以及如何借助仓库中配套的脚本与清单把初始化验收变成可执行、可量化的流程。读完本文你将掌握启动就绪清单Bootstrap Contract的设计方法、初始化验收清单的落地方式以及让每一次后续会话都能看完仓库就能接着干的实战方案。本文内容以 俄语版第六讲与 英文版、中文版 内容一致为核心骨架配套代码示例位于 docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/对应实战项目为 Project 03. Multi-Session Continuity。一、初始化和实现是两种性质完全不同的工作初始化和实现拥有完全不同的优化目标实现阶段优化的是已验证功能的数量与质量maximize the quantity and quality of verified features。初始化阶段优化的是所有后续实现阶段的可靠性与效率maximize the reliability and efficiency of all subsequent implementation。当二者混在一起时agent 面临的是一个多目标优化问题它必须同时搭建基础设施和编写功能代码。在没有显式优先级设定的情况下agent 会自然倾向于写代码——因为代码是直接可见的产出而牺牲基础设施——因为它的价值要到后续会话才会显现。结果就是基础设施没搭牢功能代码的可靠性也随之打折扣。课程用了一个非常形象的比喻这就像让建筑队同时浇筑地基和砌墙。工人大概率会先砌墙因为墙看得见、可以展示但地基不好的房子后面会暴露系统性故障。先浇地基、等它凝固再砌墙才是干净高效的做法。二、初始化生命周期两种会话路径对比课程用 mermaid 流程图对比了两种会话路径见原文档 初始化生命周期 一节以下为该流程的文字化表达混合式会话错误路径一上来就开始做功能做到一半才发现环境和测试缺口累积未经验证的代码下一个会话还得重新摸清项目状态独立初始化阶段正确路径会话 1环境可运行示例测试通过写出启动就绪清单 任务清单提交干净检查点clean checkpoint后续会话直接开始做已准备好的任务核心差别在于正确路径在第一天就把项目如何运作固化成了仓库内容而不是留在某个 agent 会话的临时记忆里。三、把初始化和实现混在一起会发生什么3.1 最直接的问题基础设施搭不牢Agent 花 80% 的精力写功能代码剩下 20% 随便搭了点基础设施测试框架配了但没验证过、lint 规则设了但太宽松、进度文件没创建。这些缺陷在第一个会话里不明显——因为当前 agent 还记得自己做过什么但到第二个会话就立刻暴露新 agent 不知道项目怎么跑、怎么测、做到哪了。脆弱的根基必然导致摇晃的大楼。3.2 更隐蔽的代价未经验证的累积在测试框架配好之前写的功能代码属于无验证代码。等你回头补测试时可能发现设计本身就错了——早知道的话当初就会用不同的方式实现。这就像在未干透的水泥上贴瓷砖等发现地面不平整时所有瓷砖都得撬掉重来。前面写的代码越多后面需要推翻重来的就越多。3.3 上下文预算被浪费初始化工作配环境、配测试、理解项目结构会消耗大量上下文预算留给真正功能实现的反而变少。结果往往是第一个会话只完成一半功能第二个会话还要从头理解项目。预算花在了初始化上但初始化也没做好——两头都没占着。3.4 最容易被忽略的问题隐式假设埋下的雷Agent 在初始化过程中做出的决策——用哪个测试框架、目录怎么组织、依赖怎么管理——如果没有被显式记录后续会话就可能做出矛盾的选择。课程给出的例子非常典型第一个会话选了 Vitest第二个会话的 agent 不知道又引入了 Jest两套测试框架共存维护成本翻倍。这就像第一支施工队打了水泥地基第二支施工队不知情又在里面钉了木桩地基开裂。3.5 行业研究的佐证课程引用了两份公开研究作为旁证Anthropic 的长运行应用开发研究明确建议把初始化和实现分离其实验数据显示使用独立初始化阶段的项目在多会话场景中的功能完成率比混合方式高 31%初始化阶段投入的时间在后续3-4 个会话中即可完全收回。OpenAI Codex 的 harness engineering 指南强调仓库作为操作记录repository as operational record原则从第一次运行就要建立清晰的操作结构否则每次新会话都得重新推断项目约定。四、核心概念速览初始化阶段Initialization Phaseagent 生命周期中的第一个阶段只建立后续实现所需的执行前提不做任何功能开发。它的产出是基础设施而不是业务代码。启动就绪清单Bootstrap Contract / Startup Readiness Checklist一个项目能被全新 agent 会话无歧义操作的条件——能启动、能测试、能看进度、能接手下一步。四个条件缺一不可。冷启动 vs 热启动From Scratch vs From Template冷启动意味着 agent 要从空目录自行推断项目结构效果差热启动意味着基础设施已经就位效果远好。能用模板就用模板——这相当于开工时已有水电而非面对一片荒原。随时可接手Always Ready to Hand Off项目在任何时刻都处于可以被全新 agent 接手的状态不需要任何口头解释只看仓库内容就能继续干活。从开始到第一次测试通过Time from Start to First Passing Test衡量初始化效率的核心指标时间越短初始化越高效。后续会话的成功率Success Rate of Subsequent Sessions后续会话在不依赖隐式知识的前提下成功执行任务的比例这是衡量初始化质量的最佳标准。五、初始化的正确做法五个产出物把初始化当作独立阶段来执行——第一个会话只做初始化不写任何业务功能代码。初始化的产出物有五个5.1 可运行的环境项目能启动、依赖都装好、没有环境问题。这是浇好的、没有裂缝的地基。5.2 可验证的测试框架至少有一个示例测试通过证明测试框架本身是配置正确的。这相当于在地基上立起一根柱子来验证它能承重。5.3 启动就绪清单文档一份明确的文档向后续会话传达怎么跑、怎么测、项目当前状态、目录怎么组织。课程给出的模板如下该模板同时出现在原文档的初始化的正确做法一节# 初始化契约 ## 启动命令 - 安装依赖make setup - 启动开发服务器make dev - 运行测试make test - 完整验证make check ## 当前状态 - 所有依赖已安装并锁定 - 测试框架已配置Vitest React Testing Library - 示例测试通过1/1 - Lint 规则已配置ESLint Prettier ## 项目结构 - src/ — 源代码 - src/components/ — React 组件 - src/api/ — API 客户端 - tests/ — 测试文件5.4 任务分解把整个项目拆成有序的任务列表每个任务附带明确的验收标准# 任务分解 ## Task 1: 用户认证基础 - 实现 JWT 认证中间件 - 添加登录/注册端点 - 验收标准pytest tests/test_auth.py 全部通过 ## Task 2: 用户资料页面 - 实现用户资料 CRUD - 添加资料编辑表单 - 验收标准pytest tests/test_profile.py 全部通过 ## Task 3: 搜索功能 - ...5.5 Git 提交作为检查点初始化完成后提交一个干净的 checkpoint后续所有工作都从该 checkpoint 开始保证回滚与交接都有明确基线。5.6 热启动策略不要从空目录开始。使用项目模板create-react-app、fastapi-template 等预置标准目录结构、依赖配置和测试框架把通用初始化步骤烘焙进模板只留下项目特有的初始化工作。5.7 初始化完成条件与验收清单判断初始化是否完成的依据不是写了多少代码而是启动就绪清单的四个条件是否全部满足。课程给出的验收清单## 初始化验收清单 - [ ] make setup 从零开始能成功 - [ ] make test 至少有一个测试通过 - [ ] 新的 agent 会话能只看仓库回答怎么跑和怎么测 - [ ] 任务分解文件存在且有至少 3 个任务 - [ ] 所有内容已提交到 git六、仓库源码级佐证把初始化验收变成可执行代码learn-harness-engineering 在本讲的 code/ 目录 下提供了三份配套资产把上面纸上谈兵的验收标准落成了可运行的脚本与清单。6.1 init-check.ts前置条件程序化检查init-check.ts 用 TypeScript 实现了对初始化前置条件的程序化检查覆盖 8 项检查每项都标注了缺失时的影响检查项类别缺失时的影响Node.js 版本 18RuntimeTypeScript 特性与内置 API 不可用package.json 存在Config无法安装依赖或运行脚本依赖已安装node_modulesDependencies所有 import 在运行时失败TypeScript 可用npx tsc --versionToolchain无法编译 TypeScript 文件tsconfig.json 存在Config编译器使用默认配置可能与项目需求不匹配源码目录存在src/lib/appStructureagent 找不到可修改的源文件测试目录存在test/tests/tests/specStructureagent 找不到或无法运行现有测试Git 仓库已初始化Version Control无法回滚、无变更历史该脚本的核心价值在于对比模拟simulateWithoutInit()模拟agent 跳过初始化直接干活——它不提前检查前置条件遇到缺失项时逐个踩坑每个缺失项按 200ms 估算探索时间simulateWithInit()模拟先跑初始化——提前发现全部问题。两者对比输出 INIT PHASE COMPARISON 表格直观展示有初始化阶段时提前检查前置条件 Yes、工作时长浪费 0ms、工作成功 取决于检查是否全过无初始化阶段时带着问题强行干活、浪费大量时间在后期逐个发现缺项。运行方式注释中给出npx tsx docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts注tsx是 TypeScript 直接执行器需先通过npm install安装依赖。这个脚本把本文第三节描述的隐性假设地雷未验证累积等抽象风险转化成了可观测、可复现的对照实验——这正是初始化必须提前、集中完成这一原则的代码级证据。6.2 init.sh最小初始化脚本骨架init.sh 提供了一个最小可用的初始化脚本骨架采用set -euo pipefail严格模式包含三个步骤安装依赖npm install、可选启动文档站npm run docs:dev、以及项目特有启动逻辑放这里的占位注释。它示范了初始化阶段的第一步应当如何编排——把环境搭建固化为幂等、可重复执行的脚本而不是依赖 agent 临场发挥。6.3 initializer-output-checklist.md初始化器产出清单initializer-output-checklist.md 从验收视角给出 5 个追问与第五节内容一一对应是否有规范的启动命令canonical startup command是否有规范的验证命令canonical verification command是否有第一个进度产物first progress artifact是否有稳定的第一个提交stable first commit是否有对后续运行可见的功能面visible feature surface for later runs这 5 个问题本质上是把启动就绪清单四条件翻译成了初始化器initializer的交付验收标准能启动启动命令、能测试验证命令、能看进度进度产物、能接手下一步首个提交 可见功能面。七、仓库中的实际落地Project 03 多会话连续性本讲对应的实战项目是 Project 03. Multi-Session Continuity它直接检验每次会话前先初始化的成效。从项目说明看starter/基于 Project 02 的解方案文档分块、元数据提取、索引状态、带引用问答均待实现缺少完整的重启/交接 harnessinit.sh、session-handoff.md、claude-progress.md、clean-state checklist而solution/是参考实现补齐了全部重启/连续性产物并在AGENTS.md中内置一次一个功能策略。项目的任务对应关系表清楚地标出了连续性 harness这一列starter 缺失的产物正是 projects/project-03/solution/ 下实际存在的文件init.sh——初始化脚本把可运行环境固化session-handoff.md——会话交接文档把当前状态固化claude-progress.md——进度跟踪文件把看进度固化clean-state-checklist.md——干净状态清单把可接手固化feature_list.json——功能清单把下一步做什么固化从源码结构可以看出这正是本讲思想的工程化落地初始化阶段的所有产出都必须以文件形式存在于仓库中让后续任何全新会话只读仓库就能回答怎么跑、怎么测、做到哪、下一步做什么四个问题。这与 init-check.ts 中前置条件检查 显式初始化阶段的设计互为印证——文档给原则代码给机制项目给验收。八、实际案例React 前端项目的两种初始化路径课程用一个 React 前端项目对比了两种做法混合方式同时浇地基和砌墙agent 在第一个会话中同时创建项目脚手架并实现首个功能。会话结束时仓库有可运行代码但没有显式的启动/测试命令文档、没有进度跟踪文件、没有任务分解。第二个会话花了约20 分钟推断项目结构、测试框架和构建流程——如同一支新施工队到达工地不知道地基浇到哪、管线走到哪只能一个坑一个坑地挖着试探。独立初始化先浇地基第一个会话只做初始化——用项目模板创建目录结构、配置测试框架Vitest React Testing Library、写一个示例测试并验证通过、创建启动就绪清单文档和任务分解文件、提交初始检查点。第二个会话的重建时间不到3 分钟直接按任务列表开始工作——施工队到场后看一眼图纸就知道该从哪里接着干。全项目周期对比混合方式的总重建时间跨所有会话比独立初始化多约60%。独立初始化多花的 20 分钟在后续会话中被成倍收回。课程给出了一个反直觉的结论前期慢一点整体反而更快slower is faster。九、核心要点初始化和实现的优化目标不同混在一起只会互相拖后腿——先浇地基再砌墙。初始化的产出不是业务代码而是基础设施可运行环境、可验证测试、启动就绪清单、任务分解、干净检查点。用启动就绪清单的四个条件验收初始化能启动、能测试、能看进度、能接手下一步。热启动优于冷启动用项目模板预置标准化基础设施只留项目特有初始化工作。初始化投入的时间会在后续 3-4 个会话中完全收回——这是前期投资不是额外成本。所有初始化决策必须显式落盘文档、脚本、清单否则就是给后续会话埋下的隐式假设地雷。十、动手练习启动就绪清单设计为你正在开发的项目写一份完整的启动就绪清单然后打开一个全新 agent 会话只给它看仓库内容不给任何口头上下文让它尝试启动项目、跑测试、了解当前进度。记录它遇到的每个问题——每个问题都对应你清单中缺失的一个条款。对比实验选一个中等复杂度的新项目。方式 A 让 agent 初始化和首次实现同时进行方式 B 先花一个会话做独立初始化第二个会话再开始实现。4 个会话后对比首次验证时间、重建成本、功能完成率。初始化验收清单参照第六节的 initializer-output-checklist.md 与第五节验收模板为你的项目设计一份初始化验收清单让全新 agent 会话逐项执行记录哪些通过、哪些失败。失败的项就是你的 harness 需要补强的地方——可进一步参考 Project 03 解方案的连续性产物 作为对照基准。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐独立初始化阶段为 Agent 每次工作会话打牢地基learn-harness-engineering 实战指南独立初始化阶段为 Agent 每次工作会话打牢地基learn harness engineering 实战指南 本文基于 learn harness enHarness 工程实战为什么 Agent 的初始化必须是一个独立阶段——learn-harness-engineering 讲座 06 深度解读Harness 工程实战为什么 Agent 的初始化必须是一个独立阶段——learn harness engineering 讲座 06 深度解读 本文基于让 Agent 在每次工作会话前先完成初始化独立初始化阶段的设计与落地learn-harness-engineering 课程 06 深度解析让 Agent 在每次工作会话前先完成初始化独立初始化阶段的设计与落地learn harness engineering 课程 06 深度解析 导读 本上一篇如何快速入门VLA-Diffusion-Policy-Robotics扩散模型在机器人操作中的5大应用场景下一篇实战指南3个关键步骤彻底解决Gogs第三方服务集成难题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考