Claude Code skill 实战：把会话交接写成可执行的手顺书

Claude Code 的会话是有边界的。一天里可能结束好几次，每次结束都要把「做了什么、还剩什么、踩了什么坑」写成一份交接文档，下一个会话才能接着干。写一次不难，难的是每次都写全、每次都不丢东西。把这件事交给 Claude Code 的 skill 机制——也就是一份让 Claude Code 读取的手顺书——可以把它变成固定流程。这篇讲的就是这样一份 skill 从 59 行长到 123 行的过程，以及每一步为什么会被加进去。

适合的读者：已经在用 Claude Code 做多会话、多项目协作，并且发现自己每次都要手写交接、偶尔漏掉关键信息的人。如果你只是单次对话用完就丢，这篇的价值有限。

准备工作

在动手写 skill 之前，先确认几件事。

理解 Claude Code 的记忆结构

Claude Code 有一个跨会话保留的「记忆」存放区。每个存放区里有一个 MEMORY.md 作为索引，会话开始时会被自动读取。索引本身不存正文，它只负责指向一条条独立的备忘（一个文件一条）。

交接文档就是这些备忘里的一种。做法是：每个项目在索引里挂一条「入口」，指向该项目最新的一份交接文档；下一个会话从这条入口进去，接着干活。

这个结构决定了后面所有设计：索引是检索用的钥匙，正文才是内容。两者混在一起会出问题。

确定存放区与命名规则

一个存放区里可能同时有多个项目的交接文档。如果文件名只有日期，不打开就分不清是哪个项目的。所以文件名里要带项目名，例如：

session-handoff-<项目名>-YYYY-MM-DD.md

同时准备一个归档目录，用来放旧版本，例如 handoff-archive/。

想清楚「什么时候写」

这一点需要人来定，不能交给模型。结论是：确认是必须的，创建是事件驱动的。

每次会话结束前，必须确认该项目是否已有交接文档。
只有当确实还有后续工作没做完时，才新建一份。
已经停摆的项目不要生成空的交接文档。

「每个仓库都必须建一份」是过度设计，会产出大量没有内容的文件。

操作步骤

第一步：写下 skill 的目的

skill 的开头只写目的，不写细节。最初的两个目的是：

防止漏写（靠下面的检查清单兜底）
自动切换索引里的「入口」标记

后来加了第三个，也是最重要的一个：在归档时不要把知识弄丢。这个目的来自一次真实事故，后面会讲。

第二步：固定正文的检查清单

交接文档的正文按固定项目写。这份清单从最早到现在基本没变：

本次会话完成的事（要区分「做了」和「验证过了」）
已合并 / 未合并的改动
下一个会话的主任务
等待验证、被中断的项目
运维上的经验与坑
轻微的遗留事项
当前的结构
相关备忘的链接

其中「区分做了和验证过了」这一条要特别强调。把「改了代码」写成「修好了」，下一个会话会基于错误前提继续工作。

第三步：处理索引膨胀

入口切换之后，旧的那份交接文档不再是入口，但它的索引行和文件都还留着。每天新增几条，索引很快就被交接日志填满。

做法是：把旧的交接文档移到 handoff-archive/，同时删掉索引里对应的行。不要用「（已有后继）」之类的注记保留。

但这里有个陷阱，必须同时立一条铁律：

归档只针对同一项目中非最新的那些。每个项目的最新一份必须留在索引里。

如果只是机械地执行「把旧的退避掉」，很可能把另一个并行项目的入口也一起退避了。那个项目从下一个会话开始就找不到了。

第四步：规定索引的排序

入口的排列顺序要固定，否则每次都要重新判断：

有明确着手计划的项目排在上面，其余排在下面。
各组内部按日期从新到旧。

第五步：加上退避前检查（最关键的一步）

这一步来自一次事故：某次写完新交接、把旧交接移到归档目录之后，才发现只有旧交接里写着的三条知识没有落到别处。文件还在归档目录里，理论上能恢复，但归档目录平时没人打开。

复盘出三个原因，对策与原因一一对应：

原因	对策
「反映到已有备忘」这一步的标题写成「（必要时）」，看起来像可选项；而且只针对「本次会话的知识」，没有检查即将被归档的那一份	把反映拆成两个方向：①本次会话的知识；②即将被归档的旧交接里独有的知识
唯一的刹车写在 `mv` 指令之后，而且带着「前面的步骤应该已经做完了」的乐观假设	把「退避前检查」放到 `mv` 之前。逐条检查旧交接的每一项，分成三类，只要还有未分类的项就不许执行 `mv`
没有要求确认，也没有要求报告，执行方和人都发现不了遗漏	分类结果必须给人看

三类分法如下：

分类	去向
知识、坑、做法、教训	正式备忘（这里最容易漏）
未完成的任务、等待验证、等待判断	新的交接文档
当时的数值（件数、使用率、ID）	可以丢弃

拿不准的时候往正式备忘那边靠。正式备忘里冗余是无害的，丢失是有害的。

同时要改写 skill 末尾那句判断依据。原来写的是「应该已经反映过了」，这本质上是对另一个会话里的自己的信任。改成只承认已实施的事实：逐项分类过，并且用眼睛确认过正式备忘里的对应描述。

这条检查确实有效。某次同一个项目里，退避前检查两次各捡出两条正式备忘里没有的知识，一共四条。没有这道检查，这四条就会沉在归档目录里。

第六步：给索引本身也加上同样的手顺

索引后来出了问题：某一行从一行变成了一整段，最长到 1963 字。索引本来是「该打开哪份备忘」的检索键，结果正文被写进去了。更糟的是，有的行里索引和正文说的是相反的事——正文写「未部署」，索引写「已发布」。

于是补了三条：

索引的一行控制在 120 字左右，不写正文。
件数、版本号、使用率这类当时的数值不要写进索引。它们几天就过期，却会一直留在索引里。
要缩短索引时，走和退避前检查一样的手顺：先把只存在于索引里的后续信息移进正文，再删。

需要说明的是，这一条不能算有效。三周后重新统计，索引比删减后的字数又涨了 25%。

第七步：定下 skill 的骨架

最终的 skill 结构大致如下，标题顺序本身就是关卡的顺序：

目的：防止漏写 / 切换入口 / 归档时不丢知识
何时使用
前提的确定：存放区、日期、项目名、文件名
确认上一份交接：确认是必须的，创建是事件驱动的。读它有两个目的——接着写，以及做对照
写正文：八项检查清单。不写机密。当时的观测要标注「需再确认」
反映到已有备忘：退避的前提条件，不可省略。退避前检查（三分类，有未分类就不许前进）
更新索引并退避：第 6 步没做完就不许 mv。每个项目的最新一份必须保留。一行 120 字左右
收尾：分类结果必须给人看
不做的事：会话开始时自动生成、量产内容稀薄的交接文档

编号即关卡顺序：第 6 步没完成就不进第 7 步，第 7 步的结果在第 8 步给人看。

一个完整示例

假设有两个并行项目 alpha 和 beta，今天要结束 alpha 的会话。

1. 确认前提

存放区：memory/
日期：2026-10-02
项目名：alpha
文件名：session-handoff-alpha-2026-10-02.md

2. 确认上一份交接

memory/session-handoff-alpha-2026-09-28.md

读它，一边接着写，一边做对照。

3. 写正文，按八项清单逐条填。注意区分「做了」和「验证过了」。

4. 退避前检查。把上一份交接（09-28）的每一项从上到下分成三类：

知识/坑/做法/教训  → 正式备忘
未完成任务/待验证   → 新交接（10-02）
当时的数值          → 丢弃

只要还有未分类的项，就不执行下一步。

5. 更新索引并退避。把 alpha 的入口指向 10-02；把 09-28 移到归档目录，并删掉它在索引里的行。不要动 beta 的入口。

mv memory/session-handoff-alpha-2026-09-28.md handoff-archive/

6. 收尾。把第 4 步的三分类结果给人看。

注意事项

写进 skill 也管不住的情况

120 字那条规则确实写在 skill 的手顺里，但三周后索引还是涨了 25%。原因大致是：往索引里加行的路径不止 skill 这一条。添加交接以外的备忘时，也会往索引加一行，而那条路径不会读 skill，也没有给人看的出口。

结论是：写在手顺里的规则，只对经过这条手顺的作业有效。做自己的 skill 时，要确认同一件事在 skill 之外有没有别的路径；有的话，这条规则写进 skill 也不管用。

不要用「应该已经做过了」当依据

「前面的步骤应该已经反映过了」是对另一个会话里的自己的信任，不是事实。判断依据只能是已实施的动作：逐项分类过、用眼睛确认过正式备忘里的对应描述。

刹车要放在不可逆操作之前

文章里的规则，写在哪里都是「读了才会遵守」。放进手顺里，才能在那个操作之前拦住。归档（mv）、覆盖、删除、push——这些一旦执行就回不来的操作，前面都要写一句「这件事没做完就不许继续」。

给自己留一个给人看的出口

分类结果必须给人看，这是检测退化的最后一道防线。自己的分类错误自己发现不了，所以要把它摆成人能说一句「这个丢掉真的没问题吗」的形式。那次三条知识的遗漏，就是被人指出来的。

不要写进去的东西

当时的数值（件数、版本、使用率）、机密信息，以及已经留在代码或 git 里的内容，都不要写进交接文档。前两类会过期或泄露，第三类重复且容易和实际代码不一致。

变更记录要写清「发生了什么、为什么」

每次事故后加一行对策，并在变更记录里写清当时发生了什么、为什么会发生。这样后面回看时才知道这行字是为什么存在的。这份 skill 从 59 行到 123 行，多出来的 64 行每一行都有理由，每一行都是在某次事故或险些出事之后补上的。

最后提醒：Claude Code 的功能、配额、价格与可用地区会变化，动手前请以官网当前信息为准。