【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本技术指南以 learn-harness-engineering 仓库中《講義 05. セッションをまたいでコンテキストを保つ》为核心深入剖析 AI 编码代理在跨会话长任务中失忆的根本原因——上下文窗口有限、早期收敛、状态漂移——并给出以连续性工件continuity artifacts为核心的系统化解决方案。读完本文你将掌握 PROGRESS.md / DECISIONS.md / Git 检查点 / init.sh 这四件套的落地写法理解压缩 vs 重置的取舍并能通过仓库自带的会话模拟器与 Project 03 实战项目验证效果。问题长任务为什么必然丢失连续性向 Claude Code 这样的编码代理下达一个完整功能实现任务它运行 30 分钟后接近完成但上下文即将耗尽。你开启一个新会话让它继续——结果它不记得之前做过哪些决策、为什么选方案 A 而不选方案 B、哪些文件已被修改、测试处于什么状态。它花 15 分钟重新探索项目甚至可能做出与上一轮自相矛盾的选择。这就像一个每天醒来就失忆的工匠需要重新熟悉整个工地——哪面墙砌了一半、为什么选了红砖而不是蓝砖、管道铺到哪了。更糟的是它可能因为不记得昨天已装好窗户而把它拆掉重来。该讲义的核心判断是这不是模型缺陷而是客观现实。上下文窗口是有限资源且窗口内信息的增长速度远快于窗口本身的扩张——即使窗口涨到 1M token复杂任务依然会用尽因为代理不仅要生成代码还要理解代码库、追踪自身决策历史、处理工具输出、维持对话上下文。更深层的问题是信息重要度不均匀中间推理步骤包含决策的为什么——为什么选 A 不选 B、为什么用这个库不用那个库、为什么跳过某项优化最终输出只包含做了什么——即代码本身。压缩策略通常保留后者、丢失前者。下一个会话能看到代码却不知道代码为何这样写于是可能把有意的设计决策当成可优化项优化掉。此外Anthropic 在长时运行代理研究中观察到上下文焦虑context anxiety代理感到上下文所剩不多时会表现出早期收敛行为——仓促收尾当前工作、跳过验证步骤、选择比最优解更简单的方案如同考试快结束时给选择题乱填答案。会话连续性流程有工件与无工件的对比没有连续性工件时每个新会话都是一场灾难有了连续性工件新会话可以立即恢复核心概念一览上下文窗口有限无论标称多大128K、200K、1M长任务终会用尽。用尽后只能压缩丢信息或重置开新会话两者都有代价。连续性工件让新会话能明确接续上次会话的持久化状态文件基本形态是进度日志 验证记录 下一步动作——就是那位失忆工匠的日记。重建成本rebuild cost新会话达到可执行状态所需的时间。好的 harness 能把重建成本从 15 分钟压缩到 3 分钟。漂移drift代理的理解与代码仓库真实状态之间的偏差。每个会话边界都会产生漂移不加以控制就会复利式累积。上下文焦虑Anthropic 观察到的现象——代理感知到上下文受限时表现出早期收敛为规避信息损失而提前结束任务属于非理性的资源焦虑。压缩 vs 重置压缩在同一会话内摘要上下文保留做了什么可能丢失为什么重置则开启新会话、从持久化状态重建干净但依赖工件完整性。连续性被破坏时会发生什么重复决策上一会话花大量上下文预算分析三种方案后选定 B本会话的代理不知道这次分析基于不完整信息可能重选 A。就像失忆工匠今天觉得蓝砖更好看推倒昨天的墙重砌。重复劳动代理不确定某工作是否已完成于是再做一遍更糟的是做了一半才发现与既有实现冲突推倒重来。没有进度记录新团队根本不知道已经有人在这面墙上施工。需求漂移跨越多会话后实现方向在不知不觉中偏离原始需求。每个新会话对项目目标的理解都略有不同如同传话游戏十个人传下来帮我买咖啡可能变成帮我买台咖啡机。验证缺口上一会话的验证结果哪些测试过、哪些失败、为何失败没有记录新会话为理解当前状态必须重跑全部验证每次都从零开始重新诊断每次都浪费宝贵上下文。OpenAI 与 Anthropic 的官方文档都强调结构化状态持久化OpenAI 的 harness engineering 文章把仓库视为运维记录system of record所有操作结果都应在仓库留下可追溯证据Anthropic 的长时运行代理文档则明确推荐handoff 文件——包含当前状态、已知问题、下一步动作的结构化文档。失忆工匠的日记四大连续性工具核心方法论一句话把代理当作一位失忆的优秀工程师来对待。它在下班前必须把关键信息写下来让下一班次的代理能立即接手。工具 1进度文件PROGRESS.md最基本的连续性工件日记的核心。注意其固定结构当前状态commit 哈希、测试通过率、已完成、进行中、已知问题、下一步# Project Progress ## Current State - Latest commit: abc1234 (feat: add user preferences endpoint) - Test status: 42/43 passing (test_pagination_edge_case failing) - Lint: passing ## Completed - [x] User model and database migration - [x] Basic CRUD endpoints - [x] Auth middleware integration ## In Progress - [ ] Pagination feature (90% - edge case test failing) ## Known Issues - test_pagination_edge_case returns 500 on empty result sets - Need to confirm whether deleted users should appear in listings ## Next Steps 1. Fix pagination edge case bug 2. Add include deleted users query parameter 3. Update API documentation工具 2决策日志DECISIONS.md记录重要设计决策及其理由。不需要详尽设计文档——只要决定了什么、为什么、什么时候像日记里的便签# Design Decisions ## 2024-01-15: Use Redis for user preferences caching - Reason: High read frequency (every API call), small data size - Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile) - Constraint: Cache TTL of 5 minutes, active invalidation on write工具 3Git 提交作为检查点每完成一个原子工作单元就提交一次提交信息写明做了什么和为什么。提交是免费、自动版本化的状态快照——它精确记录了仓库在某时刻的状态供新会话恢复。工具 4init.sh 或 harness 初始化流程在 AGENTS.md 中指定上班与下班例行程序## At session start (clock in) 1. Read PROGRESS.md for current state 2. Read DECISIONS.md for important decisions 3. Run make check to confirm repo is in consistent state 4. Continue from PROGRESS.md Next Steps section ## Before session end (clock out) 1. Update PROGRESS.md 2. Run make check to confirm consistent state 3. Commit all completed work混合策略并非所有任务都需要上下文重置短任务30 分钟以内可在单会话内完成长任务跨会话必须用进度文件与决策日志保证连续性。判断标准当任务预计消耗窗口的 60% 以上时就开始准备 handoff。上下文焦虑压缩 vs 重置的深入取舍Anthropic 2026 年 3 月的研究进一步揭示了上下文焦虑的具体表现Sonnet 4.5 在上下文接近窗口上限时表现出强烈的早期收敛行为。对此有两种应对策略压缩在同一会话内摘要早期对话。优点保持连续性代理仍能看到做了什么缺点摘要常常丢失为什么——为何选 B 不选 A、为何跳过某项优化。更重要的是压缩并不能消除上下文焦虑——代理知道自己上下文曾经很大心理上仍倾向匆忙收尾。上下文重置完全清空上下文开启新会话从持久化工件重建。优点精神清爽新会话没有时间不够的焦虑缺点完全依赖 handoff 工件的完整性——日记缺了关键信息新会话就可能把时间浪费在错误方向上。Anthropic 的实际数据表明Sonnet 4.5 的上下文焦虑严重仅靠压缩不够上下文重置成为 harness 设计的重要组件而 Opus 4.5 该行为显著减少可主要依赖压缩管理上下文。这推导出关键结论harness 设计必须针对目标模型具体定制不存在万能模板。讲义出处注明Anthropic Harness design for long-running application development 与 Effective Harnesses for Long-Running Agents 研究具体结论以模型实际行为为准。仓库实证会话模拟器与 handoff 模板讲义配套的 code 目录提供了可直接运行和对照的素材见 code 目录session-simulator.ts量化对比有无 handoff 的差异session-simulator.ts 用 6 个带耗时的任务步骤模拟两个会话Run 1无 handoffSession A 完成步骤 1–3 后超时Session B 无上下文从步骤 1 重新开始重复完成 1–3duplicatedSteps 3多耗 190ms 的重复劳动Run 2有 handoffSession A 完成 1–3 并写 handoff 文件Session B 读取后从步骤 4 继续duplicatedSteps 0。运行方式注意以仓库根目录为基准npx tsx docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts输出包含两个 Run 的完整步骤日志与对比表Session A/B 完成步骤数、重复步骤数、总工作量、handoff 节省的时间是演示handoff 消除重复工作、保障跨会话连续性的最直观证据。session-handoff.md 与 continuity-checklist.mdcode/session-handoff.md 给出一个真实形态的 handoff 示例只有三块已完成、损坏或未验证、下一步最优步骤——例如.md导入成功但大.txt文件失败应用能启动但详情视图未接上下一步则是修复.txt导入路径 → 端到端验证导入 → 添加文档详情面板。这正是讲义中四字段模板的落地变体。code/continuity-checklist.md 提供会话开始时的自检四问新代理能否在 5 分钟内定位近期工作当前稳定的启动路径是否已文档化未完成工作是否被明确标识不读旧聊天记录能否看到下一个最优任务实战项目佐证Project 03 的多会话连续性讲义指向 Project 03: Multi-Session Continuity在英文版讲义中作为配套实践项目日文版讲义同样引用该项目。该项目的 solution 目录把讲义理论全部实例化solution/session-handoff.md 是真实填写完成的 handoff记录 Last Session 日期、What Was Accomplished元数据抽取、文档分块、索引状态 UI、带引用的 grounded QA 四项功能及实现细节、What Remains、Decisions Made为何在导入时抽取元数据而非惰性抽取、为何按段落感知切分、Files Modified列出src/services/indexing-service.ts、src/renderer/components/StatusBar.tsx等具体文件、BlockersNone、Next Steps进入 Project 04——与讲义做了什么 / 为什么 / 下一步完全对应。solution/AGENTS.md 实现了讲义中的上班例行程序启动时按顺序读 AGENTS.md → 读架构与产品文档 →npm install npm run check验证构建 → 读 feature_list.json 查看功能状态并规定一次只做一个功能纪律one-feature-at-a-time policy选一个 not-started 功能 → 只实现它 → 验证 → 更新 feature_list.json 为 pass 并附证据 → 提交提交信息引用功能 ID→ 才进入下一个。这正对应讲义下班前更新进度文件 确认一致状态 提交全部已完成工作的检查点思想。solution/clean-state-checklist.md 是讲义验证记录的扩展构建验证npm run check零 TypeScript 错误、npm run build产出 dist/、功能验证逐条勾选窗口、导入、元数据、分块、索引状态、引用回答、持久化等、范围控制验证feature_list.json 全 pass、无 fail/not-started、代码质量与文档验证session-handoff.md 已填写、claude-progress.md 有会话日志。该项目的真实运行数据也印证讲义核心论点跨 5 个会话的实现任务靠 session-handoff.md 把会话 2 的重建成本降到约 3 分钟最终 11 个功能全部 pass。实例对比有日记与没日记的 5 个会话讲义用一个用户认证博客系统12 个功能点、预计 5 个会话的实例做量化对比无日记基线会话 1 实现用户模型与基础路由会话 2 代理不记得认证中间件的接口契约花约 15 分钟猜测上一轮设计意图到会话 3 漂移累积代理开始重实现已完成功能到会话 5仓库里大量冗余代码核心认证功能仍未通过端到端测试——12 个功能点只完成 7 个其中 3 个还有隐藏正确性问题。像从不写日记的工匠第 5 天工地上乱成一团有的墙砌了两遍该砌的墙还没动工。有日记使用进度文件、决策日志、验证记录与 Git 检查点每个会话结束自动更新状态报告会话 2 的重建成本降到约 3 分钟到会话 512 个功能点全部完成并验证。量化对比重建时间减少约 78%功能完成率从 58% 提升到 100%隐藏缺陷率从 43% 降到 8%。工匠依然失忆但有了日记每天从昨天停下的地方继续而不是从零开始。关键要点上下文窗口是有限资源长任务必然跨会话会话必然丢失信息——像每天遗忘的工匠这是客观现实。解决方案不是更大的窗口而是更好的状态持久化进度文件 决策日志 Git 检查点给失忆工匠一本可靠的日记。把代理当作失忆的工程师对待下班前写清做了什么、为什么、下一步做什么。重建成本是核心指标好的 harness 应让新会话在 3 分钟内进入可执行状态。采用混合策略短任务在会话内完成长任务用结构化工件保障连续性。练习测量连续性损失选一个需要 3 个以上会话的开发任务。不提供任何连续性工件记录每个会话开始时代理花多少上下文搞清上次发生了什么每个会话结束后创建进度文件并让下一会话从它开始比较有无进度文件的重建成本。设计 handoff 模板设计包含四个字段的最小 handoff 模板——仓库状态commit 哈希、运行状态测试通过率、阻塞项、下一步动作。让一个全新代理会话仅凭该模板恢复项目状态记录恢复中遇到的歧义并迭代改进模板可参考 code/session-handoff.md 的形态。混合策略实验在 5 会话的开发任务中比较三种策略(a) 每次都开新会话 进度文件(b) 单会话内尽量多做上下文压缩(c) 混合策略短任务会话内完成、长任务跨会话 进度文件。对比重建时间、功能完成率与决策一致性。进一步探索完整讲义见 日语版 Lecture 05配套实践项目见 Project 03其 solution 目录 中的 session-handoff.md、AGENTS.md 与 clean-state-checklist.md 是可直接对照学习的完整 harness 工件样例。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性 本篇技术指南以 learLearn Harness Engineering用 Session Handoff 文档修复长任务的跨会话连续性Learn Harness Engineering用 Session Handoff 文档修复长任务的跨会话连续性 导读在 Learn Harness En长任务连续性丢失与 harness 状态持久化用 PROGRESS.md、DECISIONS.md 与 Git 检查点让 Agent 跨会话无缝续作长任务连续性丢失与 harness 状态持久化用 PROGRESS.md、DECISIONS.md 与 Git 检查点让 Agent 跨会话无缝续作 导读 本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考