Learn Harness Engineering 实战：用初始化器输出检查清单（Initializer Output Checklist）验收 Agent 初始化阶段

Learn Harness Engineering 实战用初始化器输出检查清单Initializer Output Checklist验收 Agent 初始化阶段【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering本指南以 learn-harness-engineering 开源课程第 06 课法语版配套的初始化器输出检查清单为核心骨架系统讲解为什么 Agent 初始化必须拥有独立阶段并给出五类初始化输出的验收标准与可落地的检查项。读完本文你将掌握如何设计启动契约Bootstrap Contract、任务分解与干净检查点并能借助仓库中的init-check.ts、init.sh以及 Project 03 的连续性制品把初始化从口头约定变成可执行、可验证的工程流程。一、清单速览初始化阶段的五个交付验收项原文档 initializer-output-checklist.md 以一张极简清单定义了初始化器是否真正完成工作。它只有五个问题却覆盖了初始化阶段全部产出维度#检查项原文检查项中文释义验收含义1Y a-t-il une commande de démarrage canonique ?是否有规范的启动命令新会话仅凭仓库内容即可启动项目无需猜测npm run dev/make dev之类的命令2Y a-t-il une commande de vérification canonique ?是否有规范的验证命令存在一条明确的验证命令如make check/npm run check且首次运行即通过3Y a-t-il un premier artefact de progression ?是否有第一个进度产物已生成可追踪进度的文件进度日志、任务分解、feature_list.json等4Y a-t-il un premier commit stable ?是否有第一个稳定的提交git 中存在一个干净的基线检查点后续工作全部从该点出发5Y a-t-il une surface de fonctionnalité visible pour les sessions ultérieures ?是否有对后续会话可见的功能表面后续会话能直接看到项目能做什么、做到哪一步而不是靠口头交接这五项正是初始化阶段的核心产物环境可运行、测试可验证、进度可见、状态可回退、功能可接续。下文将逐一展开其背后的原理与实现方式。二、为什么初始化必须是独立阶段2.1 两件性质完全不同的工作课程正文 lecture-06 index.md 用一个打地基 vs 砌墙的比喻点明了问题本质实现阶段的优化目标是最大化已验证功能的数量与质量初始化阶段的优化目标是最大化后续所有实现阶段的可靠性与效率。两者混在一起时Agent 面临一个多目标优化问题——同时搭建基础设施和编写业务代码。由于缺乏显式优先级Agent 会天然偏向写代码因为代码是立即可见的产出而牺牲基础设施其价值要到后续会话才显现。这就像让施工队同时浇地基和砌墙墙壁可见、可展示大家会抢着砌墙但地基不牢的房子终将出现系统性塌陷。2.2 正确与错误的生命周期对比课程文档给出的生命周期流程图mermaid右侧正确路径的每一步恰好对应第一节清单中的一项环境可运行项 1、2、契约与任务列表已写项 3、5、干净检查点已提交项 4、后续会话直接在已验证任务上开工。2.3 混合会话的四种隐性成本课程文档归纳了把初始化和实现混在一起的四种代价地基未干透Agent 把 80% 精力投入功能代码只花 20% 草草配置基础设施——测试框架配了但从未验证、lint 规则设了但过于宽松、没有创建任何进度文件。这些缺陷在第一个会话中不明显Agent 还记得自己做过什么但第二个会话会立刻暴露新 Agent 不知道如何启动、如何测试、进度在哪里。未验证代码的累积在测试框架配置好之前写下的功能代码本质上是零验证代码。等回头补测试时可能发现设计从一开始就是错的——就像在未干的水泥地上贴瓷砖发现地面不平时所有瓷砖都要撬掉重来。会话预算被浪费初始化工作配环境、搭测试、理解项目结构消耗大量预算留给真正功能实现的份额就少了。结果第一个会话只完成一半功能第二个会话还要重新理解项目。隐式假设埋雷Agent 在初始化时做出的决策选哪个测试框架、目录怎么组织、依赖怎么管理如果不显式记录后续会话无法理解这些选择甚至可能做出矛盾决策——第一支施工队用了混凝土基础第二支不知道往里面钉了木桩基础开裂。课程还引述了 Anthropic 关于长时运行 Agent 的工程研究结论在多方multi-session场景下使用专用初始化阶段的项目功能完成率比混合式方法高 31%且初始化投入的时间会在随后 3~4 个会话内完全收回OpenAI Codex 的 harness engineering 指南则强调仓库即操作记录repository as system of record——首次运行就确立清晰的操作结构否则每个新会话都要重新推断项目约定。三、核心概念定义课程文档给出了六个关键概念这是理解初始化检查清单的语言基础初始化阶段Init PhaseAgent 生命周期的第一阶段——不实现任何功能只为后续所有实现阶段建立前置条件。它的产出不是代码而是基础设施。启动契约Bootstrap Contract一个新 Agent 会话能够无歧义地操作该项目的条件集合——能启动、能测试、能看到进度、能接续下一步。四个条件全部必须满足。冷启动 vs 热启动冷启动从空目录开始Agent 必须猜测项目结构热启动从模板或既有项目开始基础设施已就位。热启动远优于冷启动——好比在有水电的工地上开工而不是从一片空地开始。交接就绪Handoff Readiness项目处于任何时刻、任何新 Agent 都能接手的状态。不需要口头解释——仅凭仓库内容即可。首次验证时间Time to First Verification从项目开始到第一个功能点通过验证所花的时间是衡量初始化效率的关键指标。下游可用性Downstream Usability衡量初始化质量的最佳指标——后续会话能在不依赖隐式知识的前提下成功执行任务的比例。四、如何正确产出五类初始化输出课程正文Comment bien faire linitialisation一节给出了标准做法与清单的五项一一对应。4.1 可执行环境对应检查项 1项目能启动、依赖已安装、无环境问题。初始化器必须验证make setup/npm install从零开始能成功执行。4.2 可验证的测试框架对应检查项 2至少有一个示例测试通过。这证明测试框架本身配置正确——好比在地基上立起一根柱子证明它能承重。4.3 启动契约文档对应检查项 3、5一份清晰的文档告诉后续会话如何启动、如何测试、当前状态与目录结构。课程文档给出了可直接套用的完整模板# Initialization Contract ## 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.4 任务分解清单对应检查项 5把整个项目拆成有序任务列表每个任务带清晰的验收标准# 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 - ...4.5 干净的 git 检查点对应检查项 4初始化完成后提交一个干净的检查点。所有后续工作都从这个检查点出发——这就是清单中第一个稳定提交的落地形态。4.6 初始化完成标准注意判据不是写了多少代码而是启动契约的四项条件是否全部满足——能启动、能测试、能看到进度、能接续下一步。课程提供的验收清单## 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五、热启动策略用模板预置基础设施课程明确推荐不要从空目录开始使用项目模板create-react-app、fastapi-template 等预置标准目录结构、依赖配置和测试框架把通用初始化步骤固化进模板只留下项目特有的初始化工作。这与你第一节清单的关系是模板负责让启动命令、验证命令天然存在初始化器只需补充进度产物、任务分解和基线提交。六、仓库源码佐证把清单变成可执行检查初始化器输出清单不能只停留在纸面。本仓库的 lecture-06 代码目录 提供了两个可运行示例把初始化前提条件和初始化脚本变成了真实代码。6.1init-check.ts把前提条件编程化init-check.ts 用 TypeScript 程序化地检查初始化前置条件共 8 项检查按类别分为类别检查项缺失影响源码中impactIfMissing字段RuntimeNode.js 版本 18TypeScript 特性与内置 API 不可用Configpackage.json 存在无法安装依赖或运行脚本Dependenciesnode_modules 已安装所有 import 在运行时失败ToolchainTypeScript 可用npx tsc --version无法编译 TypeScriptConfigtsconfig.json 存在编译器走默认配置可能不匹配项目需求Structure源码目录存在src/lib/appAgent 找不到要修改的源文件Structure测试目录存在test/tests/tests/specAgent 找不到也跑不了既有测试Version Controlgit 仓库已初始化无回滚能力、无变更历史脚本末尾还内置了两种场景模拟simulateWithoutInit/simulateWithInit无初始化阶段时Agent 直接开工每踩到一个缺失前提就浪费 200ms 逐个发现有初始化阶段时所有问题在开工前一次性暴露workSucceeded只在零失败时为 true。这正是清单检查项 1、2 的自动化形态——把能否启动、能否验证变成机器可判定的布尔值。运行方式npx tsx docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts6.2init.sh把初始化收敛为一条命令init.sh 展示了最简初始化脚本的骨架——安装依赖并预留项目特有启动的钩子#!/usr/bin/env bash set -euo pipefail echo [init] installing dependencies npm install echo [init] starting the docs site is optional echo [init] use npm run docs:dev for course docs echo [init] project-specific startup would go hereset -euo pipefail保证任何一步失败立即中断——这正是规范化验证命令的工程化表达命令要么全绿要么立即失败不允许半成品状态被当作成功。6.3 Project 03 的连续性制品清单在真实项目中的完整落地第 06 课配套的实战项目是 Project 03: Multi-Session Continuity多会话连续性与范围控制其solution/目录就是初始化器输出的教科书式实现init.shprojects/project-03/solution/init.sh三步走——npm install→npm run check类型检查→npm run build最后提示npm run dev启动。这直接对应清单检查项 1、2 的规范启动命令 规范验证命令。session-handoff.mdprojects/project-03/solution/session-handoff.md记录上次会话完成的工作、剩余事项、做出的决策、修改的文件——这就是交接就绪Handoff Readiness的落地文件对应检查项 3、5。claude-progress.mdprojects/project-03/solution/claude-progress.md按每次只实现一个功能策略逐条记录功能从实现、验证到更新feature_list.json的全过程构成第一个进度产物检查项 3。clean-state-checklist.mdprojects/project-03/solution/clean-state-checklist.md把干净状态拆成构建验证、功能验证、范围控制验证、代码质量、文档五组勾选项——是课程初始化验收清单在生产项目中的超集版本。AGENTS.mdprojects/project-03/solution/AGENTS.md开篇就是Startup Rules——写任何代码前按序完成读文件、读架构文档、跑npm install npm run check、读feature_list.json把初始化动作固化进 Agent 的强制启动流程。对照检查Project 03 的 solution 恰好完整命中清单五问——有启动命令npm run dev、有验证命令npm run check、有进度产物claude-progress.md/feature_list.json、有稳定基线git 提交 检查清单、有可见功能表面docs/PRODUCT.md与 handoff 文档。而它的starter/目录刻意缺少这些制品用于做对照实验验证它们对跨会话交付质量的真实影响。七、对照实验混合会话 vs 专用初始化课程文档以一个 React 前端项目为例给出了两种做法的对比混合式同时打地基和砌墙Session 1 同时搭脚手架和实现第一个功能。会话结束时仓库有可执行代码但没有显式的启动/测试命令文档、没有进度追踪文件、没有任务分解。Session 2 花了约 20 分钟推断项目结构、测试框架和构建流程。专用初始化地基优先Session 1 只做初始化——基于模板创建目录结构、配置测试框架Vitest React Testing Library、编写并验证一个示例测试、创建启动契约文档和任务分解文件、提交初始检查点。Session 2 的重建时间不到 3 分钟直接从任务列表开工。课程给出的全项目周期对比结论混合式在全部会话上的总重建时间比专用初始化高出约 60%初始化多花的 20 分钟在后续会话中被多次收回。八、要点总结初始化与实现拥有不同的优化目标——混在一起会把两者都拖垮。先打地基再砌墙。初始化的产出不是代码而是基础设施可执行环境、可验证测试、启动契约、任务分解。用启动契约的四个条件验收初始化能启动、能测试、能看到进度、能接续下一步。热启动优于冷启动用项目模板预置标准化基础设施。初始化投入的时间会在随后的 3~4 个会话内完全收回。它不是额外成本而是初始投资——地基越牢墙砌得越快。九、配套练习与延伸学习课程为初始化清单配套了三个可操作的练习见 lecture-06 index.md设计启动契约为你的项目写一份完整的启动契约然后开启一个全新 Agent 会话只给它仓库内容不给任何口头上下文让它尝试启动、跑测试、理解当前进度记录每个遇到的问题——每个问题都对应契约中缺失的一条。对照实验选一个中等复杂度的新项目。方案 A让 Agent 同时做初始化和首个功能方案 B用一个会话专门初始化Session 2 再开始实现。跑 4 个会话后比较首次验证时间、重建成本与功能完成率。设计初始化验收清单为你的项目设计一份验收清单让新 Agent 会话逐项执行并记录通过/失败——失败项就是你的 harness 需要加固的地方。仓库内可继续深入的材料第 05 课长时任务为何丢失连续性 与第 06 课共同构成多会话连续性的完整话题Project 03 完整实现 提供了一份可直接对照的参考 harness若想观察清单缺失时的反例直接查看 Project 03 starter 即可——它没有init.sh、session-handoff.md、claude-progress.md和clean-state-checklist.md正是用来亲身体验第二次会话一切都要重新推断的试验场。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考