企业官网建设流程全解析

跨 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 关闭，这些记忆就基本清零了——下次你新建一个 Session，AI 就像刚入职的新人，对你项目里的一切都一无所知。

我在实际使用中最常见的一个场景是：上午花三个小时让 AI 把一个订单模块从 REST API 改成消息队列驱动，代码写到一半，中午电脑合盖，下午打开发现 Session 断了。重新起一个 Session，AI 会礼貌地问："请问您的项目结构是什么？"——那一刻我的血压是飙升的。

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 信息是长期的——只要项目还在，代码风格、架构决策这些知识就不会过期。

如果把两条生命周期不同的信息流混在一个文件里，你会发现后面每次开新 Session，AI 读到的都是大杂烩：既有过期的待办事项，又有仍然有效的架构说明。这些过期信息会占据上下文窗口，更糟糕的是，它们可能干扰 AI 对现状的判断，让它误以为某个早已完成的事情还没完成。

所以我现在的习惯是：/teach的内容维护在项目的固定文档里，长期有效；/handoff的内容每次任务前重新生成，任务结束就作废。两者各管各的，互不干扰。

2.3 这套机制的根本优势

从信息传递的角度看，跨 Session 管理最怕的是"信息失真"。传统的手动复制粘贴对话记录，会把大量无关信息传给下一个 Session，AI 需要从中自行提炼重点，效果全看运气。而/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 常见问题速查

7. 踩过坑之后，我才真正想明白的事情

在把所有流程理顺之后，回头看看，我意识到跨 Session 上下文管理本质上不是技术问题，而是信息管理问题。AI 工具给了你无限的工作空间，但上下文窗口是有限的；给了你长期的记忆能力，但记忆需要维护和分类。/handoff和/teach这两个命令看似简单，背后的核心思想其实是在教你：什么信息该短留、什么信息该长存、信息在什么阶段该以什么形态存在。

我现在已经养成了几个雷打不动的习惯：任何中大型任务，开工前先确保 teach 知识库是最新的；任务进行到阶段性成果时就主动生成 handoff，不等到上下文溢出才抱佛脚；每一份文档生成后都花两分钟审查，确认信息准确再交给下一个 Session。

最后分享一个刁钻但很实用的小技巧：如果你在同一个项目的多个任务之间切换，可以在 handoff 文档最开头加一行"任务目标的一句话描述"。这行字对新 Session 快速进入状态的作用，远比整整三段详细描述更有效——因为 AI 和人类一样，在开始看细节之前，需要一个"锚点"来确定方向。我个人试下来，这个"一句话锚点"的效果出乎意料地好，几乎每次都能让接手 Session 第一次回复就切中要害。