跨会话任务为何“断片”：用 PROGRESS.md 与 handoff 工件为 AI Agent 建立连续性 harness

跨会话任务为何“断片”用 PROGRESS.md 与 handoff 工件为 AI Agent 建立连续性 harness【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering导读本文基于 learn-harness-engineering 仓库《第五讲让跨会话的任务保持上下文连续》展开。核心回答一个问题——为什么 AI 编码 Agent 在长任务中会“失忆”、重复劳动甚至推翻自己此前的设计决策以及如何用 PROGRESS.md、DECISIONS.md、Git 检查点与交接handoff程序四类连续性工件把新会话的恢复成本从十几分钟压缩到几分钟。读完你将掌握一套可直接落地的多会话连续性 harness 设计方法并能借助仓库自带的会话模拟器量化验证其收益。上下文窗口不是无限的上下文窗口是有限资源而且这不是换个更大窗口的模型就能解决的问题。即便窗口增长到 1M tokens复杂任务依然会把它耗尽——因为 Agent 不只是生成代码它同时还要阅读和理解代码库跟踪自己做出过的决策历史处理工具输出编译错误、测试日志、lint 结果维护与用户对话的上下文。这些信息加在一起增长速度远超窗口扩容速度。所以“窗口再大一点”不是解决方案只是延迟问题爆发的时间点。更深层的问题在于Agent 产出的信息重要性并不均等。中间推理步骤里藏着决策的“为什么”——为什么选方案 B 而不是 A、为什么用这个库而不是那个、为什么跳过某项优化而最终产出只包含“是什么”——即最终代码。上下文压缩compaction策略通常保留后者、丢掉前者于是下一个会话看到代码却不知道代码为什么长成这样很可能把一个有意的设计决策当作冗余“优化”掉。Anthropic 在长运行 Agent 研究中还观察到一种行为当 Agent 感知到上下文接近上限时会表现出“赶工收尾”premature convergence——匆忙结束当前工作、跳过验证步骤、选择简单方案而非最优方案。Anthropic 将其命名为“上下文焦虑”context anxiety类比考试快结束时考生开始胡乱猜答案。会话连续性流程有无工件的天壤之别没有连续性工件continuity artifacts时每个新会话都是一场灾难仓库文档用如下流程图概括有了连续性工件新会话能快速接上上次的工作关键概念概念含义上下文窗口有限无论标称多大128K、200K、1M长任务迟早耗尽耗尽后要么压缩有损要么重置开新会话两者都会丢失信息连续性工件保存的状态文件让新会话能无歧义地从上一会话的停点继续。基本形态进度日志 验证记录 下一步动作恢复成本新会话进入可工作状态所需时间。好的 harness 能把它从 15 分钟压到 3 分钟漂移driftAgent 的理解与仓库真实状态之间的落差。每次会话边界都会引入漂移不加控制会持续累积上下文焦虑Anthropic 观察到的现象Agent 在感知到上下文临近上限时提前收敛过早收尾任务以避免信息丢失本质是一种非理性的资源焦虑压缩 vs 重置压缩在会话内摘要上下文保住“是什么”可能丢“为什么”重置开启新会话并从保存状态恢复干净但依赖工件完整性连续性被破坏时会发生什么仓库文档列举了四种典型故障模式推翻既定决策上一会话花了大量上下文分析三个方案并选定 B新会话对此毫不知情可能在信息不全的情况下重新决策、改选 A——如同失忆的工匠今天看蓝色砖更顺眼就把昨天砌好的红砖墙拆了重砌。重复劳动Agent 不确定某项工作是否已完成于是再做一遍更糟的是做一半发现与现有实现冲突被迫返工。需求漂移跨多个会话后实现方向悄悄偏离原始需求。每个新会话对项目目标的理解都有细微差异如同“传话游戏”十轮之后“买杯咖啡”可能变成“买台咖啡机”。验证空窗上一会话的验证结果哪些测试通过、哪些失败、为何失败没有记录新会话只能重跑全部验证才能判断当前状态每个会话都从零开始诊断反复消耗宝贵上下文。正因如此OpenAI 与 Anthropic 的官方文档都强调结构化状态保存的重要性OpenAI 的 harness engineering 文章将仓库视为“操作日志”要求每次操作的结果都在仓库中留下可追踪痕迹Anthropic 的 long-running Agent 文档则明确推荐使用“handoff 文件”——包含当前状态、已知问题与下一步动作的结构化文档。给失忆的工匠一本日志四类连续性工具核心思路是把 Agent 当作一位天才但健忘的工程师下班前必须把关键信息写下来让下一班的人能快速接手。工具一进度文件 PROGRESS.md这是最基础的连续性工件是日志的核心。仓库文档给出的模板# 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注意四个区块的职责分工Current State给出可验证的客观基线commit hash、测试通过率、lint 状态Completed用勾选框记录已交付成果In Progress标注未完成事项及其百分比和阻塞点Next Steps给出下一个会话无需思考即可执行的动作列表。工具二决策日志 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这条模板的精妙之处在于它同时记录了被否决的备选方案——这正是压缩最容易丢失的“为什么”信息。有了它新会话不会再花 15 分钟重新论证一遍已经被否决的 PostgreSQL 方案。工具三Git 提交作为检查点每完成一个原子工作单元就提交一次提交信息说明“做了什么、为什么”。这是免费的、自动版本化的状态快照既是恢复的精确坐标也是验证记录的一部分。配合 PROGRESS.md 中的Latest commit字段新会话能立刻定位到仓库的准确状态。工具四AGENTS.md 中的交接程序在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。上下文焦虑压缩与重置的取舍Anthropic 2026 年 3 月的研究揭示了上下文焦虑的具体表现在 Sonnet 4.5 上当上下文接近窗口上限时Agent 表现出明显的“过早收敛”行为。应对它有两种策略各有取舍压缩Compaction在同一会话内摘要早期对话。优点是保持连续性、Agent 能看到“是什么”缺点是“为什么”常在摘要中丢失而且压缩无法消除上下文焦虑——Agent 知道上下文曾经很大心理上仍会急于收尾。上下文重置Context Reset清空上下文、开新会话、从保存的工件恢复。优点是心智状态干净——新会话没有“时间快用完”的焦虑缺点是完全依赖 handoff 工件的完整性日志里缺了关键信息新会话就可能走错方向。关键结论来自 Anthropic 的真实数据对 Sonnet 4.5上下文焦虑严重到仅靠压缩不够上下文重置必须成为 harness 设计的组成部分但对 Opus 4.5该行为明显减弱压缩即可管理上下文、无需依赖重置。这意味着harness 设计必须针对具体目标模型定制而不是套用通用模板。仓库配套会话模拟器与连续性检查清单本讲在仓库中自带可直接运行的工具化验证位于 docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts模拟两轮多步骤任务。第一轮无 handoff 文件——会话 B 从零开始重复完成会话 A 已做的步骤 1–3第二轮有 handoff 文件——会话 B 从步骤 4 继续零重复。脚本最后输出对比表完成步骤数、重复步骤数、总耗时、handoff 节省时间可直接用npx tsx运行验证。continuity-checklist.md四个自检问题——“新 Agent 能否在 5 分钟内确定最近的工作当前稳定启动路径是否已记录未完成工作是否清晰标注不读旧聊天记录能否看到下一个最佳任务”——任何会话结束时都可用它快速自检。session-handoff.md最简交接模板只含三节Сделано已完成、Сломано или не проверено损坏或未验证、Следующий лучший шаг下一个最佳步骤示范了如何在两行内说清“断点在哪、风险在哪、下一步干嘛”。实战案例Project 03 的连续性 harness仓库的 Project 03: Multi-Session Continuity with Scope Control 是本节理论的完整落地样例对应文档 docs/ru/projects/project-03-multi-session-continuity/index.md。其 starter 与 solution 的区别正是“有无连续性 harness”的区别solution/AGENTS.md的Session Handoff一节明确要求恢复工作时先读session-handoff.md结束会话时更新它记录完成事项、剩余事项、阻塞点/决策、修改过的文件。这与本讲“接班/交班”程序一一对应。solution/session-handoff.md是真实项目的交接产物按What Was Accomplished / What Remains / Decisions Made / Files Modified / Blockers / Next Steps六个维度记录其中Decisions Made记录了诸如“元数据在导入时提取而非惰性提取”“分块采用段落感知切分以避免拆句”等决策——这正是 DECISIONS.md 思想的工程化体现。solution/claude-progress.md是逐会话日志例如会话 1 按“metadata-extraction → document-chunking → indexing-status-ui → grounded-qa”顺序逐特性实现每个特性都记录“改了什么文件、如何验证、feature_list.json 状态”构成可审计的完整轨迹。solution/clean-state-checklist.md与文档中“验证记录”对应把构建、特性、范围控制、代码质量、文档五类检查项全部勾选化。值得注意的还有 solution/AGENTS.md 中的One-Feature-at-a-Time Policy一次只实现一个特性、实现后验证、更新 feature_list.json、提交、再继续——它与本文主题同源在会话边界之外任务边界也是信息丢失的高发区把大任务切成可验证的小原子单元正是降低跨边界漂移的有效手段。现实数据有日志与没日志的差距仓库文档给出一个可复现的对比案例让 Agent 实现带用户认证的博客系统共 12 个特性、预计 5 个会话。无日志基线会话 1 完成用户模型与基础路由会话 2 因不记得 auth-middleware 的接口契约花约 15 分钟重建设计意图到会话 3累积漂移导致 Agent 开始重做已完成特性会话 5 结束时仓库里充满冗余代码而关键认证特性仍未通过端到端测试。最终仅完成 7/12 特性其中 3 个存在隐藏正确性问题。有日志使用进度文件、决策日志、验证记录与 Git 检查点每会话结束自动更新状态报告。会话 2 的恢复成本降至约 3 分钟会话 5 结束时 12 个特性全部完成并通过验证。量化对比恢复时间下降约78%特性完成率从58% 提升到 100%隐藏缺陷率从43% 降至 8%。工匠依然健忘但有了日志每一天都从昨天的停点开始而不是从零开始。主要结论上下文窗口是有限资源长任务必然跨多个会话会话之间必然丢失信息——这是客观现实不是 bug。解法不在更大的窗口而在更好的状态保存进度文件 决策日志 Git 检查点就是给失忆工匠一本可靠的日志。把 Agent 当作健忘的工程师下班前记录“做了什么、为什么、下一步做什么”。恢复成本是核心指标好的 harness 应让新会话在 3 分钟内进入可工作状态。采用混合策略短任务在单会话内完成长任务通过结构化连续性工件跨会话推进。练习建议测量连续性损失选一个至少需要 3 个会话的开发任务。无连续性工件时在每会话开始时记录 Agent 花多少上下文“理解上次做了什么”会话结束创建进度文件让下个会话从它继续对比有无进度文件时的恢复成本。设计最小 handoff 模板设计含四个字段的模板——仓库状态commit hash、运行时状态测试通过比例、阻塞项、下一步动作让一个全新会话仅凭模板恢复项目状态记录恢复过程中的歧义并迭代改进模板。混合策略对照实验在 5 会话任务中比较三种策略——(a) 每次新会话 进度文件(b) 单会话内尽量多做上下文压缩(c) 混合策略短任务在会话内、长任务跨会话 进度文件对比恢复时间、特性完成率与决策一致性。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考