learn-harness-engineering 编码代理开工流程（Coding Agent Startup Flow）：会话启停的标准操作程序
【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文讲解 learn-harness-engineering 仓库中定义的「编码代理开工流程」一套在每次会话初始化完成后、正式动手改代码之前必须执行的标准操作程序SOP。它回答了 Agent 编码工作中的一个核心工程问题——如何让每一轮会话都在可验证、可续接、不会在坏状态上叠改动的前提下开始与结束。读完本文你将掌握 9 步固定开工模板、每一步背后的原理与仓库中的真实落地形态init.sh、claude-progress.md、feature_list.json、session-handoff.md以及与之镜像对应的收尾流程。一、为什么编码会话需要一套固定开工流程1.1 会话是无状态的仓库才是系统记录在 learn-harness-engineering 的课程体系中有一个核心论断长期任务之所以丢失连续性是因为每次新会话都是一张白纸。Agent 的上下文窗口会在会话结束时清空而仓库文件是唯一能在会话之间存活下来的持久载体参见第 3 讲为什么仓库必须成为系统记录 与第 5 讲为什么长期任务会丢失连续性。因此开工流程的本质不是「仪式感」而是把「当前处于什么状态、接下来做什么」这件事从 Agent 的记忆里搬进仓库文件里让每个新会话都能在几秒钟内恢复出全部上下文。1.2 顺序即协议9 步模板为什么不能乱开工模板给出的 9 个步骤之间存在严格的依赖关系顺序本身就是约束。下面逐条拆解运行pwd确认仓库根目录——防止在错误目录里干活。很多「改了没生效」的诡异问题根源其实是 Agent 在子目录或错误的工作区里编辑了文件。读取claude-progress.md——恢复持久状态。这个文件记录了上次会话的验证结果、未完成功能与阻塞项模板见 docs/ru/resources/templates/claude-progress.md。读取feature_list.json——恢复功能清单与优先级。它回答了「接下来该做什么」。用git log --oneline -5查看最近 5 条提交——快速解释上次会话结束时发生了什么变更。运行./init.sh——把启动过程标准化而不是靠记忆执行一串命令。跑一条基础 smoke test 或端到端路径——建立「基线是绿的」这一事实。如果基础状态已坏先修这个——永远不要在红基线上叠加新改动。选择最高优先级的未完成功能——从 feature_list.json 中挑选。只围绕这个功能工作直到它被验证或明确 blocked——单活动功能约束对应feature_list.json中single_active_feature: true规则。第 7 步是全流程的纪律核心基线验证必须先于任何新工作否则新改动会「掩盖」旧的破坏让问题在事后难以定位。二、开工流程的五个关键工件仓库里的真实落地形态开工流程不是抽象口号仓库中给出了每个工件的可直接复制模板与真实用例。2.1 init.sh标准化启动模板位于 docs/ru/resources/templates/init.sh核心结构如下#!/usr/bin/env bash set -euo pipefail ROOT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) cd $ROOT_DIR # Replace these commands with the correct commands for your repository. INSTALL_CMD(npm install) VERIFY_CMD(npm test) START_CMD(npm run dev) echo Working directory: $PWD echo Syncing dependencies ${INSTALL_CMD[]} echo Running baseline verification ${VERIFY_CMD[]} ...要点解读set -euo pipefail任何一步失败立即退出防止「假装成功」继续往下跑——这本身就是对「过早宣布胜利」问题的防御。ROOT_DIR用脚本自身位置推导仓库根配合cd $ROOT_DIR让脚本在任何目录下被调用都能落到正确位置这正是开工模板第 1 步pwd的脚本化等价物。三个命令数组INSTALL_CMD/VERIFY_CMD/START_CMD可按仓库替换默认用npm install同步依赖、npm test做基线验证。RUN_START_COMMAND1时才会直接拉起应用默认只打印启动命令避免 init 阶段误启动长驻进程。真实项目中的落地示例见 projects/project-01/solution/init.sh它按npm install→npm run check类型检查→npm run build构建三步执行并在结尾明确提示Run npm run dev to launch the application——同样体现了「先验证再启动」的顺序纪律。2.2 claude-progress.md会话间持久状态模板见 docs/ru/resources/templates/claude-progress.md固定包含两部分当前已验证状态仓库根路径、标准启动路径、标准验证路径、当前最高优先级未完成功能、当前阻塞项。会话日志按### 会话 001、### 会话 002递增编号每条记录日期、目标、已完成事项、实际运行的验证、记录的证据、提交哈希、更新的文件/工件、已知风险、下一步最佳行动。这个文件解决了「上次会话到底做到哪了」的问题是开工模板第 2 步的读取对象也是收尾流程第 1 步「记录进度」的写入对象。2.3 feature_list.json功能即原语模板见 docs/ru/resources/templates/feature_list.json这是「功能清单是 harness 原语」一讲的直接载体参见第 8 讲为什么功能清单是 harness 原语。其结构要点rules 区声明三条元规则single_active_feature: true同时只允许一个活动功能、passing_requires_evidence: true通过必须有证据、do_not_skip_verification: true不得跳过验证。status_legend 区定义四个状态not_started、in_progress当前活动任务、blocked需先解决记录的阻塞项、passing验证通过且证据已记录。features 数组中的每条功能包含id如 chat-001、priority数值越小优先级越高、area、title、user_visible_behavior用户可见行为即验收标准、status、verification可执行验证步骤列表、evidence证据记录、notes。精简形态的示例见 docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json它用passes: false布尔字段直接表达「该功能尚未通过验证」。真实项目用例则存在于 projects/project-01/solution/feature_list.json 等多个项目目录。开工模板第 3、8 步分别对应读取该文件、并从中挑选status ! passing且priority最小的功能作为本轮唯一目标。2.4 session-handoff.md交接摘要模板见 docs/ru/resources/templates/session-handoff.md固定五个板块现在已验证的内容当前能跑什么、实际跑了哪些验证本会话变更新增的代码/行为、基础设施或 harness 的改动已损坏或未验证的部分已知缺陷、未验证路径、对下一会话的风险下一步最佳行动最高优先级未完成功能、为什么是它、什么算通过、此步骤中不能改什么命令速查启动命令、验证命令、定向调试命令。这份文件是收尾流程第 3 步「写交接摘要」的标准格式也是「长期任务连续性」主题的实操工具相关讲稿见 docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/。仓库同时提供了该模板的可编辑副本 skills/harness-creator/templates/session-handoff.md。2.5 git log用提交历史解释「刚刚发生了什么」git log --oneline -5只展示最近 5 条提交的单行摘要。它的作用不是审计而是快速对齐上一会话结束时提交了什么、有没有遗留未提交的改动。结合claude-progress.md中的「提交」字段Agent 可以判断持久状态文件与 git 历史是否一致。三、对应的收尾流程开工模板的镜像开工模板要求会话结束同样按固定顺序收尾五步与开工步骤形成镜像记录进度——更新 claude-progress.md 的会话日志更新功能状态——把 feature_list.json 中本条功能的 status 改为passing、blocked或保持in_progress并同步last_updated必要时写交接摘要——生成/更新 session-handoff.md提交安全状态的代码——只提交已验证、不会破坏基线的变更留下可直接重启的干净环境——保证下一会话执行开工模板时能顺利通过第 6 步基线验证。镜像关系的意义在于闭环收尾时留下的文件恰好就是开工时读取的文件开工时的基线验证恰好能检验收尾是否留下了干净状态。这也与「会话必须留下干净状态」的主题一脉相承参见第 12 讲为什么每次会话都必须留下干净状态。四、把流程嵌入 harness从模板到项目实践4.1 三份模板文件与项目结构的关系在真实项目中开工模板所需的工件按以下约定落位以项目目录为根init.sh放在仓库根目录直接可执行chmod x后运行./init.shclaude-progress.md、feature_list.json同样放在仓库根与 AGENTS.md / CLAUDE.md 等 harness 指令文件并列session-handoff.md在需要多会话接力时生成。参见真实用例 projects/project-01/solution/含 init.sh、claude-progress.md、feature_list.json、AGENTS.md、CLAUDE.md 的完整布局与 projects/project-02/solution/含 session-handoff.md 的多会话示例。4.2 常见误用与规避跳过 init.sh 直接改代码等于放弃了基线验证第 6、7 步的防线失效同时推进多个功能违反single_active_feature规则导致状态文件互相污染把 status 标成 passing 却没有证据违反passing_requires_evidencefeature_list.json 的evidence数组必须记录实际运行的验证输出收尾不写 handoff 就提交下一会话只能靠猜开工模板第 2、3 步会读到过期状态。五、总结开工与收尾是一枚硬币的两面编码代理开工流程本质上是一条可复制的状态恢复协议开工 9 步负责「读状态 → 验基线 → 选唯一目标」收尾 5 步负责「写状态 → 留证据 → 保干净」。两者共用同一套工件claude-progress.md、feature_list.json、session-handoff.md、init.sh因此在 learn-harness-engineering 的项目实践中它们被统一收纳为模板目录 docs/ru/resources/templates/并被 harness-creator 技能skills/harness-creator/templates/引用为生成新项目 harness 的标准零件。对任何想把 Agent 从「一次性的、靠运气的编码会话」升级为「可接力、可审计、可验证的持续工程过程」的开发者而言这套开工/收尾流程是最小可用、也最容易被验证的起点它不依赖任何特定模型能力只依赖「把状态写进文件、把验证跑在基线前」这两条朴素纪律。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 实战编码 Agent 会话启动流程Coding Agent Startup Flow完整指南learn harness engineering 实战编码 Agent 会话启动流程Coding Agent Startup Flow完整指南 本指南以learn-harness-engineering 实战为编码 Agent 建立固定会话启动流程Coding Agent Startup Flowlearn harness engineering 实战为编码 Agent 建立固定会话启动流程Coding Agent Startup Flow 本指南Learn Harness Engineering 实战Coding Agent 会话启动流程Startup Flow九步模板Learn Harness Engineering 实战Coding Agent 会话启动流程Startup Flow九步模板 本指南围绕 coding上一篇在 Android Studio 中配置 Firebase Agent SkillsGemini 本地集成与 MCP 限制实战指南下一篇VisiData 数据解谜实战Noahs Tapestry 第 1 关——用 T9 号码映射找出私人侦探的电话创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考