Claude Code 的并行安全上下文交接

2026年2月27日·1 分钟阅读

单文件的问题

每个 Claude Code 会话都从零开始。关掉终端，上下文就消失了。不记得你构建了什么、哪里出了问题、做了什么决策、什么还没完成。

上下文交接解决了这个问题。每次会话结束时，写一份结构化文档。下次会话开始时，读取它。这样新会话就有了完整的上下文。

第一个版本永远是单文件。~/.claude/context-handoff.md。每个会话启动时读取，结束时写入。简单，高效。

直到你打开第二个终端。

终端 A 完成任务后写入交接文件。终端 B 在30秒后完成并覆盖了它。终端 A 的上下文就这么没了。你根本不会注意到，因为文件还在。只是里面的内容已经不对了。

这是一个"最后写入者获胜"的竞态条件。随着规模扩大，问题会越来越严重。我同时运行4到6个 Claude Code 终端。用单文件方案时，每天会有3到5个会话的上下文被悄悄销毁。系统看起来正常运行，因为交接文件始终存在。你只是看不到它缺失了什么。

我是怎么走到这一步的

演进过程是这样的：

没有交接。 每次会话都从零开始。重新解释所有事情。前10分钟都浪费在让模型搞清楚状况上。大多数人都在这个阶段。

单文件。 ~/.claude/context-handoff.md。CLAUDE.md 告诉模型在启动时读取它、结束时写入它。会话开始叠加而不是每次重置。巨大的升级。用了好几个月都很好。

崩坏。 我开始运行并行终端。一个写内容，一个搞基础设施，第三个调试，第四个构建 wiki。所有终端都写入同一个文件。上下文开始消失。我好几周都没注意到，因为交接文件一直有内容。只是它丢失了80%的会话信息。

修复。 基于目录的并行写入。带时间戳的文件。启动时全部读取。消费后标记完成。实现只用了30分钟。

令人沮丧的是，回头看修复方案是多么显而易见。我花了几周丢失上下文，才意识到问题出在架构上，而不是模型上。

架构设计

完整的并行安全交接系统有4个操作。

写入。 每个会话写入 ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md。时间戳保证唯一性。不会有两个会话冲突。slug 描述了会话正在处理的内容。

读取。 会话启动时，列出所有不以 _done.md 结尾的文件。逐一读取。将所有上下文合并到当前会话中。

消费。 读取后，将每个文件从 file.md 重命名为 file_done.md。后续会话跳过已消费的文件。原始内容保留在磁盘上供参考。

清理。 定期删除超过7天的已消费交接文件。未消费的交接文件永远不会被删除。

完整的生命周期如下：

会话启动：
  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

这就是整个系统。没有数据库。没有锁文件。会话之间无需协调。每个会话独立运行，由目录处理合并。

记忆升级

在修复交接系统时，我在记忆文件上遇到了同样的问题。

MEMORY.md 是一个每次会话都加载的单文件。刚开始是30行。几周后，每个会话都往里追加内容，就膨胀到了400多行。Claude 对自动记忆文件只加载前200行。第200行之后的所有内容都看不见了。决策、偏好、架构笔记 - 全部被悄悄截断。

修复方案遵循同样的模式。别把所有东西都塞进一个文件。

MEMORY.md 变成一个精简的索引文件。控制在200行以内。包含章节标题、一行摘要和指向话题文件的链接。

话题文件 存储细节。identity.md 存身份和个人资料数据。voice-rules.md 存语音系统快速参考。infrastructure.md 存模型、定时任务、关键路径。completed-work.md 存已完成的工作。

MEMORY.md 始终加载。话题文件按需加载，在任务相关时才载入。索引文件始终保持在截断限制以下。细节在需要时随时可用。

和交接目录一样的原则。用结构化方案替代单个过载的文件。

前后对比

之前：

一个交接文件在 ~/.claude/context-handoff.md
最后写入的终端获胜，其他所有上下文丢失
一个 MEMORY.md 文件无限增长
第200行之后的内容悄悄消失
会话随机丢失上下文，没有任何可见错误

之后：

交接目录在 ~/.claude/handoffs/
每个会话写入唯一命名的文件
所有未消费的交接文件在会话启动时合并
MEMORY.md 是一个200行的索引，链接到话题文件
话题文件按需加载，永远不会被截断
并行终端之间零上下文丢失

并行交接系统已经运行了一周。六个终端，同时进行的会话，没有丢失任何上下文。早晨的会话读取前一天的3-5个交接文件，以对前一天发生的所有事情的完整感知开始。

拿去用

这是你需要的 CLAUDE.md 配置块。直接复制到你的项目中。

## Context Handoff System

Handoffs are parallel-safe. Multiple terminals can write handoffs
without overwriting each other.

### On Session Start
1. Read all unconsumed handoffs:
   ls ~/.claude/handoffs/*.md 2>/dev/null | grep -v '_done.md$'
2. Also check legacy location: ~/.claude/context-handoff.md
3. After reading, mark each consumed:
   rename file.md to file_done.md
4. Clean up old consumed handoffs:
   find ~/.claude/handoffs -name '*_done.md' -mtime +7 -delete

### On Session End
Write handoff to ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md
Never overwrite another session's handoff.

目录结构：

~/.claude/
  handoffs/
    2026-02-27_091522_blog-pipeline.md        (未消费)
    2026-02-27_093401_wiki-entries.md          (未消费)
    2026-02-26_201145_deploy-fix_done.md       (已消费)
    2026-02-26_184230_content-batch_done.md    (已消费)

每个交接文档包含5个部分：

会话摘要。 一段话。目标是什么，发生了什么。
变更内容。 创建、修改、删除的文件。具体路径。
待完成事项。 未完成的任务、已知 bug、下一步。
关键决策。 架构选择、权衡取舍、下一个会话不应重新讨论的事项。
当前上下文。 分支名、正在运行的进程、环境状态。

交接文件要保持客观。不要加评论。一个早上6点读取它的会话需要的是文件路径和状态，而不是你对重构的看法。

值得点明的递归洞察是：上下文工程基础设施本身也需要上下文工程。管理会话上下文的交接系统，本身就因为上下文问题而出了故障 - 会话互相覆盖，因为架构没有考虑并行性。修复方法是应用我在其他所有场景中使用的相同原则：结构化、命名规范，以及永远不要把所有状态放在一个文件里。