交接文档：跨会话的智能体记忆
2026年3月21日，在一次缓存清除暴露出性能瓶颈后，我的生产站点开始出现14秒的页面加载时间。我在两个会话中调查根本原因，定位了缓慢的代码路径，起草了修复方案，并将所有内容记录在一份交接文档中。
交接文档将诊断跨越会话边界传递，使实施智能体继承已修正的理解，而不必重新推导出相同的错误结论。与仅说明”要做什么”的工单不同，交接文档记录了尝试过什么、错在哪里，以及先前的方法为何失败。市场页面的交接文档在四天内经历了三次修正，最终指导了一项将页面加载从14秒缩短至108毫秒的实施工作。
该交接文档的第一版是错的。它瞄准了错误的代码路径。一次代码审查发现，被测量到缓慢的页面是由market_hub()提供服务的，而非交接文档所假设的_fetch_market_data()。于是交接文档被修订。
第二版提议为Apple Maps和层级计数添加不必要的HTMX局部视图。审查指出，Apple Maps在本地对URL进行签名（没有可延迟的出站请求），而层级计数应该来自单次聚合查询。交接文档再次被修订。
第三版提议将天气端点改为异步，却没有指明现有的同步HTTP客户端即便在HTMX背后仍会阻塞事件循环。交接文档第三次被修订。
四天后，另一个会话读取了这份经过三次修订的交接文档并实施了修复。Austin从14,290毫秒降至108毫秒。实施瞄准了正确的代码路径，采用了正确的查询方式，并跳过了那些不必要的HTMX局部视图。三次审查中的每一项修正都已被纳入。
这份交接文档跨越四天和多个会话，承载着一份诊断。没有它，实施会话将从头开始，做出相同的错误假设，提出相同的不必要优化，并需要相同的修正。交接文档将四天的调查压缩进了一份文档，实施智能体能在数秒内读完。这就是将上下文窗口管理应用于一个具体问题：如何在跨越会话边界时传递诊断，而不丢失那些使其准确的修正。
交接文档包含什么
交接文档不是工单。工单说明要做什么。交接文档说明尝试了什么、学到了什么、错在哪里、接下来要做什么。差别在于机构记忆。
市场页面的交接文档包含：
诊断。六个市场页面的冷渲染TTFB测量数据，从381毫秒（东京，小市场）到14,290毫秒（Austin，500多家公司）不等。测量结果证明该问题随公司数量扩增，这将瓶颈指向了查询形式。
按优先级排列的根本原因。四个按影响排序的根本原因：查询形式（主要）、阻塞性的天气API（次要）、在另一条代码路径上的全表扫描（第三），以及缺失的缓存头（已部分解决）。每个根本原因都附有文件路径、行号以及导致性能下降的具体代码模式。
走过的弯路。第一版瞄准的是_fetch_market_data()而非market_hub()。交接文档记录了这一错误及其修正，以便实施会话不会重新推导出同样的错误结论。文档也记录了被舍弃的HTMX局部视图及舍弃原因：Apple Maps没有出站请求，层级计数应归入聚合查询。
实施计划。五个步骤，附带SQL示例、验收标准和验证说明。步骤1：用数据库查询替换Python端分页。步骤2：添加带异步客户端的HTMX天气局部视图。步骤3：缓存次要代码路径。步骤4：添加边缘缓存头。步骤5：重新测量相同的六个URL。
上下文窗口管理一文解释了为何这种细致程度至关重要：交接文档中的每一处模糊之处，都是实施智能体必须重新推导的决策，既消耗上下文预算，又冒着得出同样错误结论的风险。
上下文陷阱。共享的模板上下文包含一个针对每个页面的已鉴权金币余额查询，即使某些页面从不渲染它。交接文档将此标记为缓存正确性问题：s-maxage在缺少适当的Vary头时，可能向匿名用户提供陈旧的认证数据。
工单为什么失败
针对同样工作的工单会说：”市场页面很慢。优化市场中心查询。”实施会话将需要：
- 发现哪条代码路径为市场页面提供服务（不读路由器就不明显）
- 剖析该代码路径以找出瓶颈
- 考虑各种优化方案
- 实施其中之一
- 发现该方案有副作用（与认证数据相关的缓存正确性问题）
- 修订方案
步骤1-3在调查会话中已经完成。交接文档将这些工作传递下去。工单则将其丢弃。
失败模式并非懒惰。失败模式是跨越会话边界时的上下文丢失。AI智能体会话从一个干净的上下文窗口开始。它不记得上一个会话发现了什么。这与上下文即架构在系统层面所论述的是同一个问题：你放入上下文窗口的内容决定了输出的质量。工单提供目标。交接文档提供目标加上正确达成它所需的已积累理解。
修订历史至关重要
交接文档的修订历史与其当前内容同样重要。市场页面交接文档记录了三次修订，附有时间戳和原因：
- 捕获：2026-03-21T17:24（初次调查）
- 修订：2026-03-21T18:20（代码审查修正：错误的代码路径、不必要的HTMX）
- 修订：2026-03-25T06:30（实施完成，查询修复已部署）
修订历史告诉实施会话：”这份诊断曾被挑战并修正。当前版本已纳入这些修正。”一份未经修订的交接文档可能是错的。一份经过三次修订的交接文档则已经过压力测试。
走过的弯路也是价值的一部分。一份写着”我们考虑并否决了/_mapHTMX，因为Apple Maps在本地签名URL”的交接文档，可以免去实施会话提出同样的优化、被审查、再被否决的过程。交接文档将否决前置了。
什么时候写交接文档
并非每项任务都需要交接文档。一次会话就能完成的缺陷修复无需跨会话持久化。交接文档的价值体现在以下情形：
调查成本高昂时。剖析性能瓶颈、追查安全漏洞、调试多系统交互。如果调查耗费了大量精力，交接文档就保留了这些精力。
实施将在不同会话中进行时。如果今天完成调查但明天才实施，交接文档可以弥合这段间隔。没有它，明天的会话将从零开始。
诊断并非显而易见时。如果正确的修复方案需要理解为何三个看似合理的替代方案是错的，交接文档就捕获了这种理解。复合上下文系统说明了交接文档如何融入更广泛的项目知识积累。一份只写着”修复查询”的工单并不能解释为何该查询需要某种特定的修复。
多人（或多个智能体）可能参与时。交接文档是一份共享理解文档。任何读到它的会话都继承了完整的调查上下文。
交接文档作为复合上下文
交接文档是对复合上下文系统的一笔存入。每份交接文档都捕捉了诊断时间，并将其转化为可复用的成果。实施会话以近乎零成本提取该诊断。
随着时间推移，交接文档会积累为一份调查史。市场页面的交接文档引用了缓存清除事件、nightcheck测量、破坏性API守卫和代码审查系统。其中每一项本身都是先前会话的产物。交接文档将它们串联成一段新会话可以循迹而行的叙事。
交接文档并不取代理解。实施会话仍需阅读代码、编写修复、验证结果。交接文档取代的是重新发现。会话无需再去发现已知的内容。Ralph智能体架构将交接文档用作其通宵执行循环的主要跨会话持久化机制。AI工程中心记录了交接文档如何融入由钩子、技能和记忆系统构成的更广泛基础设施之中,使智能体辅助开发能随时间复利累积。
常见问题
交接文档应该多长？
足够长，以涵盖诊断、走过的弯路和实施计划。又足够短，使智能体能在一次上下文加载中读完。市场页面的交接文档有103行。大多数交接文档在50到150行之间。
交接文档存放在哪里？
存放在项目的记忆目录中：~/.claude/projects/{project}/memory/handoff-{topic}.md。记忆系统会根据前置元数据的描述加载相关文件，因此交接文档对未来会话而言可被发现，无需显式引用。
交接文档会取代文档吗？
不会。文档描述系统如何工作。交接文档描述围绕某一具体问题所学到的内容以及应对之策。文档是永久性的。交接文档则由实施会话消费，之后便成为历史上下文。
如果交接文档过时了怎么办？
交接文档的状态字段会追踪这一点。活跃的交接文档被标记为PLANNED或IN PROGRESS。已完成的交接文档被标记为RESOLVED，并附上实施提交的哈希。过时的交接文档作为历史上下文可见，但不再可执行。
来源
本文参考了市场页面性能交接文档（handoff-market-page-perf.md），该文档指导了2026年3月25日部署的查询形式修复。这份交接文档在四天内经历了三轮修订周期，并指引了一项实现了132倍性能提升的实施工作。在复合上下文一文中有所引用。