为失忆的工程师写交接日记：learn-harness-engineering 中的 Session Handoff 文件实战

为失忆的工程师写交接日记learn-harness-engineering 中的 Session Handoff 文件实战【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读长任务必然跨会话跨会话必然丢上下文——这是 AI Coding Agent 面对的客观现实。本篇基于 learn-harness-engineering 开源仓库中第五讲「为什么长任务会丢失连续性」的配套交接文件模板 session-handoff.md讲解如何用结构化的会话交接文件Session Handoff让新会话在几分钟内接上旧会话的工作。读完本文你将掌握交接文件的最小字段结构、与 PROGRESS.md / DECISIONS.md / Git 检查点等其他连续性工件的关系以及仓库中真实项目如何落地这套方案。背景为什么 Agent 会「断片」上下文窗口是有限的资源。这不是模型升级能解决的问题——即使窗口增长到 1M tokens复杂任务依然会用完因为 Agent 不只在生成代码它还要理解代码库、跟踪自己的决策历史、处理工具输出、维护对话上下文这些信息的增长速度远超窗口扩容。更深层的问题在于信息的不均匀价值Agent 的中间推理步骤里藏着决策的「为什么」为什么选方案 B 而非 A、为什么用这个库而不用那个而最终输出只有「是什么」代码本身。压缩策略通常保留「是什么」却丢掉「为什么」下一个会话看到代码却不知道为什么这么写可能「优化」掉一个有意为之的设计决策。Anthropic 的研究还观察到一种「上下文焦虑」现象当 Agent 感觉上下文快满时会表现出去赶工收尾的行为匆忙结束工作、跳过验证步骤。这正是讲义开篇的比喻把 Agent 想象成一个每天醒来都会失忆的手艺人——他必须每天重新熟悉工地甚至可能拆掉昨天刚砌好的墙。解决方案不是让手艺人不失忆而是让他养成写日记的习惯。Session Handoff 文件就是这个「日记」的最小载体。Session Handoff 文件交接日记的最小形态仓库中第五讲代码目录下的 session-handoff.md 提供了一个最精简的交接模板全部内容只有三个字段# Session-Übergabe Beispiel 会话交接示例 ## Abgeschlossen 已完成 - Markdown-Import-Unterstützung hinzugefügt 已添加 Markdown 导入支持 - Eine grundlegende Dokumentenliste im Renderer hinzugefügt 在渲染器中添加了基础文档列表 ## Defekt oder Unverifiziert 有缺陷或未验证 - Import erfolgreich für .md, scheitert aber bei großen .txt-Dateien .md 导入成功但大 .txt 文件失败 - Die App startet, aber die Detailansicht ist noch nicht verbunden 应用能启动但详情视图尚未接通 ## Nächster bester Schritt 下一步最佳行动 - .txt-Import-Pfad reparieren 修复 .txt 导入路径 - Import End-to-End verifizieren 端到端验证导入 - Dann das Dokument-Detailpanel hinzufügen 然后添加文档详情面板这就是整个文件的核心。它刻意保持极简只回答三个问题字段回答的问题信息价值已完成Abgeschlossen上次做了什么让新会话不要重复劳动有缺陷或未验证Defekt oder Unverifiziert哪些事情还没做好让新会话清楚风险点避免在坏地基上继续施工下一步最佳行动Nächster bester Schritt接下来优先做什么给新会话一个明确的起点而不是重新探索注意「下一步最佳行动」写的是单个最佳行动及其后续排序而不是一张含糊的待办清单。它直接指向session-simulator.ts中演示的核心能力新会话读了交接文件后应该能从第 4 步接着干而不是从第 1 步重新开始。从交接文件到可复现运行的验证交接文件的价值可以通过仓库中的模拟器直接量化。session-simulator.ts 用代码模拟了同一任务在两种场景下的表现任务包含 6 个步骤读项目结构 → 理解认证模块 → 设计搜索端点 → 实现搜索端点 → 写集成测试 → 更新文档会话 A 完成前 3 步后超时。无交接文件会话 B 没有上下文从第 1 步重新开始重复完成了会话 A 已做的前 3 步产生 3 步重复劳动和对应的时间浪费有交接文件会话 B 读取交接文件后从第 4 步继续重复步骤为 0。运行方式在仓库根目录npx tsx docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts输出会生成一张对比表直观显示「Time saved by handoff」交接省下的时间。这个模拟器印证了讲义中的核心概念——重建成本Rebuild Cost新会话恢复到可执行状态所需的时间好的 harness 设计能把重建成本从 15 分钟压到 3 分钟。完整交接体系真实项目中的四个字段扩展上面这份最小模板适合作为起点但仓库中真实项目的交接文件要更完整。以 project-02 的会话交接文件 和 project-03 的会话交接文件 为例可以看到在最小三字段之外扩展出的四个关键部分1. 会话时间戳Last Session## Last Session: 2026-03-30标注交接文件的更新时间。这看似简单却让新会话能快速判断交接信息的新鲜度——如果仓库已被大幅改动而交接文件还是上周的说明状态已经漂移。2. 文件修改清单Files Modifiedproject-02 的交接文件详细列出了本次会话改动的所有文件并附带每个文件的改动说明### Files Modified - src/shared/types.ts -- Added GET_DOCUMENT_CONTENT IPC channel - src/main/ipc-handlers.ts -- Registered GET_DOCUMENT_CONTENT handler - src/preload/preload.ts -- Exposed documents.getContent() - src/renderer/App.tsx -- Added import toggle, delete handler, mount-time refresh - ...这份清单把交接文件与 Git 提交记录衔接起来新会话既可以读交接文件快速定位也可以在需要细节时按图索骥去查对应文件与提交。3. 决策记录Decisions Made这是讲义中「DECISIONS.md」思想的内嵌版本。project-02 的交接文件记录了三个关键决策及其理由例如- Added GET_DOCUMENT_CONTENT as a new IPC channel rather than bundling content with GET_DOCUMENT to keep payloads small for list views.注意格式遵循「什么决策、为什么、什么时候做的」三要素——不需要详细设计文档只要记下决策和动机防止下一个会话基于不完整信息重新决策讲义中反复强调的「为什么选方案 B 而非 A」问题。project-03 的交接文件同样记录了元数据提取时机、按段落分块策略、一次只做一个功能的执行纪律等决策正是这些「为什么」让后续会话能与前序会话保持决策一致性避免漂移Drift。4. 阻塞项Blockersproject-02 和 project-03 的交接文件都有独立的### Blockers段落记录阻碍当前进展的问题。Project-03 中的值为None.而最小模板中「有缺陷或未验证」字段其实承担了同样的职责——把已知风险显式暴露给下一班「接班的工程师」。交接文件只是日记的一页完整的连续性工件体系从讲义 index.md 可以看到Session Handoff 文件是「状态持久化」体系中的一环它与其他工件配合使用才能覆盖「状态 → 原因 → 验证 → 快照」四个维度工件对应维度说明PROGRESS.md状态当前进度当前 commit、测试状态、已完成、进行中、已知问题、下一步DECISIONS.md原因记录「什么决策、为什么、什么时候」验证记录验证哪些测试通过、哪些失败、为什么失败Git 检查点快照每完成一个原子工作单元就提交commit message 说清楚做了什么和为什么Session Handoff交接面向「下一班」的精简交接已完成 / 有缺陷或未验证 / 下一步最佳行动init.sh / AGENTS.md流程规定每次「上班」和「下班」的例行程序上班 / 下班例行程序讲义给出了一套可写入AGENTS.md的「打卡」流程## 每次会话开始时上班 1. 读 PROGRESS.md 了解当前状态 2. 读 DECISIONS.md 了解重要决策 3. 跑 make check 确认仓库处于一致状态 4. 从 PROGRESS.md 的「下一步」部分继续工作 ## 每次会话结束前下班 1. 更新 PROGRESS.md 2. 跑 make check 确认一致状态 3. 提交所有已完成的工作Session Handoff 文件的更新应发生在「下班」例行程序中与 PROGRESS.md 的更新同步进行——一个是给「白班」自己看的完整日记一个是给「夜班」同事看的精简交接。四问检查清单同目录下的 continuity-checklist.md 提供了一份极简的交接质量自检清单# 连续性检查清单 - 新 Agent 能否在五分钟内识别出当前工作 - 当前稳定的启动路径是否已文档化 - 未完成的工作是否被清晰标注 - 下一步最佳任务是否无需翻阅旧聊天记录即可看到这四问是判断交接文件是否合格的验收标准新会话不依赖旧聊天记录、五分钟内定位工作、明确知道下一步做什么。项目中的真实落地project-03 的连续性 harnessproject-03 的 README 展示了一个以「多会话连续性」为评估目标的完整实验starter 与 solution 的关键差异恰恰就在于是否包含重启/连续性工件——init.sh、session-handoff.md、claude-progress.md、clean-state-checklist.md。README 明确把「Continuity harness」列为一个交付物并指出 solution 中的AGENTS.md包含「一次只做一个功能」的策略与功能依赖图。project-03 的 session-handoff.md 是本文主题最完整的仓库实例它记录了元数据提取、文档分块、索引状态 UI、带引用的接地问答四块功能的实现情况决策记录说明了「导入时提取元数据」「按段落感知分块双换行避免切碎句子」「严格遵循一次一功能策略」等关键决策最后以「无阻塞项、下一步进入 Project 04」收尾。这与你我手上的最小三字段模板一脉相承只是针对真实多会话开发扩充了信息量。这套体系的实战收益可以用讲义中的案例量化实现一个带用户认证的博客系统12 个功能点预计 5 个会话——基线场景无交接工件到第 5 个会话时仅完成 7 个功能点、3 个存在隐含正确性问题使用进度文件、决策日志、验证记录和 Git 检查点后12 个功能点全部完成并验证重建时间减少约 78%功能完成率从 58% 提升到 100%。最佳实践与混合策略综合讲义与仓库实践Session Handoff 的最佳使用方式可以总结为以下几点把 Agent 当失忆的工程师管理每次「下班」前必须写下做了什么、为什么、下一步做什么交接文件保持精简三字段最小模板已完成 / 有缺陷或未验证 / 下一步最佳行动是底线可在真实项目中扩展文件清单、决策记录与阻塞项与 Git 检查点配合交接文件描述状态Git 提交提供精确的、自动版本化的仓库快照用重建成本作为关键指标好的 harness 应让新会话在 3 分钟内恢复到可执行状态参考 session-simulator.ts 的量化对比方法采用混合策略短任务30 分钟以内在单会话内完成长任务跨会话必须依赖结构化工件维持连续性判断标准是——如果任务需要的上下文超过窗口的 60%就开始准备交接用四问清单验收每次会话结束时用 continuity-checklist.md 的四问检查交接质量。动手练习讲义提供了三个可直接上手的实验帮助你验证本文结论连续性损耗度量选一个需要至少 3 个会话的开发任务。先不给任何交接工件在每个会话开始时记录 Agent 花了多少上下文「搞清楚上次做了什么」之后引入进度文件对比两次的重建成本。交接模板设计设计一个最小交接模板包含四个字段——仓库状态commit hash、运行时状态测试通过率、阻塞项、下一步行动。让一个全新会话只凭模板恢复项目状态记录恢复中的歧义点并迭代模板可以 project-02 的 session-handoff.md 为参照。混合策略实验在 5 个会话的开发任务中对比三种策略每次开新会话 进度文件、单会话尽量多做压缩、混合策略。对比重建时间、功能完成率与决策一致性。进一步阅读可参考仓库内讲义原文 index.md德语版、中文版以及配套的连续性检查清单与模拟器源码。相关实战项目为 project-03 多会话连续性。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考