用交接笔记让编程代理接续上次工作
编程代理在新会话、切换工具或压缩长对话后,容易丢失约束和调试进展。作者用交接笔记记录已做决定、失败尝试和当前阻塞,让后续会话接着推进。
AI 深度解读
昨天已经否决的重写方案,今天 Coding Agent 又提了一遍;上次修复弄坏了两个测试,新会话却毫不知情。作者想解决的,是跨会话反复解释任务状态的成本:把目标、决策、验证结果和下一步写成短交接文件,再绑定一份 Git 快照,帮助判断这份记录是否还适用。
这个叫 Handoff Kit 的原型没有给 Agent 增加自动记忆。它提供的是一种更容易检查的交接方式。对持续数周、经常切换会话或工具的开发任务,这个思路值得看,尤其是它对「记录可信」的处理及其边界。
为什么聊天记录和 AGENTS.md 接不住任务状态
作者把 Agent 的失忆分成三类:会话结束后,积累的信息留在旧聊天里;长会话被压缩后,约束可能丢失;切换工具后,新工具能看到代码,却看不到之前的讨论。
代码能告诉 Agent 当前实现是什么,却未必能解释为什么走到这里。例如,昨天团队决定放弃重写,尝试过直接修复,结果弄坏两个测试,最后被不稳定的 CI 任务卡住。这些信息决定了下一步该做什么,但通常没有完整留在代码里。
聊天历史虽然保留了过程,查找成本却很高。作者举的例子是,真正重要的 3 个决策,可能埋在 40 次工具调用之间。历史还可能被压缩、截断,或者无法随工具、机器迁移。
CLAUDE.md / AGENTS.md 更适合放长期规则,例如构建方式、代码风格和禁止修改的区域。「支付 webhook 返回 200,却没有执行任何操作」则是短期任务状态,可能只持续两天。
长期规则和临时任务状态,应该分开维护。
作者还提到,有研究发现 Agent 会优先遵循过时的指令文件。但原文没有提供研究出处、实验条件或具体比例,这个论据不能直接当作已核实结论。即使不依赖它,频繁变化的阻塞信息也确实容易让规则文件失去时效。
普通笔记已经接近答案。作者遇到的最后一个问题是:三天后重新打开笔记,无法确定它是否仍然描述眼前这份代码。
交接文件怎样判断自己是否过期
Handoff Kit 把一份短交接记录与 Git 快照放在一起。记录包含目标、已做决策、运行过的检查、当前阻塞,以及一个明确的下一步;快照则保存当时的分支、commit 和已修改路径。
交接文件可以导出为 Markdown 或 JSON,放进仓库、跟随分支流转,或者交给另一个人、另一个 Agent 会话。
配套 CLI capture.py 负责生成快照,也能把保存的快照与当前检出状态比较,输出 CURRENT 或 STALE。按作者的描述,同一 commit、相同已修改路径会被视为仍然适用;分支状态发生变化时,则提醒使用者先读 diff,再决定是否信任记录。
新会话的流程因此很短:检查交接状态,阅读交接内容,再粘贴给 Agent,或让它读取文件。Agent 从已有决策和失败尝试继续工作。
这套工具的能力边界也很明确:
- Web UI 是静态页面,草稿保存在浏览器 local storage,没有后端、账号或同步。
- 没有内置 AI,不自动总结,也没有模型或 API 调用,交接内容由人编写。
- CLI 只读取 Git 元数据,不读取源码内容、环境变量或聊天记录。
- 没有平台集成,不会捕获 Claude Code 或 Cursor 的聊天。
它还是早期原型,采用 MIT 许可证;CLI 要求 Python 3.9+,作者称无需额外安装依赖。
我的判断
我认同它把「任务记忆」做成独立文件的方向。相比翻完整聊天,结构化记录更容易找到有效信息;相比把所有东西塞进 AGENTS.md,它也更容易单独更新、归档或删除。
但最需要打问号的,恰恰是 CURRENT。
Git 快照一致,只能提供有限的状态线索,不能保证交接内容正确。
根据原文列出的字段推断,同一 commit 下,即使已修改路径没有变化,文件内容仍然可能继续变化。原文没有说明是否记录了工作区内容哈希或其他校验信息,因此不能把 CURRENT 理解成逐字验证通过。CI 故障、外部接口状态、需求变化,也可能让笔记失效,而 Git 元数据完全没动。
STALE 则适合当作检查提醒。代码有变化,并不代表交接里的每个决策都已失效,仍然需要结合 diff 判断。
作者说这套办法解决了自己不信任旧笔记的问题,但没有提供节省 token、减少重复错误或缩短任务时间的对照数据。目前它是个人工作流经验,还不能证明比团队现有的 issue、PR 描述或任务文档更有效。
代价也摆在眼前:需要人持续写、持续更新。自动摘要更省手工整理,人工交接更方便筛选关键决策,两者如何取舍,原文没有比较。