初始化阶段产出清单让每个 Agent 会话都从可运行、可验证、可接续的起点开始learn-harness-engineering 实战解析【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering在 Agent 驱动的多会话开发中初始化不是一个可有可无的前奏而是决定后续所有实现会话效率与可靠性的关键阶段。本指南以 learn-harness-engineering 仓库中「初始化需要独立阶段」讲义配套的《イニシャライザー出力チェックリスト》初始化器输出检查清单为核心骨架逐项拆解初始化阶段必须产出的五类工件并结合仓库内的可执行检查脚本init-check.ts、初始化脚本init.sh以及 Project 03 的完整落地方案帮助你掌握一套可直接复制、可自动验证的初始化验收标准。一、为什么初始化必须拥有自己的独立阶段在深入检查清单之前先理解它存在的理由。在《讲 06为什么初始化需要独立阶段》中作者用一个形象的比喻解释了问题建房子时打地基和砌墙不能同时进行——如果边打地基边砌墙墙会在地基凝固前就立起来最终只能推倒重建。初始化和功能实现拥有本质不同的优化目标实现阶段的优化目标是最大化已验证功能的数量与质量初始化阶段的优化目标是最大化后续所有实现的可靠性与效率。如果两者混在一起Agent 会面临一个多目标优化问题——一边搭基础设施、一边写功能代码。在没有显式优先级的情况下Agent 天然会被写代码吸引因为那是立即可见的产出而基础设施其价值只在后续会话中显现则被牺牲。这正是初始化需要独立成阶段、并在结束时用产出清单验收的根本原因。二、初始化器输出检查清单五条验收标准位于 docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md 的检查清单用五个问题界定了初始化阶段合格的输出边界#检查项日文原文含义缺失时的后果1正規の起動コマンドはあるか有没有规范的启动命令后续会话只能靠猜来运行项目每次都要重新摸索2正規の検証コマンドはあるか有没有规范的验证命令代码改完后无法快速确认是否破坏已有功能3最初の進捗アーティファクトはあるか有没有最初的进度工件会话之间无法传递做到哪一步的状态4安定した最初のコミットはあるか有没有稳定的初始提交没有回滚锚点出错时无法回到干净基线5後のセッション向けに可視的な機能面はあるか有没有面向后续会话的可见功能面新会话不知道该从哪个功能点继续切入这五条与讲义中定义的**引导契约Bootstrap Contract**一一对应。引导契约要求项目满足四个条件全部为必须项能启动runnable、能测试testable、进度可见visible progress、能接续下一步next step actionable。检查清单正是把这四个抽象条件翻译成了五个可操作的产出物。三、逐项拆解如何落地每一项检查3.1 规范的启动命令初始化结束时仓库必须能让一个完全陌生的新 Agent 会话仅凭仓库内容就知道怎么运行。启动命令需要固化到脚本或包管理配置中如make dev、npm run dev而不是散落在口口相传里从零环境可以完整执行npm install等依赖安装步骤包含在流程内在文档中显式声明。仓库中的初始化脚本给出了一个最小可复制的模板#!/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 here关键点是set -euo pipefail——任何一步失败都立即中断避免假装初始化成功。而 Project 03 的 init.sh 则展示了更完整的三步式启动流程把安装依赖 → 类型检查 → 构建串成一个可重复执行的验收链echo [1/3] Installing dependencies... npm install echo [2/3] Running type checks... npm run check echo [3/3] Building project... npm run build echo Init complete. All checks passed. echo Run npm run dev to launch the application.3.2 规范的验证命令能启动不等于能验证。检查清单第二条要求至少存在一条规范的验证命令如make test、npm run check并且至少有一个示例测试真实通过。这证明了测试框架本身配置正确——正如讲义所说在基础之上立一根柱子证明它能承受荷载。注意验证命令必须是可重复、可自动执行的。在 Project 03 的 AGENTS.md 中Startup Rules把这条固化成了流程规则4. Run npm install npm run check to verify the project builds cleanly.也就是说每个新会话开始工作前必须先跑验证命令确认自己站在一个绿色的基线上。这直接对应检查清单第二条并且通过 AGENTS.md 的形式保证了跨会话的一致性。3.3 最初的进度工件进度工件progress artifact是会话间传递状态的载体。在清单语境下它至少包含两类文件状态文件记录所有功能点的当前状态已完成/进行中/未开始及其证据交接文档说明上一会话完成、遗留、卡点与决策。仓库中 Project 03 的 feature_list.json 就是状态文件的典型实现——每条功能记录id、name、description、status、evidence和testedAt字段evidence字段用具体实现细节如IndexingService.chunkDocument() splits on paragraph boundaries…而非空话证明完成状态。配合 session-handoff.md 与 claude-progress.md构成了完整的进度可见体系。讲义还给出了任务拆解Task Breakdown的格式规范每个任务必须带明确的接受标准acceptance criteria例如## Task 1: User Authentication Basics - Implement JWT auth middleware - Add login/register endpoints - Acceptance: pytest tests/test_auth.py all passing3.4 稳定的初始提交初始化完成时必须产生一个干净的 Git 检查点提交。它的价值在于提供回滚锚点——后续所有工作从这个基线开始让初始化是否完成有了不可篡改的客观证据.git 历史新会话可以通过git log/git status快速确认项目是否处于干净状态。init-check.ts 将Git 仓库已初始化列为八项前置检查之一缺失时的影响描述为 No rollback capability, no change history。同样Project 03 的 clean-state-checklist.md 在 Code Quality 与 Documentation 部分把提交要求展开为可勾选条目。3.5 面向后续会话的可见功能面这一条最容易理解偏差。它的含义不是初始化阶段就要实现功能而是初始化产出的基础设施必须能让后续会话一眼看到功能从哪开始做、做到什么程度。具体形态包括目录结构清晰src/、tests/等标准布局Agent 能定位源码与测试feature_list.json或等价的任务清单存在且至少包含若干条未开始的任务文档层级明确如 Project 03 AGENTS.md 中的docs/ARCHITECTURE.mddocs/PRODUCT.md结构功能依赖关系被显式记录Project 03 的 AGENTS.md 就用 ASCII 图声明了metadata-extraction → document-chunking → indexing-status-ui的依赖链。有了这张可见的功能面新会话不再需要把整个项目重新读一遍而是直接从任务列表挑选下一条待办——这正是检查清单要保证的能接续下一步。四、用源码自动验证init-check.ts 与初始化前后对比init-check.ts 是本检查清单的可执行化实现。它定义了八项前置检查每一项都包含name、category、check与impactIfMissing缺失影响四个维度检查项类别缺失影响Node.js 版本 18RuntimeTypeScript 特性与内置 API 不可用package.json 存在Config无法安装依赖或运行脚本node_modules 已安装Dependencies所有 import 在运行时失败TypeScript 可用npx tscToolchain无法编译 TS 文件tsconfig.json 存在Config编译器走默认配置可能与项目需求不符src/lib/app 目录存在StructureAgent 找不到要修改的源文件test/tests 目录存在StructureAgent 找不到也无法运行现有测试.git 目录存在Version Control无回滚能力、无变更历史脚本的核心价值在于它做了有无初始化阶段的对比模拟无初始化阶段Agent 跳过前置检查直接开工遇到缺失项时逐个边做边发现每一项缺失按 200ms 计为后期浪费时间timeWastedMs 200而且即便存在问题也会继续尝试工作workAttempted: true有初始化阶段Agent 先跑完八项检查全部通过才开始工作前置失败数failuresBeforeWork在开工前就暴露无遗后期浪费时间为 0。这个模拟直观证明了讲义的核心论点先发现问题的成本远低于边做边发现问题的成本。脚本运行方式见文件头注释npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts它会输出明细表格每项 PASS/FAIL 与 Detail、失败项的影响清单以及一张 INIT PHASE COMPARISON 对比表从前置检查是否执行带问题开工后期发现问题的浪费时间工作是否成功四个指标对比两种策略。五、初始化验收清单把检查清单落到 CI 与每个会话讲义在检查清单之外还给出了一份可勾选的初始化验收清单Initialization Acceptance Checklist可以视为检查清单五个问题在命令层面的具体化## 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逐条对照make setup从零环境成功→ 对应检查清单第 1 条规范的启动命令要求命令无任何隐藏前置条件make test至少有一个通过的测试→ 对应第 2 条规范的验证命令证明测试框架本身可用新 Agent 仅凭仓库内容能回答怎么运行/怎么测试→ 这是第 1、2 条的盲测形式模拟真实接续场景任务拆解文件存在且至少 3 个任务→ 对应第 5 条可见功能面保证后续会话有明确的切入点全部内容已提交到 Git→ 对应第 4 条稳定初始提交。Project 03 的 clean-state-checklist.md 展示了这种清单在生产项目中的完整形态它把验收拆成 Build Verification、Feature Verification、Scope Control Verification、Code Quality、Documentation 五大板块每项带勾选状态让初始化/收尾是否合格变成一个可复核的过程。建议把这份清单模板化为仓库根目录文件并在每次会话结束时重新过一遍——失败的项目就是 harness 需要强化的地方。六、冷启动 vs 暖启动让检查清单更容易通过检查清单的五个问题在冷启动空目录起步下极难全部通过因为 Agent 必须在猜结构的同时搭环境。讲义给出的策略是暖启动Warm Start从项目模板起步create-react-app、fastapi-template 等预先带好标准目录结构、依赖配置与测试框架把通用初始化步骤固化为模板只保留项目特有的初始化工作效果相当于在有水电的工地开工而非从荒野开始。这意味着检查清单不只是验收工具更是初始化策略的设计指南。当五个问题都能在模板层面预先回答时每个新项目的初始化就只剩写引导契约文档 拆任务 首次提交三件事。七、关键要点初始化与实现拥有不同的优化目标混在一起只会两头落空——先打地基再砌墙初始化阶段产出的是基础设施而非代码可运行的坏境、可验证的测试、引导契约文档、任务拆解、Git 检查点初始化器输出检查清单的五个问题启动命令、验证命令、进度工件、初始提交、可见功能面本质上是引导契约四条件能启动、能测试、进度可见、能接续的可操作翻译用 init-check.ts 这类前置检查脚本把后期逐个踩坑变成前期一次性暴露暖启动远胜冷启动用项目模板预置标准化基础设施只保留项目特有的初始化工作初始化上投入的时间会在接下来的 34 个会话中完全回收讲义引用的实验数据显示使用专用初始化阶段的项目在多会话场景下功能完成率更高、总重建时间更少——它不是额外成本而是先行投资。八、继续深入完整讲义正文含生命周期图、混用场景分析、正反实例对比docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md前置检查脚本与初始化脚本code/init-check.ts、code/init.sh多会话连续性的完整实战项目含 AGENTS.md 启动规则、feature_list.json、clean-state-checklist.mdprojects/project-03/solution/AGENTS.md、projects/project-03/solution/init.sh、projects/project-03/solution/feature_list.json、projects/project-03/solution/clean-state-checklist.md对应实践项目讲义docs/ja/projects/project-03-multi-session-continuity/index.md实践建议为手头项目写一份引导契约文档然后开一个全新 Agent 会话只给它仓库内容不给任何口头背景让它回答怎么启动、怎么测试、当前进度如何——遇到的每一个问题都是这份检查清单里应当补上的条款。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 初始化阶段产出清单：让每个 Agent 会话都从可运行、可验证、可接续的起点开始（learn-harness-engineering 实战解析）
初始化阶段产出清单让每个 Agent 会话都从可运行、可验证、可接续的起点开始learn-harness-engineering 实战解析【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering在 Agent 驱动的多会话开发中初始化不是一个可有可无的前奏而是决定后续所有实现会话效率与可靠性的关键阶段。本指南以 learn-harness-engineering 仓库中「初始化需要独立阶段」讲义配套的《イニシャライザー出力チェックリスト》初始化器输出检查清单为核心骨架逐项拆解初始化阶段必须产出的五类工件并结合仓库内的可执行检查脚本init-check.ts、初始化脚本init.sh以及 Project 03 的完整落地方案帮助你掌握一套可直接复制、可自动验证的初始化验收标准。一、为什么初始化必须拥有自己的独立阶段在深入检查清单之前先理解它存在的理由。在《讲 06为什么初始化需要独立阶段》中作者用一个形象的比喻解释了问题建房子时打地基和砌墙不能同时进行——如果边打地基边砌墙墙会在地基凝固前就立起来最终只能推倒重建。初始化和功能实现拥有本质不同的优化目标实现阶段的优化目标是最大化已验证功能的数量与质量初始化阶段的优化目标是最大化后续所有实现的可靠性与效率。如果两者混在一起Agent 会面临一个多目标优化问题——一边搭基础设施、一边写功能代码。在没有显式优先级的情况下Agent 天然会被写代码吸引因为那是立即可见的产出而基础设施其价值只在后续会话中显现则被牺牲。这正是初始化需要独立成阶段、并在结束时用产出清单验收的根本原因。二、初始化器输出检查清单五条验收标准位于 docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md 的检查清单用五个问题界定了初始化阶段合格的输出边界#检查项日文原文含义缺失时的后果1正規の起動コマンドはあるか有没有规范的启动命令后续会话只能靠猜来运行项目每次都要重新摸索2正規の検証コマンドはあるか有没有规范的验证命令代码改完后无法快速确认是否破坏已有功能3最初の進捗アーティファクトはあるか有没有最初的进度工件会话之间无法传递做到哪一步的状态4安定した最初のコミットはあるか有没有稳定的初始提交没有回滚锚点出错时无法回到干净基线5後のセッション向けに可視的な機能面はあるか有没有面向后续会话的可见功能面新会话不知道该从哪个功能点继续切入这五条与讲义中定义的**引导契约Bootstrap Contract**一一对应。引导契约要求项目满足四个条件全部为必须项能启动runnable、能测试testable、进度可见visible progress、能接续下一步next step actionable。检查清单正是把这四个抽象条件翻译成了五个可操作的产出物。三、逐项拆解如何落地每一项检查3.1 规范的启动命令初始化结束时仓库必须能让一个完全陌生的新 Agent 会话仅凭仓库内容就知道怎么运行。启动命令需要固化到脚本或包管理配置中如make dev、npm run dev而不是散落在口口相传里从零环境可以完整执行npm install等依赖安装步骤包含在流程内在文档中显式声明。仓库中的初始化脚本给出了一个最小可复制的模板#!/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 here关键点是set -euo pipefail——任何一步失败都立即中断避免假装初始化成功。而 Project 03 的 init.sh 则展示了更完整的三步式启动流程把安装依赖 → 类型检查 → 构建串成一个可重复执行的验收链echo [1/3] Installing dependencies... npm install echo [2/3] Running type checks... npm run check echo [3/3] Building project... npm run build echo Init complete. All checks passed. echo Run npm run dev to launch the application.3.2 规范的验证命令能启动不等于能验证。检查清单第二条要求至少存在一条规范的验证命令如make test、npm run check并且至少有一个示例测试真实通过。这证明了测试框架本身配置正确——正如讲义所说在基础之上立一根柱子证明它能承受荷载。注意验证命令必须是可重复、可自动执行的。在 Project 03 的 AGENTS.md 中Startup Rules把这条固化成了流程规则4. Run npm install npm run check to verify the project builds cleanly.也就是说每个新会话开始工作前必须先跑验证命令确认自己站在一个绿色的基线上。这直接对应检查清单第二条并且通过 AGENTS.md 的形式保证了跨会话的一致性。3.3 最初的进度工件进度工件progress artifact是会话间传递状态的载体。在清单语境下它至少包含两类文件状态文件记录所有功能点的当前状态已完成/进行中/未开始及其证据交接文档说明上一会话完成、遗留、卡点与决策。仓库中 Project 03 的 feature_list.json 就是状态文件的典型实现——每条功能记录id、name、description、status、evidence和testedAt字段evidence字段用具体实现细节如IndexingService.chunkDocument() splits on paragraph boundaries…而非空话证明完成状态。配合 session-handoff.md 与 claude-progress.md构成了完整的进度可见体系。讲义还给出了任务拆解Task Breakdown的格式规范每个任务必须带明确的接受标准acceptance criteria例如## Task 1: User Authentication Basics - Implement JWT auth middleware - Add login/register endpoints - Acceptance: pytest tests/test_auth.py all passing3.4 稳定的初始提交初始化完成时必须产生一个干净的 Git 检查点提交。它的价值在于提供回滚锚点——后续所有工作从这个基线开始让初始化是否完成有了不可篡改的客观证据.git 历史新会话可以通过git log/git status快速确认项目是否处于干净状态。init-check.ts 将Git 仓库已初始化列为八项前置检查之一缺失时的影响描述为 No rollback capability, no change history。同样Project 03 的 clean-state-checklist.md 在 Code Quality 与 Documentation 部分把提交要求展开为可勾选条目。3.5 面向后续会话的可见功能面这一条最容易理解偏差。它的含义不是初始化阶段就要实现功能而是初始化产出的基础设施必须能让后续会话一眼看到功能从哪开始做、做到什么程度。具体形态包括目录结构清晰src/、tests/等标准布局Agent 能定位源码与测试feature_list.json或等价的任务清单存在且至少包含若干条未开始的任务文档层级明确如 Project 03 AGENTS.md 中的docs/ARCHITECTURE.mddocs/PRODUCT.md结构功能依赖关系被显式记录Project 03 的 AGENTS.md 就用 ASCII 图声明了metadata-extraction → document-chunking → indexing-status-ui的依赖链。有了这张可见的功能面新会话不再需要把整个项目重新读一遍而是直接从任务列表挑选下一条待办——这正是检查清单要保证的能接续下一步。四、用源码自动验证init-check.ts 与初始化前后对比init-check.ts 是本检查清单的可执行化实现。它定义了八项前置检查每一项都包含name、category、check与impactIfMissing缺失影响四个维度检查项类别缺失影响Node.js 版本 18RuntimeTypeScript 特性与内置 API 不可用package.json 存在Config无法安装依赖或运行脚本node_modules 已安装Dependencies所有 import 在运行时失败TypeScript 可用npx tscToolchain无法编译 TS 文件tsconfig.json 存在Config编译器走默认配置可能与项目需求不符src/lib/app 目录存在StructureAgent 找不到要修改的源文件test/tests 目录存在StructureAgent 找不到也无法运行现有测试.git 目录存在Version Control无回滚能力、无变更历史脚本的核心价值在于它做了有无初始化阶段的对比模拟无初始化阶段Agent 跳过前置检查直接开工遇到缺失项时逐个边做边发现每一项缺失按 200ms 计为后期浪费时间timeWastedMs 200而且即便存在问题也会继续尝试工作workAttempted: true有初始化阶段Agent 先跑完八项检查全部通过才开始工作前置失败数failuresBeforeWork在开工前就暴露无遗后期浪费时间为 0。这个模拟直观证明了讲义的核心论点先发现问题的成本远低于边做边发现问题的成本。脚本运行方式见文件头注释npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts它会输出明细表格每项 PASS/FAIL 与 Detail、失败项的影响清单以及一张 INIT PHASE COMPARISON 对比表从前置检查是否执行带问题开工后期发现问题的浪费时间工作是否成功四个指标对比两种策略。五、初始化验收清单把检查清单落到 CI 与每个会话讲义在检查清单之外还给出了一份可勾选的初始化验收清单Initialization Acceptance Checklist可以视为检查清单五个问题在命令层面的具体化## 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逐条对照make setup从零环境成功→ 对应检查清单第 1 条规范的启动命令要求命令无任何隐藏前置条件make test至少有一个通过的测试→ 对应第 2 条规范的验证命令证明测试框架本身可用新 Agent 仅凭仓库内容能回答怎么运行/怎么测试→ 这是第 1、2 条的盲测形式模拟真实接续场景任务拆解文件存在且至少 3 个任务→ 对应第 5 条可见功能面保证后续会话有明确的切入点全部内容已提交到 Git→ 对应第 4 条稳定初始提交。Project 03 的 clean-state-checklist.md 展示了这种清单在生产项目中的完整形态它把验收拆成 Build Verification、Feature Verification、Scope Control Verification、Code Quality、Documentation 五大板块每项带勾选状态让初始化/收尾是否合格变成一个可复核的过程。建议把这份清单模板化为仓库根目录文件并在每次会话结束时重新过一遍——失败的项目就是 harness 需要强化的地方。六、冷启动 vs 暖启动让检查清单更容易通过检查清单的五个问题在冷启动空目录起步下极难全部通过因为 Agent 必须在猜结构的同时搭环境。讲义给出的策略是暖启动Warm Start从项目模板起步create-react-app、fastapi-template 等预先带好标准目录结构、依赖配置与测试框架把通用初始化步骤固化为模板只保留项目特有的初始化工作效果相当于在有水电的工地开工而非从荒野开始。这意味着检查清单不只是验收工具更是初始化策略的设计指南。当五个问题都能在模板层面预先回答时每个新项目的初始化就只剩写引导契约文档 拆任务 首次提交三件事。七、关键要点初始化与实现拥有不同的优化目标混在一起只会两头落空——先打地基再砌墙初始化阶段产出的是基础设施而非代码可运行的坏境、可验证的测试、引导契约文档、任务拆解、Git 检查点初始化器输出检查清单的五个问题启动命令、验证命令、进度工件、初始提交、可见功能面本质上是引导契约四条件能启动、能测试、进度可见、能接续的可操作翻译用 init-check.ts 这类前置检查脚本把后期逐个踩坑变成前期一次性暴露暖启动远胜冷启动用项目模板预置标准化基础设施只保留项目特有的初始化工作初始化上投入的时间会在接下来的 34 个会话中完全回收讲义引用的实验数据显示使用专用初始化阶段的项目在多会话场景下功能完成率更高、总重建时间更少——它不是额外成本而是先行投资。八、继续深入完整讲义正文含生命周期图、混用场景分析、正反实例对比docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md前置检查脚本与初始化脚本code/init-check.ts、code/init.sh多会话连续性的完整实战项目含 AGENTS.md 启动规则、feature_list.json、clean-state-checklist.mdprojects/project-03/solution/AGENTS.md、projects/project-03/solution/init.sh、projects/project-03/solution/feature_list.json、projects/project-03/solution/clean-state-checklist.md对应实践项目讲义docs/ja/projects/project-03-multi-session-continuity/index.md实践建议为手头项目写一份引导契约文档然后开一个全新 Agent 会话只给它仓库内容不给任何口头背景让它回答怎么启动、怎么测试、当前进度如何——遇到的每一个问题都是这份检查清单里应当补上的条款。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考