平时用 Claude Code 写复杂项目时最头疼的不是让 AI 写代码而是让“上一个会话的上下文”顺利交接到“下一个会话”。如果你也遇到过类似场景上午让 Claude Code 分析了一整份日志下午新开会话又得把结论重新粘贴一遍或者接手一个别人用 Claude Code 开发到一半的项目完全不知道之前改了什么、下一步该干什么又或者切了几次会话后AI 开始把同名变量反复定义……那这篇内容应该对你有用。这篇文章会先讲清楚 Claude Code 的会话机制和“跨会话通信”的本质再给出文件共享、脚本检索、MCP 服务器三条进阶实现路径附带可直接运行的代码和排错方案。无论是刚接触 Claude Code 的新手还是已经在团队里推广 AI Coding 的开发者都可以照着做。1. 为什么需要跨会话通信1.1 每个会话都是一个独立的“上下文容器”Claude Code 的本质是一个跑在终端里的 AI 编程代理Agent。你可以在一个项目目录下启动它然后通过自然语言让它读代码、改文件、执行命令、跑测试。这里有一个关键机制每次启动 Claude Code 都会创建一个新会话会话之间默认是隔离的。这一点和 ChatGPT、Claude 网页版的“多轮对话”不太一样。网页聊天通常会把同一个窗口内的所有历史留在上下文里你可以不停追问模型记得住刚才聊了什么。但 Claude Code 面向的是长期项目一个会话里可能改了很多文件、跑了很多命令、产生了很多结论。如果所有历史都一直挂在上下文里token 消耗会非常夸张上下文窗口也很快会撑爆。所以 Claude Code 会按会话管理上下文一个会话有自己的“记忆边界”。会话结束后下一次启动不会自动加载上一次的全部内容。1.2 复制粘贴传递信息的痛点早期开发者最常用的“跨会话传话”方式就是新开会话后手动把上一个会话的报错、代码片段、结论贴进去。这在简单任务里勉强能用但项目一旦复杂起来问题非常明显长上下文容易丢。复制粘贴的内容超过一定长度后模型可能忽略中间部分或者只记住开头和结尾。格式被破坏。从终端复制多行日志、JSON、代码块时缩进和特殊字符经常错乱Claude 拿到之后反而理解偏了。浪费 token。把整段日志或整个文件粘进去等于让模型重新读一遍原始数据成本很高。容易漏信息。上一个会话里可能有一些隐性结论比如“这个 bug 是因为 Nginx 缓存没清”如果不写进交接文字下一个会话完全无从知晓。无法追溯。复制粘贴出来的内容是游离的没有落盘也不能检索过几天就找不到了。这些痛点总结起来就是开发者需要一种机制让不同会话之间可以共享状态、沉淀结论、无损交接。这也正是“跨会话通信”要解决的问题。1.3 跨会话通信解决什么问题从工程角度看跨会话通信的本质是上下文的持久化与恢复。它要解决的场景包括任务交接会话 A 分析完问题会话 B 接着改代码。团队协作多个开发者各自运行 Claude Code但他们需要看到同一份项目进度。阶段性沉淀把每次会话的关键决定、待办事项、技术约束保存下来让后续会话自动读取。历史检索之前某个会话里提到过一个方案现在需要快速找回来。理解了这些场景后面配置方案时就会更清楚所有跨会话通信方案本质上都是在“文件系统”和“外部工具”上做文章而不是让模型天生拥有跨会话记忆。2. 跨会话通信的几种实现思路跨会话通信没有统一的官方标准更多是开发者结合 Claude Code 的能力自己搭出来的工作流。下面按实现成本从低到高介绍三种主流思路。2.1 文件系统共享最简单的跨会话“总线”Claude Code 天然会读取项目里的记忆文件最常见的是CLAUDE.md。当你在项目根目录创建CLAUDE.md后Claude Code 每次启动都会自动读到它。我们可以利用这个机制把项目约定、当前进度、关键决策写进去。更进一步可以建立一个专门的交接目录比如.claude/handoff/每个会话结束时把结论写成一个 Markdown 文件。下一个会话开始时只需要一句话让 Claude Code 读取对应文件即可。这种方式的优点是零额外依赖纯靠文件读写。内容人类可读也能提交到 Git团队共享。不需要改 Claude Code 配置。缺点是检索效率低文件多了之后容易找不到对应结论而且依赖开发者的自觉不主动写就没有交接信息。2.2 MCP 服务器让多个会话共享同一套工具与状态MCPModel Context Protocol是 Claude Code 支持的一种工具扩展协议。通过 MCP开发者可以给 Claude Code 挂载自定义工具比如“保存笔记”“读取任务状态”“查询数据库”。核心思路是把跨会话通信变成一组工具调用由外部程序负责状态存取。举例来说你可以开发一个“会话共享状态服务器”提供一个save_note(key, content)工具和一个get_note(key)工具。两个完全不同的 Claude Code 会话都挂载同一个 MCP 服务器它们就能通过工具读写同一份共享文件或数据库。这种方式的优点是交互方式更自然Claude 可以直接调用工具而不是靠复制粘贴状态管理更规范支持结构化数据。缺点是需要额外编写服务器代码MCP SDK 的 API 也在快速迭代需要根据版本调整。2.3 外部脚本与别名检索历史会话内容的懒人方案Claude Code 会把每次会话的历史记录以 JSONL 格式保存在本地目录通常是~/.claude/projects/。这些历史文件包含了你和 Claude 的完整对话内容。借助脚本我们可以直接在终端里全文搜索历史会话再配合fzf、bat等工具快速预览。这种方式适合“回看过去某次思路”不适合做实时的状态传递但它是一个非常高效的补充。当文件交接没写、CLAUDE.md 没更新时历史检索往往能把之前的内容捞回来。3. 环境准备与基础配置在动手实现跨会话通信之前先把 Claude Code 的基础环境准备好。这里不会罗列所有安装细节重点讲清楚容易踩坑的几个点。3.1 安装 Claude Code 并完成登录Claude Code 官方主推的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后先检查版本claude --version如果提示找不到命令通常是因为 npm 的全局 bin 目录没有加入PATH。在 macOS / Linux 上可以执行export PATH$PATH:$(npm prefix -g)/binWindows 上如果遇到npm install报错优先检查 Node.js 版本是否过老再用管理员权限打开 PowerShell 重试。安装完成后在项目目录里运行claude首次启动会要求登录按提示完成认证即可。这里有一个常见坑如果在公司网络或受限环境中登录可能会失败。遇到这类问题属于账号订阅或组织策略的限制需要联系组织管理员确认订阅权限而不是盲目更换网络环境。3.2 确认会话历史存储位置安装完成后Claude Code 会在本地保存会话历史。不同操作系统下位置稍有差异但总体在用户目录下的.claude文件夹中~/.claude/全局配置文件、历史记录总目录。~/.claude/projects/按项目存放的会话历史 JSONL 文件。~/.claude/CLAUDE.md用户级别的 Claude Code 记忆文件对所有项目生效。项目级别的CLAUDE.md要放在项目根目录。Claude Code 启动时会自动读取这个文件把里面的内容当作项目长期记忆。这个文件非常适合存放跨会话的稳定信息比如技术栈约定、目录结构、常见命令、开发规范。3.3 初始化项目记忆文件这里给出一个CLAUDE.md的基础模板按自己的项目情况修改# 项目环境说明 - 技术栈Node.js 18 Express 4 SQLite - 启动命令npm run dev默认端口 3000 - 测试命令npm test - 项目结构src/ 存放源码tests/ 存放测试docs/ 存放文档 # 开发约定 - 数据库迁移脚本放在 migrations/ 目录命名格式YYYYMMDD_描述.sql - 调用第三方 API 时必须通过 src/services/httpClient.js 统一发出 - 修改公共组件前先在 docs/decision-records/ 下追加 ADR 文档 # 当前进度 - [x] 完成用户登录模块 - [ ] 完成订单导出功能 - [ ] 补充接口压测脚本这个文件写好后每次启动 Claude Code 都会自动看到。它相当于一个“项目级长期记忆库”跨会话通信的第一步就是把它用起来。4. 实战通过共享文件实现跨会话上下文传递4.1 创建项目交接目录与模板先创建目录mkdir -p .claude/handoff在.claude/handoff/下放一个模板文件template.md方便每次交接时照格式填写# 任务交接任务名称 - 日期YYYY-MM-DD - 当前状态进行中 / 已完成 / 有阻塞 - 会话目标本次会话要解决什么问题 - 关键结论分析得出的核心结论 ## 已完成 1. ## 待办 1. ## 遗留问题 / 风险 1. ## 相关文件 -4.2 在会话 A 中生成交接清单假设现在有一个实际任务给一个 Node.js 项目中添加一个“慢查询统计模块”。你在会话 A 中让 Claude Code 完成了代码分析和初步实现临退出前让 Claude 把进度写入交接文件请阅读当前项目的 src/ 目录分析现有数据库访问方式然后完成一个慢查询统计模块记录执行时间超过 500ms 的 SQL并写入日志文件。 完成实现后把以下内容写入 .claude/handoff/2025-04-01-slow-query.md 1. 当前进度 2. 已修改的文件列表 3. 慢查询判断逻辑的核心设计 4. 下一步待办会话 A 结束后.claude/handoff/2025-04-01-slow-query.md可能长这样# 任务交接慢查询统计模块 - 日期2025-04-01 - 当前状态进行中 - 会话目标实现慢查询统计模块 - 关键结论使用拦截器统一包装数据库查询避免在每个 DAO 中手工埋点 ## 已完成 1. 新增 src/utils/slowQueryLogger.js 2. 在数据库连接池配置中接入慢查询拦截器 3. 慢查询判断逻辑duration 500ms记录 SQL、执行时间、参数摘要 ## 待办 1. 需要为慢查询日志添加轮转避免单文件过大 2. 建议补充单元测试 ## 遗留问题 / 风险 1. 参数摘要可能包含敏感字段需要过滤 ## 相关文件 - src/utils/slowQueryLogger.js - src/config/database.js这个文件已经变成了会话 A 和会话 B 之间的“通信协议”。它不是聊天记录粘贴而是一份结构化、可检索、可版本化的交接文档。4.3 在会话 B 中读取交接清单新开一个 Claude Code 会话只需一句话请先读取 .claude/handoff/2025-04-01-slow-query.md了解慢查询统计模块的进度然后继续完成剩余待办为慢查询日志添加轮转并补充单元测试。这样的话Claude 不需要依赖任何“上一个会话”的记忆仅凭文件就能把上下文恢复得七七八八。如果交接文件里信息足够完整它甚至能直接开始干活。这看起来非常简单但它才是跨会话通信最核心、最稳定的实践。很多团队用 Claude Code 做大型项目时最终沉淀下来的并不是什么复杂工具而是一套良好的交接文件规范。4.4 用脚本快速检索历史会话除了主动写交接文件我们还可以从历史会话里被动捞信息。Claude Code 的会话记录是以 JSONL 格式保存在~/.claude/projects/下的每一行是一条消息。下面这个脚本可以扫描所有历史记录提取用户和助手的文本内容并用fzf做交互式搜索。先确认已经安装了jq和fzf# macOS brew install jq fzf # Ubuntu / Debian sudo apt update sudo apt install jq fzf然后创建一个脚本文件例如~/bin/claude-search.sh#!/usr/bin/env bash # 用法claude-search.sh [搜索关键词] # 功能搜索 Claude Code 历史会话内容并预览匹配到的对话片段 PROJECT_DIR${HOME}/.claude/projects if [[ ! -d ${PROJECT_DIR} ]]; then echo 未找到 Claude Code 历史目录: ${PROJECT_DIR} exit 1 fi # 扫描所有 jsonl提取文本内容 find ${PROJECT_DIR} -name *.jsonl -print0 | while IFS read -r -d file; do jq -r select(.type user or .type assistant) | .message.content[]? | if .type text then .text else empty end ${file} 2/dev/null done | fzf --preview bat --styleplain --coloralways {} --preview-windowright:60%给脚本加执行权限chmod x ~/bin/claude-search.sh使用时直接运行脚本~/bin/claude-search.sh脚本会读取所有历史记录并喂给fzf。你可以输入关键词比如“慢查询”然后上下选择查看匹配片段。虽然这里没有做到严格的“按会话分组”但对于快速找回某段思路已经很有帮助。如果你更关注文件粒度也可以优化脚本把匹配到的句子连同所属的会话文件名一起输出方便定位到具体历史记录文件再用编辑器打开完整内容。5. 进阶用 MCP 构建跨会话共享状态文件交接很适合“人与人配合”的工作流但对于重度用户来说仍然需要手动创建文件和提示 Claude 读取。如果想让多个会话之间的通信更自动、更结构化可以考虑 MCP 方案。5.1 MCP 的作用与适用边界MCP 提供了一套让 Claude Code 与外部程序交互的标准协议。你可以把它理解为“给 Claude 加插件的标准接口”。Claude 在对话中如果需要某个外部能力会通过 MCP 调用你注册的工具。在跨会话场景中MCP 的价值是把“读取共享状态”和“保存共享状态”变成工具调用。例如会话 A 调用save_note保存一条任务进度会话 B 在同一个项目里调用get_note读取最新任务进度。两个会话之间不需要复制粘贴只需要同时连接同一个 MCP 服务器。适用边界也很明显MCP 适合频繁、结构化的状态读写。如果你只是想简单传一段话写个 Markdown 文件就够了如果你希望 Claude 能像调用函数一样读写状态或者把状态存到数据库里再用 MCP。5.2 实现一个轻量级共享状态 MCP 服务器下面使用modelcontextprotocol/sdk写一个极简的共享状态服务器。它的作用是提供两个工具save_note(key, content)保存一条笔记到项目.claude/shared/目录。get_note(key)读取对应笔记内容。创建项目目录并初始化mkdir claude-shared-mcp cd claude-shared-mcp npm init -y npm install modelcontextprotocol/sdk创建index.jsimport { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import fs from node:fs/promises; import path from node:path; const server new McpServer({ name: session-shared-state, version: 0.1.0 }); // 共享目录当前项目下的 .claude/shared const SHARED_DIR path.join(process.env.PWD || process.cwd(), .claude, shared); server.tool( save_note, { key: { type: string }, content: { type: string } }, async ({ key, content }) { await fs.mkdir(SHARED_DIR, { recursive: true }); const filePath path.join(SHARED_DIR, ${key}.md); await fs.writeFile(filePath, content, utf8); return { content: [{ type: text, text: 笔记已保存${filePath} }] }; } ); server.tool( get_note, { key: { type: string } }, async ({ key }) { try { const filePath path.join(SHARED_DIR, ${key}.md); const content await fs.readFile(filePath, utf8); return { content: [{ type: text, text: content }] }; } catch (error) { return { content: [{ type: text, text: 未找到笔记${key} }] }; } } ); const transport new StdioServerTransport(); await server.connect(transport);需要注意MCP SDK 的server.tool写法和工具参数的 schema 格式会随 SDK 版本变化。上面的代码是当前较常用的写法如果你安装的版本不同请以官方示例为准。5.3 在 Claude Code 中注册与测试在 Claude Code 中可以把会话级、项目级或全局的 MCP 服务器加进来。这里用项目级方式测试claude mcp add --scope project session-shared -- node index.js运行时可以先让会话 A 执行请使用 save_note 工具把这条内容保存为 progress已完成用户登录模块下一步做订单导出。然后在会话 B 中执行请使用 get_note 工具读取 progress 笔记并告诉我下一步该做什么。这样两个会话就通过同一个 MCP 服务器完成了状态传递。更进一步你可以在save_note里加上时间戳、操作人、版本号或者把数据改存到数据库里实现更复杂的共享状态管理。6. 常见问题与排查思路在配置和使用 Claude Code 跨会话功能时经常会遇到下面这些报错或异常。这里整理成表格方便快速排查。问题现象常见原因解决思路执行claude提示 command not foundNode.js 全局 bin 目录不在 PATH 中重新安装 Node.js 并确认 npm 全局目录macOS/Linux 手动添加npm prefix -g到 PATHWindows PowerShell 安装 Claude Code 报错Node.js 版本过老或权限不足升级 Node.js用管理员 PowerShell 重跑安装命令运行时报could not locate the claude cli on pathVSCode 或其他 IDE 中找不到 claude 可执行文件确保claude命令在系统 PATH 中可用重启 VSCode 或终端终端显示乱码终端编码与 Claude Code 输出编码不一致Windows 终端执行chcp 65001切换到 UTF-8macOS 终端检查 locale 设置your organization has disabled claude subscription access for claude code组织订阅策略禁止使用 Claude Code联系组织管理员开通权限或者使用自己的订阅账号提示your limits are temporarily boosted/ 周限额提示账号触发了使用限制动态调整降低单次任务复杂度避免一次性向 Claude 塞入大量上下文等待限制恢复会话历史很多claude-search.sh搜索很慢JSONL 文件数量过多脚本每次全量扫描增加索引机制按日期或项目路径过滤后再搜索MCP 注册后 Claude 调不到工具MCP 服务器启动失败或 schema 格式不匹配先用claude mcp list查看注册状态手动运行node index.js测试进程是否正常补充一点如果你的历史搜索脚本匹配不到内容先打开/Users/你/.claude/projects/下对应的 JSONL 文件确认type字段和message.content的结构。Claude Code 不同版本的历史记录格式略有差异脚本里的jq路径需要按实际格式调整。7. 工程实践与建议跨会话通信的核心不是某一条命令或某个工具而是建立一套“会话之间如何协作”的团队约定。下面这些建议来自实际项目中的经验按重要程度排列。7.1 把 CLAUDE.md 当“项目宪法”维护CLAUDE.md是影响所有会话的基础记忆文件。它应该保持稳定、精简、覆盖高频信息。不要什么内容都往里塞否则 Claude 每次启动都要读大量无关信息既浪费 token也会稀释重点。建议按“稳定信息”和“动态信息”分层CLAUDE.md存放稳定信息环境、目录结构、命令、规范。.claude/handoff/存放动态信息每次任务进度、交接记录。需要长期留存的决策移到docs/decision-records/并在CLAUDE.md中只保留索引。7.2 明确每个会话的边界开始一个会话前先在脑子里定义好这个会话要做完什么。每次会话结束前主动让 Claude 生成交接总结。可以在CLAUDE.md中加一条规则比如# 会话结束规则 当会话目标已完成或用户准备退出时自动把当前进度写入 .claude/handoff/ 下以日期命名的 Markdown 文件。这样 Claude 到点会自动写交接文档不需要每次手动提醒。注意CLAUDE.md中的指令并不是 100% 强制执行的但在大多数情况下模型都会遵守这类清晰约定。7.3 避免复制大段日志优先保存结论很多开发者想让新会话快速理解问题会把一长串日志直接粘贴给 Claude。这个习惯在跨会话场景中很浪费日志属于原始数据模型需要重新推理一遍。大量日志会挤占上下文窗口影响后续任务执行。更好的方式是在会话 A 中就提炼出结论例如“错误发生在src/utils/format.js第 23 行原因是Intl.DateTimeFormat不支持传入空字符串”然后把结论写入交接文件。会话 B 读取结论后只在必要时打开源码文件确认细节而不是重新读一遍日志。7.4 MCP 服务器要控制权限边界如果你使用 MCP 做跨会话共享一定要控制 MCP 服务器的权限范围。上面的示例只是读写项目目录这是相对安全的。但如果你的 MCP 服务器能执行 SQL、访问线上接口、操作文件系统就必须加上鉴权逻辑。生产环境里建议遵循最小权限原则MCP 服务器只能访问指定目录、指定数据库表不能拥有整个系统的读写权限。7.5 定期清理和归档交接文件交接文件多了以后.claude/handoff/会变得混乱。建议每周或每个迭代结束之后把已完成的交接文件归档到docs/handoff-archive/。删除已经失效的临时笔记。把重复出现的经纬度信息提炼到CLAUDE.md。这样既能保证历史可追溯又不会让 Claude 每次扫描目录时被大量无关文件干扰。8. 总结与下一步学习建议跨会话通信不是 Claude Code 自带的一个开关而是一套围绕“上下文持久化”搭建的工作流。文件系统共享、历史检索脚本、MCP 服务器这三条路径成本从低到高灵活度也逐级提升。实际项目中建议先从CLAUDE.md和.claude/handoff目录用起来跑通后再决定是否需要上 MCP。如果需要继续深入可以按下面顺序学习先熟练维护CLAUDE.md让每个会话自动获得项目基础信息。再建立交接文档模板让每次会话结束都能沉淀出结构化结论。然后编写历史检索脚本解决“之前那个方案在哪说过”的问题。最后研究 MCP SDK把高频的跨会话状态读写封装成工具。另外提醒一句Claude Code 的版本更新很快MCP 的 API、CLI 参数、历史记录格式都可能变化。动手配置时如果发现某个命令不存在或格式对不上优先查看本地版本对应的官方文档不要强行照搬网上旧命令。如果这篇内容对你理解跨会话通信有帮助建议先创建一个交接目录跑一次完整流程让会话 A 写交接文件再让会话 B 读取并继续任务。只有亲手跑通一次才能真正告别复制粘贴式的上下文搬运。
Claude Code跨会话通信实战：文件共享、MCP与历史检索
平时用 Claude Code 写复杂项目时最头疼的不是让 AI 写代码而是让“上一个会话的上下文”顺利交接到“下一个会话”。如果你也遇到过类似场景上午让 Claude Code 分析了一整份日志下午新开会话又得把结论重新粘贴一遍或者接手一个别人用 Claude Code 开发到一半的项目完全不知道之前改了什么、下一步该干什么又或者切了几次会话后AI 开始把同名变量反复定义……那这篇内容应该对你有用。这篇文章会先讲清楚 Claude Code 的会话机制和“跨会话通信”的本质再给出文件共享、脚本检索、MCP 服务器三条进阶实现路径附带可直接运行的代码和排错方案。无论是刚接触 Claude Code 的新手还是已经在团队里推广 AI Coding 的开发者都可以照着做。1. 为什么需要跨会话通信1.1 每个会话都是一个独立的“上下文容器”Claude Code 的本质是一个跑在终端里的 AI 编程代理Agent。你可以在一个项目目录下启动它然后通过自然语言让它读代码、改文件、执行命令、跑测试。这里有一个关键机制每次启动 Claude Code 都会创建一个新会话会话之间默认是隔离的。这一点和 ChatGPT、Claude 网页版的“多轮对话”不太一样。网页聊天通常会把同一个窗口内的所有历史留在上下文里你可以不停追问模型记得住刚才聊了什么。但 Claude Code 面向的是长期项目一个会话里可能改了很多文件、跑了很多命令、产生了很多结论。如果所有历史都一直挂在上下文里token 消耗会非常夸张上下文窗口也很快会撑爆。所以 Claude Code 会按会话管理上下文一个会话有自己的“记忆边界”。会话结束后下一次启动不会自动加载上一次的全部内容。1.2 复制粘贴传递信息的痛点早期开发者最常用的“跨会话传话”方式就是新开会话后手动把上一个会话的报错、代码片段、结论贴进去。这在简单任务里勉强能用但项目一旦复杂起来问题非常明显长上下文容易丢。复制粘贴的内容超过一定长度后模型可能忽略中间部分或者只记住开头和结尾。格式被破坏。从终端复制多行日志、JSON、代码块时缩进和特殊字符经常错乱Claude 拿到之后反而理解偏了。浪费 token。把整段日志或整个文件粘进去等于让模型重新读一遍原始数据成本很高。容易漏信息。上一个会话里可能有一些隐性结论比如“这个 bug 是因为 Nginx 缓存没清”如果不写进交接文字下一个会话完全无从知晓。无法追溯。复制粘贴出来的内容是游离的没有落盘也不能检索过几天就找不到了。这些痛点总结起来就是开发者需要一种机制让不同会话之间可以共享状态、沉淀结论、无损交接。这也正是“跨会话通信”要解决的问题。1.3 跨会话通信解决什么问题从工程角度看跨会话通信的本质是上下文的持久化与恢复。它要解决的场景包括任务交接会话 A 分析完问题会话 B 接着改代码。团队协作多个开发者各自运行 Claude Code但他们需要看到同一份项目进度。阶段性沉淀把每次会话的关键决定、待办事项、技术约束保存下来让后续会话自动读取。历史检索之前某个会话里提到过一个方案现在需要快速找回来。理解了这些场景后面配置方案时就会更清楚所有跨会话通信方案本质上都是在“文件系统”和“外部工具”上做文章而不是让模型天生拥有跨会话记忆。2. 跨会话通信的几种实现思路跨会话通信没有统一的官方标准更多是开发者结合 Claude Code 的能力自己搭出来的工作流。下面按实现成本从低到高介绍三种主流思路。2.1 文件系统共享最简单的跨会话“总线”Claude Code 天然会读取项目里的记忆文件最常见的是CLAUDE.md。当你在项目根目录创建CLAUDE.md后Claude Code 每次启动都会自动读到它。我们可以利用这个机制把项目约定、当前进度、关键决策写进去。更进一步可以建立一个专门的交接目录比如.claude/handoff/每个会话结束时把结论写成一个 Markdown 文件。下一个会话开始时只需要一句话让 Claude Code 读取对应文件即可。这种方式的优点是零额外依赖纯靠文件读写。内容人类可读也能提交到 Git团队共享。不需要改 Claude Code 配置。缺点是检索效率低文件多了之后容易找不到对应结论而且依赖开发者的自觉不主动写就没有交接信息。2.2 MCP 服务器让多个会话共享同一套工具与状态MCPModel Context Protocol是 Claude Code 支持的一种工具扩展协议。通过 MCP开发者可以给 Claude Code 挂载自定义工具比如“保存笔记”“读取任务状态”“查询数据库”。核心思路是把跨会话通信变成一组工具调用由外部程序负责状态存取。举例来说你可以开发一个“会话共享状态服务器”提供一个save_note(key, content)工具和一个get_note(key)工具。两个完全不同的 Claude Code 会话都挂载同一个 MCP 服务器它们就能通过工具读写同一份共享文件或数据库。这种方式的优点是交互方式更自然Claude 可以直接调用工具而不是靠复制粘贴状态管理更规范支持结构化数据。缺点是需要额外编写服务器代码MCP SDK 的 API 也在快速迭代需要根据版本调整。2.3 外部脚本与别名检索历史会话内容的懒人方案Claude Code 会把每次会话的历史记录以 JSONL 格式保存在本地目录通常是~/.claude/projects/。这些历史文件包含了你和 Claude 的完整对话内容。借助脚本我们可以直接在终端里全文搜索历史会话再配合fzf、bat等工具快速预览。这种方式适合“回看过去某次思路”不适合做实时的状态传递但它是一个非常高效的补充。当文件交接没写、CLAUDE.md 没更新时历史检索往往能把之前的内容捞回来。3. 环境准备与基础配置在动手实现跨会话通信之前先把 Claude Code 的基础环境准备好。这里不会罗列所有安装细节重点讲清楚容易踩坑的几个点。3.1 安装 Claude Code 并完成登录Claude Code 官方主推的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后先检查版本claude --version如果提示找不到命令通常是因为 npm 的全局 bin 目录没有加入PATH。在 macOS / Linux 上可以执行export PATH$PATH:$(npm prefix -g)/binWindows 上如果遇到npm install报错优先检查 Node.js 版本是否过老再用管理员权限打开 PowerShell 重试。安装完成后在项目目录里运行claude首次启动会要求登录按提示完成认证即可。这里有一个常见坑如果在公司网络或受限环境中登录可能会失败。遇到这类问题属于账号订阅或组织策略的限制需要联系组织管理员确认订阅权限而不是盲目更换网络环境。3.2 确认会话历史存储位置安装完成后Claude Code 会在本地保存会话历史。不同操作系统下位置稍有差异但总体在用户目录下的.claude文件夹中~/.claude/全局配置文件、历史记录总目录。~/.claude/projects/按项目存放的会话历史 JSONL 文件。~/.claude/CLAUDE.md用户级别的 Claude Code 记忆文件对所有项目生效。项目级别的CLAUDE.md要放在项目根目录。Claude Code 启动时会自动读取这个文件把里面的内容当作项目长期记忆。这个文件非常适合存放跨会话的稳定信息比如技术栈约定、目录结构、常见命令、开发规范。3.3 初始化项目记忆文件这里给出一个CLAUDE.md的基础模板按自己的项目情况修改# 项目环境说明 - 技术栈Node.js 18 Express 4 SQLite - 启动命令npm run dev默认端口 3000 - 测试命令npm test - 项目结构src/ 存放源码tests/ 存放测试docs/ 存放文档 # 开发约定 - 数据库迁移脚本放在 migrations/ 目录命名格式YYYYMMDD_描述.sql - 调用第三方 API 时必须通过 src/services/httpClient.js 统一发出 - 修改公共组件前先在 docs/decision-records/ 下追加 ADR 文档 # 当前进度 - [x] 完成用户登录模块 - [ ] 完成订单导出功能 - [ ] 补充接口压测脚本这个文件写好后每次启动 Claude Code 都会自动看到。它相当于一个“项目级长期记忆库”跨会话通信的第一步就是把它用起来。4. 实战通过共享文件实现跨会话上下文传递4.1 创建项目交接目录与模板先创建目录mkdir -p .claude/handoff在.claude/handoff/下放一个模板文件template.md方便每次交接时照格式填写# 任务交接任务名称 - 日期YYYY-MM-DD - 当前状态进行中 / 已完成 / 有阻塞 - 会话目标本次会话要解决什么问题 - 关键结论分析得出的核心结论 ## 已完成 1. ## 待办 1. ## 遗留问题 / 风险 1. ## 相关文件 -4.2 在会话 A 中生成交接清单假设现在有一个实际任务给一个 Node.js 项目中添加一个“慢查询统计模块”。你在会话 A 中让 Claude Code 完成了代码分析和初步实现临退出前让 Claude 把进度写入交接文件请阅读当前项目的 src/ 目录分析现有数据库访问方式然后完成一个慢查询统计模块记录执行时间超过 500ms 的 SQL并写入日志文件。 完成实现后把以下内容写入 .claude/handoff/2025-04-01-slow-query.md 1. 当前进度 2. 已修改的文件列表 3. 慢查询判断逻辑的核心设计 4. 下一步待办会话 A 结束后.claude/handoff/2025-04-01-slow-query.md可能长这样# 任务交接慢查询统计模块 - 日期2025-04-01 - 当前状态进行中 - 会话目标实现慢查询统计模块 - 关键结论使用拦截器统一包装数据库查询避免在每个 DAO 中手工埋点 ## 已完成 1. 新增 src/utils/slowQueryLogger.js 2. 在数据库连接池配置中接入慢查询拦截器 3. 慢查询判断逻辑duration 500ms记录 SQL、执行时间、参数摘要 ## 待办 1. 需要为慢查询日志添加轮转避免单文件过大 2. 建议补充单元测试 ## 遗留问题 / 风险 1. 参数摘要可能包含敏感字段需要过滤 ## 相关文件 - src/utils/slowQueryLogger.js - src/config/database.js这个文件已经变成了会话 A 和会话 B 之间的“通信协议”。它不是聊天记录粘贴而是一份结构化、可检索、可版本化的交接文档。4.3 在会话 B 中读取交接清单新开一个 Claude Code 会话只需一句话请先读取 .claude/handoff/2025-04-01-slow-query.md了解慢查询统计模块的进度然后继续完成剩余待办为慢查询日志添加轮转并补充单元测试。这样的话Claude 不需要依赖任何“上一个会话”的记忆仅凭文件就能把上下文恢复得七七八八。如果交接文件里信息足够完整它甚至能直接开始干活。这看起来非常简单但它才是跨会话通信最核心、最稳定的实践。很多团队用 Claude Code 做大型项目时最终沉淀下来的并不是什么复杂工具而是一套良好的交接文件规范。4.4 用脚本快速检索历史会话除了主动写交接文件我们还可以从历史会话里被动捞信息。Claude Code 的会话记录是以 JSONL 格式保存在~/.claude/projects/下的每一行是一条消息。下面这个脚本可以扫描所有历史记录提取用户和助手的文本内容并用fzf做交互式搜索。先确认已经安装了jq和fzf# macOS brew install jq fzf # Ubuntu / Debian sudo apt update sudo apt install jq fzf然后创建一个脚本文件例如~/bin/claude-search.sh#!/usr/bin/env bash # 用法claude-search.sh [搜索关键词] # 功能搜索 Claude Code 历史会话内容并预览匹配到的对话片段 PROJECT_DIR${HOME}/.claude/projects if [[ ! -d ${PROJECT_DIR} ]]; then echo 未找到 Claude Code 历史目录: ${PROJECT_DIR} exit 1 fi # 扫描所有 jsonl提取文本内容 find ${PROJECT_DIR} -name *.jsonl -print0 | while IFS read -r -d file; do jq -r select(.type user or .type assistant) | .message.content[]? | if .type text then .text else empty end ${file} 2/dev/null done | fzf --preview bat --styleplain --coloralways {} --preview-windowright:60%给脚本加执行权限chmod x ~/bin/claude-search.sh使用时直接运行脚本~/bin/claude-search.sh脚本会读取所有历史记录并喂给fzf。你可以输入关键词比如“慢查询”然后上下选择查看匹配片段。虽然这里没有做到严格的“按会话分组”但对于快速找回某段思路已经很有帮助。如果你更关注文件粒度也可以优化脚本把匹配到的句子连同所属的会话文件名一起输出方便定位到具体历史记录文件再用编辑器打开完整内容。5. 进阶用 MCP 构建跨会话共享状态文件交接很适合“人与人配合”的工作流但对于重度用户来说仍然需要手动创建文件和提示 Claude 读取。如果想让多个会话之间的通信更自动、更结构化可以考虑 MCP 方案。5.1 MCP 的作用与适用边界MCP 提供了一套让 Claude Code 与外部程序交互的标准协议。你可以把它理解为“给 Claude 加插件的标准接口”。Claude 在对话中如果需要某个外部能力会通过 MCP 调用你注册的工具。在跨会话场景中MCP 的价值是把“读取共享状态”和“保存共享状态”变成工具调用。例如会话 A 调用save_note保存一条任务进度会话 B 在同一个项目里调用get_note读取最新任务进度。两个会话之间不需要复制粘贴只需要同时连接同一个 MCP 服务器。适用边界也很明显MCP 适合频繁、结构化的状态读写。如果你只是想简单传一段话写个 Markdown 文件就够了如果你希望 Claude 能像调用函数一样读写状态或者把状态存到数据库里再用 MCP。5.2 实现一个轻量级共享状态 MCP 服务器下面使用modelcontextprotocol/sdk写一个极简的共享状态服务器。它的作用是提供两个工具save_note(key, content)保存一条笔记到项目.claude/shared/目录。get_note(key)读取对应笔记内容。创建项目目录并初始化mkdir claude-shared-mcp cd claude-shared-mcp npm init -y npm install modelcontextprotocol/sdk创建index.jsimport { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import fs from node:fs/promises; import path from node:path; const server new McpServer({ name: session-shared-state, version: 0.1.0 }); // 共享目录当前项目下的 .claude/shared const SHARED_DIR path.join(process.env.PWD || process.cwd(), .claude, shared); server.tool( save_note, { key: { type: string }, content: { type: string } }, async ({ key, content }) { await fs.mkdir(SHARED_DIR, { recursive: true }); const filePath path.join(SHARED_DIR, ${key}.md); await fs.writeFile(filePath, content, utf8); return { content: [{ type: text, text: 笔记已保存${filePath} }] }; } ); server.tool( get_note, { key: { type: string } }, async ({ key }) { try { const filePath path.join(SHARED_DIR, ${key}.md); const content await fs.readFile(filePath, utf8); return { content: [{ type: text, text: content }] }; } catch (error) { return { content: [{ type: text, text: 未找到笔记${key} }] }; } } ); const transport new StdioServerTransport(); await server.connect(transport);需要注意MCP SDK 的server.tool写法和工具参数的 schema 格式会随 SDK 版本变化。上面的代码是当前较常用的写法如果你安装的版本不同请以官方示例为准。5.3 在 Claude Code 中注册与测试在 Claude Code 中可以把会话级、项目级或全局的 MCP 服务器加进来。这里用项目级方式测试claude mcp add --scope project session-shared -- node index.js运行时可以先让会话 A 执行请使用 save_note 工具把这条内容保存为 progress已完成用户登录模块下一步做订单导出。然后在会话 B 中执行请使用 get_note 工具读取 progress 笔记并告诉我下一步该做什么。这样两个会话就通过同一个 MCP 服务器完成了状态传递。更进一步你可以在save_note里加上时间戳、操作人、版本号或者把数据改存到数据库里实现更复杂的共享状态管理。6. 常见问题与排查思路在配置和使用 Claude Code 跨会话功能时经常会遇到下面这些报错或异常。这里整理成表格方便快速排查。问题现象常见原因解决思路执行claude提示 command not foundNode.js 全局 bin 目录不在 PATH 中重新安装 Node.js 并确认 npm 全局目录macOS/Linux 手动添加npm prefix -g到 PATHWindows PowerShell 安装 Claude Code 报错Node.js 版本过老或权限不足升级 Node.js用管理员 PowerShell 重跑安装命令运行时报could not locate the claude cli on pathVSCode 或其他 IDE 中找不到 claude 可执行文件确保claude命令在系统 PATH 中可用重启 VSCode 或终端终端显示乱码终端编码与 Claude Code 输出编码不一致Windows 终端执行chcp 65001切换到 UTF-8macOS 终端检查 locale 设置your organization has disabled claude subscription access for claude code组织订阅策略禁止使用 Claude Code联系组织管理员开通权限或者使用自己的订阅账号提示your limits are temporarily boosted/ 周限额提示账号触发了使用限制动态调整降低单次任务复杂度避免一次性向 Claude 塞入大量上下文等待限制恢复会话历史很多claude-search.sh搜索很慢JSONL 文件数量过多脚本每次全量扫描增加索引机制按日期或项目路径过滤后再搜索MCP 注册后 Claude 调不到工具MCP 服务器启动失败或 schema 格式不匹配先用claude mcp list查看注册状态手动运行node index.js测试进程是否正常补充一点如果你的历史搜索脚本匹配不到内容先打开/Users/你/.claude/projects/下对应的 JSONL 文件确认type字段和message.content的结构。Claude Code 不同版本的历史记录格式略有差异脚本里的jq路径需要按实际格式调整。7. 工程实践与建议跨会话通信的核心不是某一条命令或某个工具而是建立一套“会话之间如何协作”的团队约定。下面这些建议来自实际项目中的经验按重要程度排列。7.1 把 CLAUDE.md 当“项目宪法”维护CLAUDE.md是影响所有会话的基础记忆文件。它应该保持稳定、精简、覆盖高频信息。不要什么内容都往里塞否则 Claude 每次启动都要读大量无关信息既浪费 token也会稀释重点。建议按“稳定信息”和“动态信息”分层CLAUDE.md存放稳定信息环境、目录结构、命令、规范。.claude/handoff/存放动态信息每次任务进度、交接记录。需要长期留存的决策移到docs/decision-records/并在CLAUDE.md中只保留索引。7.2 明确每个会话的边界开始一个会话前先在脑子里定义好这个会话要做完什么。每次会话结束前主动让 Claude 生成交接总结。可以在CLAUDE.md中加一条规则比如# 会话结束规则 当会话目标已完成或用户准备退出时自动把当前进度写入 .claude/handoff/ 下以日期命名的 Markdown 文件。这样 Claude 到点会自动写交接文档不需要每次手动提醒。注意CLAUDE.md中的指令并不是 100% 强制执行的但在大多数情况下模型都会遵守这类清晰约定。7.3 避免复制大段日志优先保存结论很多开发者想让新会话快速理解问题会把一长串日志直接粘贴给 Claude。这个习惯在跨会话场景中很浪费日志属于原始数据模型需要重新推理一遍。大量日志会挤占上下文窗口影响后续任务执行。更好的方式是在会话 A 中就提炼出结论例如“错误发生在src/utils/format.js第 23 行原因是Intl.DateTimeFormat不支持传入空字符串”然后把结论写入交接文件。会话 B 读取结论后只在必要时打开源码文件确认细节而不是重新读一遍日志。7.4 MCP 服务器要控制权限边界如果你使用 MCP 做跨会话共享一定要控制 MCP 服务器的权限范围。上面的示例只是读写项目目录这是相对安全的。但如果你的 MCP 服务器能执行 SQL、访问线上接口、操作文件系统就必须加上鉴权逻辑。生产环境里建议遵循最小权限原则MCP 服务器只能访问指定目录、指定数据库表不能拥有整个系统的读写权限。7.5 定期清理和归档交接文件交接文件多了以后.claude/handoff/会变得混乱。建议每周或每个迭代结束之后把已完成的交接文件归档到docs/handoff-archive/。删除已经失效的临时笔记。把重复出现的经纬度信息提炼到CLAUDE.md。这样既能保证历史可追溯又不会让 Claude 每次扫描目录时被大量无关文件干扰。8. 总结与下一步学习建议跨会话通信不是 Claude Code 自带的一个开关而是一套围绕“上下文持久化”搭建的工作流。文件系统共享、历史检索脚本、MCP 服务器这三条路径成本从低到高灵活度也逐级提升。实际项目中建议先从CLAUDE.md和.claude/handoff目录用起来跑通后再决定是否需要上 MCP。如果需要继续深入可以按下面顺序学习先熟练维护CLAUDE.md让每个会话自动获得项目基础信息。再建立交接文档模板让每次会话结束都能沉淀出结构化结论。然后编写历史检索脚本解决“之前那个方案在哪说过”的问题。最后研究 MCP SDK把高频的跨会话状态读写封装成工具。另外提醒一句Claude Code 的版本更新很快MCP 的 API、CLI 参数、历史记录格式都可能变化。动手配置时如果发现某个命令不存在或格式对不上优先查看本地版本对应的官方文档不要强行照搬网上旧命令。如果这篇内容对你理解跨会话通信有帮助建议先创建一个交接目录跑一次完整流程让会话 A 写交接文件再让会话 B 读取并继续任务。只有亲手跑通一次才能真正告别复制粘贴式的上下文搬运。
