$ man context-wiki/context-handoffs

Claude Code 会话是无状态的。关闭终端，上下文就消失了。每个新会话都从零开始。不记得你刚构建了什么、什么出了问题、做了什么决策、什么还没完成。上下文交接解决了这个问题。在每次会话结束时，写一份结构化文档，记录发生了什么、什么改变了、什么还需要做、做了什么决策。在下一次会话开始时，先读取那份文档。现在新会话就有了之前发生的完整上下文。会话不再重置，而是开始复利增长。交接不是锦上添花。它是一个会遗忘一切的 AI 和一个能在昨天基础上继续构建的 AI 之间的区别。

反模式

上下文交接的第一个版本总是单个文件。类似 ~/.claude/context-handoff.md。一个文件。每个会话启动时读取，结束时写入。当你一次只运行一个终端时这完全没问题。但当你打开第二个终端时就出问题了。终端 A 完成并写入它的交接。终端 B 30 秒后完成并覆盖终端 A 的。终端 A 的上下文丢失了。你直到第二天早上某个会话以缺失一半上下文的状态启动时才注意到。这是经典的最后写入者获胜的竞态条件。随着规模扩大情况更糟。我同时运行 4 到 6 个 Claude Code 终端。用单个交接文件，每天有 3 到 5 个会话的上下文被悄悄销毁。系统看起来在正常工作，因为你总能看到一个交接文件。你只是看不到它缺少了什么。

模式

解决方案很简单。停止覆盖一个文件。改为向目录写入带时间戳的文件。每个会话写入 ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md。时间戳保证唯一性。没有两个会话会冲突。在会话启动时，读取目录中所有未消费的交接文件。合并每个文件的上下文。读取后，将每个文件从 file.md 重命名为 file_done.md，这样它不会被再次读取。清理任务删除 7 天前已消费的交接文件。整个架构是 4 个操作：写入一个唯一命名的文件、读取所有未读文件、标记文件为已消费、清理旧文件。无需数据库。无需锁文件。无需会话间协调。每个会话独立运行，目录处理合并。

代码

带并行安全交接的会话生命周期： 会话启动： ls ~/.claude/handoffs/*.md（跳过 *_done.md） --> 读取每个未消费的交接 --> 将 file.md 重命名为 file_done.md --> 将所有上下文合并到当前会话 会话结束： --> 写入 ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md --> 永远不覆盖另一个会话的文件 清理（定期）： find ~/.claude/handoffs -name '*_done.md' -mtime +7 -delete 并行安全来自命名约定。两个在同一秒结束的会话需要相同的 slug 才会冲突。实际上这永远不会发生，因为 slug 描述工作内容而时间戳精确到秒。

公式

每份交接文档需要五个部分： 1. 会话摘要。一段话。目标是什么、发生了什么。 2. 变更内容。创建、修改、删除的文件。具体路径。 3. 待完成工作。未完成的任务、已知 bug、下一步计划。 4. 关键决策。架构选择、权衡取舍、下一个会话不应重新审视的事项。 5. 活跃上下文。分支名称、运行中的进程、环境状态，下一个会话需要知道的关于当前机器状态的任何信息。 保持事实性。没有评论，没有观点，没有叙事。交接是状态报告，不是博客文章。早上 6 点读取它的会话不需要你对重构的感受。它需要知道哪些文件改变了以及什么出了问题。