独立初始化阶段为 Agent 每次工作会话打牢地基learn-harness-engineering 实战指南【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering本文基于 learn-harness-engineering 仓库《Lecture 06. Make the Agent Initialize Before Every Work Session》课程文档展开它回答了一个困扰所有多会话 Agent 工程实践的问题——为什么装基础、砌墙不能同时进行而必须把环境初始化、测试框架验证、任务拆解与进度记录从功能实现中剥离出来作为独立的第一个阶段。读完本文你将掌握初始化阶段—启动就绪清单—验收清单这一套可落地的方法论并能结合仓库中提供的 init-check.ts 前置条件检查器、init.sh 初始化脚本以及 Project 03 的真实多会话项目为自己的 harness 建立可复现、可验证的初始化流程。一、为什么初始化必须是一个独立阶段课程文档开门见山地描述了一个非常典型的情景你开启一个新的 Agent 会话说加一个搜索功能Agent 立刻兴奋地跳进编码。20 分钟后它发现测试框架没配置好又花 10 分钟修这个接着发现数据库迁移脚本格式不对再折腾一阵。搜索功能最后是加上了但整个会话的大部分时间都耗在搞清楚这个项目怎么运行上而不是写功能本身。更好的做法是在允许 Agent 开始干活之前先用一个独立的阶段把基础环境准备好、把验证命令跑通、把项目结构搞清楚。初始化工作不应与功能实现挤在一起——它们是两类本质不同的任务。课程用了一个非常贴切的比喻盖房子时不要一边浇地基一边砌墙。如果同时做墙会在地基凝固之前就立起来最终整栋楼都要推倒重建。先浇地基等它凝固再砌墙——干净、高效。从优化目标上看二者的差异是根本性的实现阶段implementation优化的目标最大化已通过验证的功能的数量与质量初始化阶段initialization优化的目标最大化后续所有实现工作的可靠性与效率。当初始化与实现混在一起时Agent 面对的是一个多目标优化问题它必须同时搭基础设施和写功能代码。在缺乏显式优先级的情况下Agent 天然倾向于写代码因为那是直接可见的输出而牺牲基础设施因为它的价值要到后续会话才显现。结果就是基础设施没建扎实功能代码的可靠性也随之受损。二、初始化生命周期两种会话模式的对比课程文档用 mermaid 流程图对比了混合会话错误与专属初始化阶段正确两条路径右侧这条正确路径实际上定义了整个仓库方法论的核心节奏会话 1 只做初始化——环境可运行 → 示例测试通过 → 写入启动就绪清单与任务列表 → 提交干净检查点 → 后续会话直接基于已验证的任务开工。三、混合初始化的四类代价课程文档逐一拆解了把初始化与实现混在一起会付出的四类代价每一类都对应一个真实的失败模式1. 基础设施没有建扎实最直接的问题Agent 把 80% 的精力花在功能代码上剩下 20% 顺带搭一点基础设施。测试框架配置了但从未验证过、lint 规则设置了但过于宽松、进度文件根本没建。这些缺陷在第一会话不显眼因为 Agent 还记得自己做了什么但会在第二会话集中爆发新 Agent 不知道如何运行项目、如何测试、当前进展到哪一步。地基烂了楼自然晃。2. 未经验证的代码累积unverified accumulation在测试框架配置好之前写出来的功能代码是没有验证背书的代码。等最后补测试时可能发现设计从一开始就是错的——如果早知道当初就会用不同的方式实现。这就像在未干的混凝土上贴瓷砖等发现地面不平所有瓷砖都要揭掉重来。前期写得越多后期要拆的越多。3. 上下文预算被浪费初始化工作配置环境、搭测试、理解项目结构会消耗掉很大一块上下文预算留给真正功能实现的空间就少了。结果第一会话只完成一半功能第二会话还要从头理解项目——预算花在了初始化上而初始化也没做好两头落空。4. 隐式假设的地雷最容易被忽略的问题Agent 在初始化过程中做出的决策选哪个测试框架、目录怎么组织、依赖怎么管理如果没有被显式记录下来后续会话可能做出互相矛盾的决策。课程文档给了个具体例子第一会话选了 Vitest第二会话的 Agent 不知道又引入了 Jest两个测试框架共存维护成本翻倍。第一批施工队用了混凝土地基第二批不知道往里钉了木桩——地基开裂。外部研究的佐证课程文档引用了 Anthropic 关于长期运行 Agent 的研究结论使用专属初始化阶段的项目在多会话场景下的功能完成率比混合方法高 31%且投入在初始化阶段的时间会在接下来的 3~4 个会话内被完全回收。文档同时引用了 OpenAI Codex 的 harness 工程指南所强调的仓库即操作记录原则从第一次运行就确立清晰的操作结构否则每个新会话都要重新推断项目约定。这两条结论作为课程引用的外部研究背景被记录在文档中也是我们设计初始化流程时的重要参照。四、核心概念初始化方法论的六块基石课程文档定义了六个必须精确理解的核心概念它们是后续所有实操的词汇表初始化阶段Initialization PhaseAgent 生命周期中的第一个阶段——只建立后续实现所需的前提条件不做任何功能开发。它的产出是基础设施而不是业务代码。启动就绪清单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不依赖隐式知识就能成功执行任务的后续会话占比。这是衡量初始化质量的最佳指标。五、如何正确地完成初始化五个产出物与两条策略把初始化当作一个专属阶段课程文档的硬性要求是第一会话只做初始化一个业务功能代码都不写。初始化阶段需要产出以下五项成果1. 可运行的Runnable环境——项目能启动、依赖已安装、没有环境问题。2. 可验证的Verifiable测试框架——至少有一个示例测试通过证明测试框架本身配置正确。这就像在地基上立一根柱子证明它能承重。3. 启动就绪清单文档——一份清晰的文档告诉后续会话一切运行细节# Startup Readiness Checklist ## Start Commands - Install dependencies: make setup - Start dev server: make dev - Run tests: make test - Full verification: make check ## Current State - All dependencies installed and locked - Test framework configured (Vitest React Testing Library) - Example test passing (1/1) - Lint rules configured (ESLint Prettier) ## Project Structure - src/ — Source code - src/components/ — React components - src/api/ — API client - tests/ — Test files4. 任务拆解Task Breakdown——把整个项目拆成有序的任务列表每个任务都带明确的验收标准# Task Breakdown ## Task 1: User Authentication Basics - Implement JWT auth middleware - Add login/register endpoints - Acceptance: pytest tests/test_auth.py all passing ## Task 2: User Profile Page - Implement user profile CRUD - Add profile edit form - Acceptance: pytest tests/test_profile.py all passing ## Task 3: Search Feature - ...5. 作为检查点的 Git commit——初始化完成后提交一个干净的检查点之后所有工作都从这个检查点出发。策略一优先采用热启动不要从空目录开始。使用项目模板create-react-app、fastapi-template 等预设标准目录结构、依赖配置和测试框架。把通用初始化步骤烘焙进模板只留下项目特有的初始化工作。策略二用验收清单判断初始化是否完成初始化的完成标准不是写了多少代码而是启动就绪清单的四个条件是否全部满足。课程文档给出了可直接套用的验收清单## Initialization Acceptance Checklist - [ ] make setup succeeds from scratch - [ ] make test has at least one passing test - [ ] A new agent session can answer how to run and how to test from repo contents alone - [ ] Task breakdown file exists with at least 3 tasks - [ ] Everything committed to git六、源码级验证把前置条件检查变成程序化步骤课程文档不仅在理论上阐述还在仓库中提供了可运行的示例代码位于 docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md用于演示初始化阶段应该产出什么。init-check.ts程序化的前置条件检查器init-check.ts 用 TypeScript 实现了一个可运行的初始化前置条件检查器。它把Agent 开工前必须先确认什么抽象成一组可检查的条目每个条目包含名称、类别、检查逻辑和缺失时的影响impactIfMissing。从源码结构看它检查了八类前置条件检查项类别缺失时的影响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 仓库已初始化.gitVersion Control没有回滚能力没有变更历史这个文件最有价值的地方是它的对比模拟逻辑simulateWithoutInit()模拟无初始化阶段——Agent 跳过检查直接开工然后在工作中逐个撞上缺失的前置条件每个缺失项浪费 200ms 的发现时间simulateWithInit()模拟有初始化阶段——开工前一次性发现所有问题零浪费。源码注释明确点出了核心洞察An explicit init phase catches problems before they waste time.显式初始化阶段在问题浪费时间之前就抓住它们。运行方式源码头部注释给出的命令npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts它会输出一份检查明细表、失败项的缺失影响清单以及无初始化阶段 vs 有初始化阶段的指标对比表——这正是课程主题的程序化演示。init.sh 与 initializer-output-checklist.md同目录下的 init.sh 是一个带set -euo pipefail的最小初始化脚本骨架安装依赖、提示可选启动文档站、预留项目特有启动逻辑的位置。它示范了初始化脚本应该有的最小形态——把装依赖 验证固化成一条可重复执行的命令。initializer-output-checklist.md 则给出了判断初始化器输出是否合格的五问清单是否有规范的启动命令Is there a canonical startup command?是否有规范的验证命令Is there a canonical verification command?是否有第一个进度产物Is there a first progress artifact?是否有稳定的首次提交Is there a stable first commit?是否有对后续运行可见的功能表面Is there a visible feature surface for later runs?这五问与课程正文的五项产出物一一对应是初始化验收的可操作版本。七、仓库中的真实落地Project 03 的多会话初始化工程课程文档链接了配套实战项目 Project 03. Multi-session continuity它的解决方案目录projects/project-03/solution/是初始化方法论最完整的落地样本。init.sh把干净构建固化为开工仪式solution/init.sh 的头部注释写得非常直白Verify the project builds cleanly before starting work. Run this after cloning or when resuming work.在开始工作前验证项目能干净构建。克隆后或恢复工作时运行它。脚本用set -euo pipefail保证任何一步失败都立即终止并按三步推进安装依赖 → 运行类型检查npm run check→ 构建项目npm run build最后提示npm run dev启动应用。这就是课程第一会话只做初始化在真实项目中的执行形态。AGENTS.md把初始化写进 Agent 的启动规则更关键的是 solution/AGENTS.md 中的Startup Rules——它用强制顺序定义了每个新会话的初始化仪式完整阅读本文件定义边界与约定阅读docs/ARCHITECTURE.md理解分层结构与数据流阅读docs/PRODUCT.md理解功能需求运行npm install npm run check验证项目干净构建阅读feature_list.json查看所有功能当前状态。这就是课程启动就绪清单的制度化版本先读约定 → 再读架构 → 再读需求 → 再验证构建 → 再读功能状态任何代码动手之前必须走完。同文件还定义了一次只做一个功能One-Feature-at-a-Time策略与功能依赖图确保后续会话不会偏离轨道。进度可见性与会话交接feature_list.json 是能看到进度的载体每个功能带有id、name、description、status、evidence验证证据和testedAt时间戳。课程强调不能在没有验证证据的情况下标记 pass这份文件中的document-chunking、metadata-extraction等条目都附带了具体的实现与验证描述正是该原则的执行记录。session-handoff.md 实现了能接续下一步记录上次会话完成了什么、还剩什么、做了哪些决策、改过哪些文件、有什么阻塞。它与 clean-state-checklist.md 一起构成会话结束时的收尾协议与 Lecture 12 的干净状态主题呼应。模板化把初始化烘焙进 harness 脚手架仓库的 harness 创建技能skills/harness-creator/templates/提供了 init.sh、agents.md、feature-list.json、progress.md、session-handoff.md 等模板。其中模板版 init.sh 是课程热启动策略的直接体现它会自动探测包管理器pnpm/yarn/bun/npm、按check → typecheck → lint → test → build顺序执行 Node 项目验证并兼容 Pythonpytest compileall、Gogo test、Rustcargo test、Maven、Gradle、.NET 等多种技术栈。也就是说通用初始化步骤已经被烘焙进模板每个新项目只需补充项目特有的部分——这正是课程所说的从模板开始远优于从零开始。八、真实世界示例React 前端项目的两种初始化方式课程文档用一个 React 前端项目对比了两种初始化路径混合方式同时浇地基与砌墙Agent 在会话 1 同时创建项目脚手架并实现第一个功能。会话结束时仓库有可运行代码但没有显式的启动/测试命令文档、没有进度跟踪文件、没有任务拆解。会话 2 花了约 20 分钟推断项目结构、测试框架和构建流程——就像新施工队到了现场不知道地基进展到哪、管线走向如何只能一个个挖洞去探测。专属初始化先浇地基会话 1 只做初始化——从模板创建目录结构、配置测试框架Vitest React Testing Library、编写并验证一个示例测试、创建启动就绪清单与任务拆解文件、提交初始检查点。会话 2 的重建时间不到 3 分钟直接从任务列表开始干活——施工队到场看一眼图纸就知道该从哪里继续。整个项目周期的对比结论混合方式的累计重建时间跨所有会话比专属初始化方式多约 60%。初始化阶段多花的 20 分钟在后续会话中被成倍回收。文档的总结非常精辟慢即是快the slow is fast——前期多投入一点时间把初始化做好后续效率反而更高。九、关键结论初始化与实现有不同的优化目标——把它们混在一起只会把两者都拖下水。先浇地基再砌墙。初始化的产出不是业务代码而是基础设施可运行的环境、可验证的测试、启动就绪清单、任务拆解。用启动就绪清单的四个条件验证初始化能启动、能测试、能看到进度、能接续下一步。热启动优于冷启动用项目模板预设标准化基础设施。投入初始化的时间会在接下来的3~4 个会话内完全回收。这不是额外成本而是前期投资——地基越硬楼建得越快。十、配套练习课程文档设计了三个可操作的练习用于把方法论内化为自己的 harness 能力设计启动就绪清单为你正在开发的项目写一份完整的启动就绪清单然后开一个全新的 Agent 会话只给它仓库内容不给任何口头上下文让它尝试启动项目、运行测试、理解当前进度记录它遇到的每一个问题——每个问题都对应你清单里缺失的一条。对比实验选一个中等复杂度的新项目。方案 A让 Agent 同时进行初始化与首次实现方案 B用一个会话做专属初始化会话 2 再开始实现。4 个会话后比较从开始到首个测试通过的时间、重建成本、功能完成率。初始化验收清单为你的项目设计一份初始化验收清单让全新 Agent 会话逐项执行记录哪些通过、哪些失败——失败的条目就是你 harness 需要加固的地方。延伸阅读仓库内Lecture 05. 长任务为什么会失去连续性——初始化阶段产出的清单与交接文件正是解决连续性丢失的关键输入。Lecture 12. 每次会话必须留下干净状态——初始化阶段的干净检查点与会话收尾协议紧密衔接。Project 03. Multi-session continuity——把本课方法落地为真实项目的完整对照样本starter 与 solution 对比。harness-creator 技能模板——可直接复用的多语言初始化脚本模板。课程文档还推荐了 Anthropic《Effective Harnesses for Long-Running Agents》、OpenAI《Harness Engineering》、HumanLayer《Harness Engineering for Coding Agents》、Martin Fowler《Infrastructure as Code》以及 SWE-agent 的 Agent-Computer Interfaces 作为背景阅读材料可结合仓库中本课代码示例code/ 目录进一步理解初始化阶段在整个 harness 生命周期中的位置。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考