跨Session上下文管理实战：用/teach和/handoff让AI Agent不再“失忆”

跨 Session 上下文管理这件事我在 AI 编程助手上面反复折腾了快两个月踩了无数坑才摸清/handoff和/teach这套组合拳的正确姿势。先说结论如果你只把这两个命令当作更高级的复制粘贴那你基本享受不到跨 Session 管理的红利但如果你理解了 Session 隔离的本质和 AI Agent 的上下文依赖这俩命令能直接把你从每次对话都要重新解释一遍项目背景的泥潭里拽出来。这篇文章我会把我从实际项目里摸出来的经验完整拆给你包括什么时候用/handoff、什么时候用/teach、两者怎么配合、交接之后 AI 还在失忆该怎么办以及一些常规文档里根本不会写的避坑细节。1. Session 失忆的本质为什么 AI 总是转头就忘1.1 一个 Session 到底装了什么在聊/handoff和/teach之前我们得先对齐一个基础概念——Session 是什么。很多刚接触 AI 辅助编程的人会把 Session 类比成聊天窗口这个类比没错但不够准确。一个 Session 本质上是从你发起对话到关闭对话之间的完整交互上下文集合。这里面不仅包含你输入的每一条指令还包括 AI 返回的每一段代码、每一次工具调用的结果、每一步文件读写的记录。当这个 Session 还开着的时候AI 可以记得前面聊过的所有内容并根据这些内容连续工作。可一旦 Session 关闭这些记忆就基本清零了——下次你新建一个 SessionAI 就像刚入职的新人对你项目里的一切都一无所知。我在实际使用中最常见的一个场景是上午花三个小时让 AI 把一个订单模块从 REST API 改成消息队列驱动代码写到一半中午电脑合盖下午打开发现 Session 断了。重新起一个 SessionAI 会礼貌地问请问您的项目结构是什么——那一刻我的血压是飙升的。1.2 为什么 Session 不能无限续下去可能有人会问Session 失忆这么麻烦为什么不设计成永远记住所有内容答案在于上下文窗口Context Window是有限的。你可以把上下文窗口理解成一张工作台AI 在处理你当前的请求时需要在台上摆出它认为相关的所有信息代码片段、文件结构、之前的对话记录、工具输出。工作台就这么大东西摆多了最边缘的旧信息就会被挤下去——这就是上下文溢出。上下文溢出有个特别阴险的表现它不会直接报错告诉你我忘了而是会给出看似合理、实则基于过时信息的回答。我有一次让 AI 继续修改一个三天前定义的接口它依然用旧版接口名生成了代码编译直接失败。查日志才发现旧接口名的信息已经被挤出了上下文窗口。所以Session 需要管理不是因为它设计得不合理而是因为有限的上下文窗口决定了一次干不完所有事。跨 Session 上下文管理的核心目标就是在有限的工作台空间里把最重要的信息保留下来并且把它们传递给下一个 Session。1.3 AI Agent 与普通聊天的本质区别顺便说一个很多人的认知误区AI 编程助手不是普通聊天机器人。普通聊天你问一句它答一句上下文丢了顶多多解释两句。但 AI Agent 是会动手干活的——它会自主读文件、改代码、执行命令、处理报错。一旦上下文里丢失了关键信息它不是答错而是做错而且可能在错误的方向上越走越远。这也是为什么跨 Session 管理对 AI Agent 工具特别重要。你面对的是一个自主执行的任务流水线流水线中间的每个环节都在消费上下文。如果你不能在 Session 之间有效传递状态那 Agent 每换一个 Session 就相当于换了一个失忆的执行者所有前期工作都白费。2./handoff与/teach的设计思路拆解2.1 两个命令解决的是完全不同的问题我在刚开始接触这两个命令时以为它们是同类工具只是形式不同。用了一段时间才发现这两个命令面对的是完全相反的痛点。/handoff解决的是Session 之间如何交接进行中的任务。它像一份交接文档把当前进度、已完成的工作、待办事项、注意事项全部打包让下一个 Session 能无缝接续。它的核心场景是任务进行到一半上下文马上要用完了/Session 即将断开。/teach解决的是AI 对项目缺乏长期记忆的问题。它把项目的架构约定、代码风格、关键模块说明、技术选型理由等常识性知识教给 AI让它在任何新 Session 里都能快速理解项目背景。它的核心场景是项目很复杂每次新会话都要花大量时间解释背景。简单总结/handoff管的是活干到哪了/teach管的是这个项目是怎么一回事。一个是短期交接一个是长期教育。2.2 为什么要拆成两个命令而不是一个你可能觉得一个命令不也行吗交接的时候顺便把项目背景讲一遍不就好了。但在实际操作中把两者混在一起非常危险。因为handoff和teach的信息生命周期完全不同。handoff 信息是短暂的——一旦当前任务完成上一份交接文档里的待办事项就全部失效了留着只会污染后续 Session 的上下文。teach 信息是长期的——只要项目还在代码风格、架构决策这些知识就不会过期。如果把两条生命周期不同的信息流混在一个文件里你会发现后面每次开新 SessionAI 读到的都是大杂烩既有过期的待办事项又有仍然有效的架构说明。这些过期信息会占据上下文窗口更糟糕的是它们可能干扰 AI 对现状的判断让它误以为某个早已完成的事情还没完成。所以我现在的习惯是/teach的内容维护在项目的固定文档里长期有效/handoff的内容每次任务前重新生成任务结束就作废。两者各管各的互不干扰。2.3 这套机制的根本优势从信息传递的角度看跨 Session 管理最怕的是信息失真。传统的手动复制粘贴对话记录会把大量无关信息传给下一个 SessionAI 需要从中自行提炼重点效果全看运气。而/handoff和/teach的组合相当于让 AI 自己生成了一份结构化的信息摘要。根据我的实际使用体会一套运作良好的跨 Session 机制带来的收益是新 Session 的启动时间从重新解释半小时缩短到交接文档读完即开工任务连续性大幅提升不会因为 Session 更换而丢失关键决策记录长期项目的代码风格一致性更容易保持因为 AI 始终记得项目的约定3./handoff实操让下一个 Session 无缝接续3.1 什么时机该触发 handoff这是很多人忽略的问题——不是任何时候都适合做 handoff。我试过在任务刚开始十秒钟就生成交接文档结果是文档里的内容几乎为空下一个 Session 看了也白看。也试过在项目改到一半、代码还没跑通时就交接结果接手方基于残缺的现状继续工作输出了大量错误的中间代码。根据我的经验判断是否该做 handoff 的核心标准是当前 Session 是否产生了一个稳定状态。什么算稳定状态代码能编译通过、测试用例能跑通、或者至少有一个明确清晰的当前进度快照——比如接口定义已经完成但是实现还没写完。在这个状态下手写交接文档下一个 Session 才能在一个可靠的基线上继续工作。另外当你明显感觉到 AI 的回答开始打折扣时——比如它开始忽略你们半小时前讨论的约束条件、或者重复问已经确认过的问题——这通常意味着上下文窗口快溢出了。不要等到彻底失忆再做 handoff提前一点因为生成交接文档本身也需要 AI 读取当前上下文如果窗口已经爆炸交接文档的质量也会很惨。3.2 一份高质量 handoff 文档应该包含什么我在大量实践中逐渐总结出了 handoff 文档的黄金结构分享出来供你参考。不管工具的模板怎么变以下几项是我认为必不能少的当前任务一句话描述让接手者瞬间知道现在到底在干什么。这句话要具体比如正在把订单模块的库存扣减逻辑从同步改为异步重试而不是笼统的优化订单模块。已完成的工作清单只列关键里程碑不要事无巨细。我看到很多人喜欢把半天内的每一步操作都写进去这反而会干扰接手者的判断。一份好的已完成清单是让接手者知道哪些事情已经确定可以做完了不用再碰。待办事项与下一步行动这是整个文档的核心价值所在。要说清楚接下来第一步干什么、第二歩干什么以及判断这一步骤完成的验收标准是什么。关键决策与踩坑记录把任务过程中做过的关键选择写下来包括为什么这么选、试过什么方案发现不行。如果不写接手者很可能在同一个坑里再掉一遍。注意事项/约束条件比如不要改动 auth 模块、这个接口有第三方依赖测试时需要 mock 掉——这些通常是你花了大量时间才摸清的隐性知识最值得传递。3.3 手把手演示从一个真实改造任务说起为了让你更直观地理解我拿一个真实任务来演示。假设我们有一个电商后台项目正在把订单导出功能从同步接口改为异步任务。当前的 Session 已经完成了异步任务队列的搭建、导出任务的写入逻辑但任务消费端的邮件通知还没做。这时候 Session 快没上下文了我在对话里输入帮我生成一份 handoff 文档。然后 AI 会生成类似这样的内容【当前任务】 将订单导出功能从同步接口改造为异步任务当前处于任务消费端开发阶段。 【已完成工作】 1. 已完成异步任务队列的搭建使用 Redis 作为消息中间件。 2. 已完成导出任务的写入逻辑接口层通过 task_id 轮询异步获取结果。 3. 已完成导出文件的生成与存储文件保存到本地磁盘 uploads 目录。 【待办事项】 1. 实现任务消费端的邮件通知功能导出完成后发送邮件给用户。 2. 在消费端添加失败重试机制最多重试 3 次每次间隔 5 分钟。 3. 补充异步导出的集成测试。 【关键决策】 - 使用 Redis 而非 RabbitMQ原因是当前项目已有 Redis 依赖引入新中间件成本过高。 - 任务写入时先写 DB 再发消息保证消息不丢失因为曾经出现过 DB 写入后任务未投递的情况。 【注意事项】 - 不要修改 analyze 模块的代码该模块正在被另一个同事重构。 - 消费端重试时注意幂等性邮件服务对重复发送不友好。我拿到这份文档后会简单检查一下看关键信息和我的记忆是否一致。确认无误后关掉当前 Session新建 Session然后把这段内容粘贴进去通常我会用类似 请阅读以下 handoff 文档并继续执行待办事项 的指令开头。3.4 交接后第一步明确接手指令这里有一个很多人的误区——以为把 handoff 文档丢给新 Session 就行了。实际上你还需要一条明确的接手指令。如果只说请基于此文档继续工作AI 可能会只是把文档复述一遍或者等在那问你请问第一步做什么。而如果你说请阅读此 handoff 文档直接开始执行待办事项中的第一项完成后给出下一步建议AI Agent 就能直接进入干活状态。我习惯的接手指令是这样已阅读并理解上述 handoff 文档。 请直接执行待办事项 1实现任务消费端的邮件通知功能。 完成后运行相关测试并把结果告诉我。这个指令非常关键的一步是运行相关测试——它让 AI 在改完代码后有一个验证闭环而不是只把代码写出来就算完事。如果你不强制验证你可能拿到一份看着合理但其实编译不过的代码。4./teach实操让 AI 真正懂你的项目4.1 teach 和 handoff 的分工要拎清我在前面强调过/teach管的是长期知识。什么样的知识算长期我列几个典型的例子项目的技术栈和版本要求后端是 Spring Boot 3.x使用 Java 17项目的模块划分和依赖关系auth 是基础模块所有其他模块都依赖它代码风格与约定统一使用 Lombok 的 Slf4j 打印日志禁止使用 System.out.println特殊的架构决策数据库访问统一走 mapper 层不允许在 service 里直接操作数据源常见的坑改这个模块的配置后必须重启才能生效这些知识有一个共同特征它们在很长时间内不会变而且任何一个新 Session 的 AI 都需要知道它们才能高效工作。如果你每次新开 Session 都要口头解释一遍那/teach就是你的解药。4.2 如何组织一份可复用的 teach 知识库我推荐的做法是单独维护一份项目指南文档专门给 AI 看。你可以把它放在项目根目录命名为如AGENTS.md或.ai-guide.md之类的固定文件。不要把它往 README 里塞——README 是给人看的给 AI 看的文档需要更强的机器可读性。这份项目指南的结构我建议包含以下部分项目概览两三句话说明项目是做什么的、给谁用。技术栈清单列清楚用到的语言、框架、关键依赖版本。目录结构说明按模块说明每个目录的功能边界这对 AI 快速定位代码至关重要。代码规范命名方式、注释规范、日志规范、禁止事项。常用操作命令如何编译、测试、启动、构建。已知注意事项部署限制、环境依赖、历史遗留问题。我自己的写法是每条尽量精简、具体、无歧义。比如不要写代码要优雅而要写新增方法必须包含 Javadoc 注释说明参数、返回值和异常。AI 对模糊指令的执行效果取决于你的描述有多可验证。4.3 用 teach 让 AI 快速进入角色的实操演示继续用上面的电商后台项目举例。假设项目根目录下已经有了一份AGENTS.md内容包含技术栈、目录结构、代码规范等。我要开一个新 Session 来开发订单导出异步化功能开头的指令可以是请先阅读项目根目录下的 AGENTS.md了解项目背景和代码规范。 然后阅读订单模块的代码理解当前的导出逻辑。 一切准备好之后告诉我你的理解和我可以开始提需求了。这段指令的关键在于阅读 AGENTS.md是放在第一位的。我希望 AI 先建立全局认知再去碰具体代码。AI 读完项目指南后通常会给出一个简要的理解反馈比如我已了解该项目是基于 Spring Boot 3 MyBatis Plus 的后台管理系统订单模块位于 order-service 下...。有了这个反馈我就能确认它真的吸收了知识而不是敷衍。如果 AI 理解得不对我会及时纠正然后让它继续。这个确认理解的步骤很重要不要省略。我有一次跳过确认直接提需求结果 AI 把 order-service 的代码当成 user-service 来改整个实现全跑偏了。4.4 teach 的进阶用法按需加载避免上下文浪费很多人担心一个问题/teach的内容如果太长开新 Session 时全量加载会不会又挤占上下文窗口这个担心是合理的。所以我现在的做法是把AGENTS.md分成两个文件一个固定加载一个按需加载。固定加载的文件控制在 50 行以内只包含最核心的信息——项目一句话概览、技术栈清单、目录结构总览、代码规范条例。其他更详细的内容比如具体的模块说明、常见坑位列表放在另一个文件等需要时再让 AI 去读。这个按需加载的思路非常关键。它相当于给你的项目知识做了分级常见知识常驻内存冷门知识按需查询。实际试用下来既能保证 AI 不失忆又不会因为信息过载导致核心任务表现下降。5. 手把手实战跨 Session 完整工作流演示5.1 场景设定从零开始接一个陌生项目为了让你看明白/handoff和/teach组合起来的完整效果我们走一遍完整的工作流。假设你刚入职一家公司接手了一个从未接触过的项目——一个企业内部的数据分析平台。你的第一个任务是增加一个报表定时发送功能。如果没有任何跨 Session 管理你的体验会是第一天开 Session花半天了解项目结构刚准备动手Session 断了。第二天重新开AI 又是一问三不知你哭着又把项目背景讲了一遍。但有了/teach/handoff流程就完全不一样了。5.2 第一步建立项目长期记忆teach你的第一个 Session不对是你工作的第一次对话不应该用来写业务代码而应该用来教学。我给这个阶段的建议是先自己快速浏览项目把关键信息摘录出来然后用对话让 AI 帮你整理成AGENTS.md。比如你可以说我扫了一遍这个项目的代码大概情况是这样吗 1. 后端是 Spring Boot 3 MyBatis Plus前端是 Vue 3。 2. 项目分为 report-service、user-service、gateway 三个模块。 3. 报表模块的代码在 report-service 的 controller/service/mapper 三层目录里。 4. 项目里大量使用 Scheduled 做定时任务没有独立的调度中心。 请帮我整理成一份项目的 AGENTS.md包含技术栈、目录说明、代码规范控制在 50 行以内。AI 会生成一份结构清晰的项目指南你确认无误后保存到项目根目录。这一步投入的时间非常值得它相当于给后续所有 Session 安装了一份项目说明书。5.3 第二步用 teach 开新 Session 进入角色第二天你新建一个 Session 开始做报表定时发送功能。开头先让 AI 读项目指南确认理解然后提出你的具体需求。请先阅读项目根目录下的 AGENTS.md。 然后我要做报表定时发送功能。具体需求 1. 管理员可以配置一个报表每天定时把报表以邮件形式发给指定收件人。 2. 配置页面在报表管理后台里新增一个定时发送页签。 3. 定时任务每天上午 9 点执行扫描配置表把应发送的任务推送出去。 请先给出实现方案包括数据库表改动、后端接口设计、前端页面改动。因为 AI 已经通过 teach 了解了项目背景它这次不会问你你们的项目结构是怎样的而是直接基于 report-service 的现有模式给出方案。比如它会参照项目里已有的Scheduled用法来设计定时任务而不是引入一套不搭调的调度框架。这就是 teach 的价值——让 AI 的产出天然符合项目现有的技术习惯。5.4 第三步干了一半用 handoff 交接给新 Session假设上午这个 Session 干得不错AI 已经完成了数据库表的设计、后端发送任务的实体和 Mapper、定时任务的扫描逻辑但调用报表导出并发送邮件这一环还没做完。这时候你的上下文差不多快用满了而且中午要开会。你果断生成 handoff生成一份 handoff 文档记录当前任务进度。等拿到交接文档后检查一遍关键点确保信息准确。下午开新 Session发接手指令已阅读上述 handoff 文档。 请继续执行待办事项 1实现调用报表导出并发送邮件的逻辑。 完成后完整走一遍定时任务的测试流程把结果汇报给我。因为有了上午的 handoff 文档下午的新 Session 不需要你重新解释我们要做的是一个定时发送报表的功能——它直接进入当前任务已经进行到发送邮件环节的状态。而且因为 handoff 里写明了数据库表结构和 Mapper 已完成它不会傻到又去重新建一张表。5.5 两次 Session 无缝衔接的结果这套流程跑下来最大的感受是什么第一你省下了大量的重复解释时间第二任务中途断掉不再可怕交接文档保证了下一次接手能接得上第三整个项目过程中的知识沉淀下来了不会随着 Session 消失而消失。我个人用这套工作流跑了几个中大型项目之后最直观的变化是以前一个新 Session 的启动成本大约是二十分钟到半小时现在压缩到五分钟以内——其中两分钟给 AI 读项目指南三分钟确认理解然后直接开干。这种效率的提升不是靠某一个命令单独达成的而是 teach 负责让 AI 懂项目、handoff 负责让 AI 接得上活这两者协同的结果。6. 常见问题与排查技巧实录6.1 handoff 之后 AI 还在问已经记录过的问题这个问题我遇到过不止一次。明明 handoff 文档里写了数据库表结构已完成新 Session 里的 AI 还是问需要我设计数据库表吗。排查思路是先检查 handoff 文档是不是真的被 AI 读取了。有些时候你的接手指令表述不明确AI 可能只是扫了一眼文档并没有把内容当作事实基线。我现在的做法是在接手指令里加上一句以下内容为当前任务的事实基线请严格以此为准不要重复讨论已完成决策能把这种情况大幅减少。还有一种可能是 handoff 文档自己写得不清楚。如果你只写了数据库表已完成接手者并不知道具体完成了哪些表。更合理的写法是数据库表已完成包括 report_send_config配置表和 report_send_log发送日志表两张表字段定义在 db/migration/V3__create_report_send.sql 中。信息越具体越不会被误解。6.2 teach 的知识库越来越长要不要瘦身随着项目迭代AGENTS.md里的内容会越来越多。我把这个文件越写越长之后发现 AI 读它的时间变长了而且重要信息被淹没在大量次要信息中AI 的关注度反而下降。我的处理方案是分级维护。核心的 50 行放总纲只保留最新、最常被需要的信息详细的模块指南、历史决策记录、坑位清单全部放到按需读取的附录文件里。新 Session 只自动加载总纲需要深入了解某个模块时我再让 AI 去读对应的附录。这个做法非常有效。它本质上是在做一个信息优先级管理——AI 的上下文窗口是稀缺资源你不能让它平等对待所有信息必须有所取舍。6.3 如何判断 AI 是真理解还是假装理解这是跨 Session 管理中最隐性的风险。AI 在读完你的 teach 文档后可能会说好的我已了解项目结构但实际上它只记住了第一段内容后面根本没细看。如果你随即抛出一个依赖深层知识的任务它就会露馅。于是我在让 AI 学习 完项目之后养成了一个习惯让它用自己的话复述一遍我的项目核心技术约束。比如请用自己的语言描述 1. 当前项目的模块划分和依赖关系。 2. 项目数据访问层的约定是什么。 3. 如果我要新增一个报表模块的方法需要改哪些文件、遵循哪些步骤。这个复述产出的组合验证比单纯问你理解了吗可靠得多。因为理解了吗可以被敷衍回答但要求它产出具体的实现步骤时它如果没读懂项目指南会给出明显偏离项目实际的回答你一眼就能看出来。6.4 交接文档与项目文档混淆怎么办我见过一些使用者把 handoff 文档的内容往 AGENTS.md 里写理由是这些信息以后也许有用。这是典型的信息污染。我刚才反复强调过handoff 的生命周期是任务结束即失效teach 的生命周期是长期有效。你把一次任务的待办事项写进长期项目指南里短期内看是保存了信息实际上是在毒害后面所有 Session 的上下文——它们会读到一堆已经过期的待办事项然后困惑于到底哪些完成了、哪些没完成。我的习惯是项目里的长期知识只存在于 teach 体系里handoff 文档每次任务单独生成、任务结束立即作废或者归档到临时目录。这个习惯一开始有点难坚持但时间长了就会发现这其实是在强制你做知识分类反而让你的信息管理更清晰。6.5 常见问题速查问题原因解决方案新 Session 对项目一无所知未建立 teach 长期知识库编写AGENTS.md项目指南并让 AI 阅读handoff 后 AI 忽略文档继续问旧问题接手指令不明确/文档信息不够具体明确事实基线指令写出具体表名文件路径AI 假装理解但产出偏离项目规范只让 AI 表面阅读没做理解验证让 AI 复述关键约束并产出具体的实现步骤teach 文档过长反而降低 AI 表现全部信息平等占用上下文分级维护核心信息常驻详细信息按需加载任务待办事项污染长期知识库把 handoff 写进了 teach 文档严格区分生命周期任务结束即作废交接文档AI 使用过时的架构决策旧信息从上下文窗口挤掉/被过时文档误导在 teach 中维护最新决策handoff 中写明以 X 为准7. 踩过坑之后我才真正想明白的事情在把所有流程理顺之后回头看看我意识到跨 Session 上下文管理本质上不是技术问题而是信息管理问题。AI 工具给了你无限的工作空间但上下文窗口是有限的给了你长期的记忆能力但记忆需要维护和分类。/handoff和/teach这两个命令看似简单背后的核心思想其实是在教你什么信息该短留、什么信息该长存、信息在什么阶段该以什么形态存在。我现在已经养成了几个雷打不动的习惯任何中大型任务开工前先确保 teach 知识库是最新的任务进行到阶段性成果时就主动生成 handoff不等到上下文溢出才抱佛脚每一份文档生成后都花两分钟审查确认信息准确再交给下一个 Session。最后分享一个刁钻但很实用的小技巧如果你在同一个项目的多个任务之间切换可以在 handoff 文档最开头加一行任务目标的一句话描述。这行字对新 Session 快速进入状态的作用远比整整三段详细描述更有效——因为 AI 和人类一样在开始看细节之前需要一个锚点来确定方向。我个人试下来这个一句话锚点的效果出乎意料地好几乎每次都能让接手 Session 第一次回复就切中要害。