DeepDojo.AI发布 2026-11-15English

Claude Code 换了会话,之前的约定就忘了

Claude CodeAI 编程

会话刚开始的第一轮,你和产品经理核对过一句关键要求:出于第三方合同限制,所有请求的超时时间必须锁定在 30 秒。当时大家聊得热火朝天,谁也没想起来把这句话写进 CLAUDE.md 或项目配置。

几天后会话太长了,你用一个裁剪历史的脚本删掉了前半段对话。新会话只继承了后面的代码细节,完全不知道这条红线。等它下一次为了性能把超时改成 5 秒,问题就悄无声息地进来了。

继续一个长任务时,Claude Code 需要知道当前目标、已经试过的方法和下一步。会话历史提供了这些信息,同时也保留着旧目标、失败尝试和临时讨论。新会话、压缩、交接文件、分支、裁剪历史,每一种方法都在替你决定:哪些事实带进下一段工作,哪些留在原地。

所以换会话之前,先回答两个问题:

  • 新一轮工作依赖哪些事实,哪些是只说过一次、别处都没记录的硬约束;
  • 需要的是一份摘要、一份交接文件,还是原始对话本身。

想清楚之后再选工具:同一任务、历史整体有用就压缩;只需几个关键事实就写交接文件;想保留原路线再试新方案就开分支;要裁剪历史,先预览被删掉的部分,把唯一的约束搬进文件。

01 先判断要不要换会话

长会话常见的异常包括:回答明显变慢,重复已经解释过的内容,抓不住当前重点,把旧任务的限制带进新问题,或者需要你反复纠正同一个方向。

变慢这一条要多看一眼。很多人一看到吐字变慢、停顿变长,第一反应就是“肯定聊太长、上下文撑爆了”。但首个字符出来得慢,也可能是远端服务在高峰期,或者本地后台有条测试命令卡住吃满了 CPU,这时敲 /compact 解决不了问题。

先看终端卡在哪个阶段,再用 /context 看看 token 占了多少。上下文确实庞大、旧话题开始干扰当前思路,压缩或交接才有意义;如果上下文才用了 20%,后台进程却在报错,就去排查本地环境。

确认是会话本身的问题后,按任务状态选:

当前任务还在继续吗?
  ├─ 否:新会话或 /clear
  └─ 是
      ├─ 历史整体仍有用:/compact
      ├─ 只需保留关键事实:handoff 文件或 Plan 模式交接
      ├─ 想保留原路线并尝试新方案:/branch 或 --fork-session
      └─ 近期原始对话重要、早期历史可舍弃:half-clone

这里的 handoff 是交接说明,half-clone 是只保留后半段历史的第三方做法。刚开始用时,先掌握新会话、/compact 和交接文件;需要比较方案或保留原始细节时,再考虑分支与裁剪。

新会话不会自动带上原来的讨论。有人对一个会话格外执着,扯了三四天也舍不得关,里面积压了大量早就过时的草稿。不妨把会话当作当前任务的工作空间:后续任务还要继续,就把核心结论整理成一份交接文档,然后开一个干净的会话。整理过的历史,能让它更集中地处理当前任务。

02 交接文件写清走不通的路

长任务暂停、换会话或交给协作者时,可以在项目里建一个 HANDOFF.md:

请在当前项目中创建或更新 `HANDOFF.md`。
写清当前目标、已经完成的内容、验证有效的方法、失败路径、关键文件和下一步。
新的 Claude Code 会话要能从这个文件定位下一步,再读取关键文件与验证记录,核对现状后继续。

要让接手者知道怎么继续,交接至少写清六部分:

部分要保存的状态
Goal当前要完成的具体结果与边界
Current Progress已完成内容和当前停点
What Worked已验证的方法、命令和结论
What Didn't Work失败方案、失败原因和已经排除的路径
Key Files文件职责、改动状态和相关测试
Next Steps下一步最小动作、顺序与验证方式

很多人写交接图省事,随手一句“转写模块还有问题,继续修”。新会话收到这句话,仍然不知道从哪里接手:到底什么问题,怎么复现,你刚才花一个小时试过哪些走不通的路?

交接里没写清已经排除的路径,新会话一上来就会把你踩过的坑原样再踩一遍。把跑失败的测试命令、终端里的现场报错、试过但被证伪的方案逐条列出来,新会话才能沿着这些证据处理剩下的问题。

一份填好的 HANDOFF.md 片段长这样:

## Goal
修复转写模块在长音频(>30 分钟)上无响应的问题;不改输出格式。

## Current Progress
- 已复现:`pnpm test transcribe -- --fixture long.mp3` 在 12 分钟处挂起
- 停点:怀疑流式读取未正确结束,未验证

## What Worked
- 短音频路径正常;问题只出现在流式分支(`src/transcode/stream.ts`)

## What Didn't Work
- 增大缓冲区:无效,已还原(见 commit a1b2c3)
- 换成同步读取:可行但内存翻倍,不符合约束

## Key Files
- `src/transcode/stream.ts`(嫌疑文件)
- `tests/transcode/stream.test.ts`(复现用例,已加 `--timeout`)

## Next Steps
1. 在 `stream.ts:87` 的 while 循环加日志,确认退出条件
2. 复跑复现命令;如果挂起点变化,更新本文件

需要更严格的版本时,可以补一句:文件已存在就先读取再更新,并记录关键文件路径、已运行的命令、观察结果、失败原因和下一步验证。新会话只需接收:

请读取 `path/to/HANDOFF.md`,核对当前项目状态,然后继续下一步。

接手时先核对复现命令、文件和当前状态。接手者能据此执行一个明确的下一步,交接才算有效;只写“先复现”还不够。

小黑从旧会话向新会话交接当前目标、已验证事实和下一步,让任务状态能够继续

03 压缩、计划交接和交接文件

同一任务继续推进时,可以在原会话里压缩,也可以整理材料后换一个上下文。它们保存信息的方式不同:

方法保留方式适用状态
/compact系统总结当前对话任务延续,历史整体仍有价值,需要快速释放空间
Plan 模式交接把继续任务所需的信息整理成计划任务正在推进,需要清爽的上下文,暂时不写正式文件
handoff 文件把任务状态保存为项目文件长任务暂停、跨会话或跨协作者继续,需要人工检查和长期保存

用 /plan 或 Shift+Tab 进入 Plan 模式,然后要求:

请整理一个全新 agent 继续本任务所需的上下文。
它看不到当前历史,所以计划要写清目标、关键文件、已验证方法、失败路径、风险和验证步骤。

Plan 模式在这里负责整理交接内容;换到新会话时,还要把计划带过去,并确认新会话已经读到。需要暂停、审查或跨人交接时,handoff 文件更便于保存和检查。两种方式都要写出当前停点,接手者才知道“剩余工作”具体指什么。

交接里要分开假设与结论。“怀疑流式读取未结束”就照原样写,别写成“根因是流式读取”。新会话可以用相同的复现步骤检查这个假设;如果代码或输入已经变了,先核对现状。摘要可以省去中间对话,待验证的判断仍要标成待验证。

04 分支:保住原路线,再试另一条

方案改到一半舍不得扔,又想试一种完全不同的实现路线?优先用 Claude Code 自带的分支:

/branch try-streaming-approach

它会复制到目前为止的对话,把你切进新分支,原会话原封不动,随时可以用 /resume 回去。名字可以省略,省略时用对话的第一条提问命名。

有一点要记住:分支分开的只是对话历史,磁盘上的代码文件还是同一份。两个窗口对着同一个目录改代码,照样会互相打架;真要并行改代码,得用 Git worktree 给每条路线一个独立的工作目录。

从命令行启动时,也可以创建新的会话身份:

claude -c --fork-session
claude -r --fork-session
  • -c 继续最近的会话;
  • -r 从历史中选择;
  • --fork-session 在继续或恢复的基础上创建新的会话 ID。

Claude Code 会话文档列出了分支继承什么:对话历史会复制过去;用 /branch 时,本会话里“允许本次会话”的权限授权继续有效;用 --fork-session 启动的新进程则要重新批准。

经常使用时,可以写个 shell 函数把 --fs 展开为 --fork-session,之后用 claude -c --fs 启动。这只是缩短输入,会话身份的创建方式不变。

05 裁剪历史前先预览

/branch 和 --fork-session 是内置能力。clone 和 half-clone 来自第三方仓库 ykdojo/claude-code-tips 提供的脚本或 dx 插件,用来复制、截断本地历史;安装 Claude Code 后它们并不存在,脚本参数和标记要以实际安装的版本为准。

完整 clone 会复制全部历史。早期讨论已经没用、最近的对话仍包含大量细节时,可以用 half-clone 只保留后半部分真实消息。它适合三项条件同时成立的场景:

  1. 当前任务还没结束;
  2. 近期的原始对话比自动摘要更有价值;
  3. 前半段的约束已经过时,或者能从其他材料恢复。

常见入口是 half-clone-conversation.sh 脚本,或安装 dx 插件后的 /dx:clone、/dx:half-clone。使用 clone 脚本前,先读准当前的会话 ID 和项目路径,再找到实际安装的脚本:

tail -1 ~/.claude/history.jsonl | jq -r '[.sessionId, .project] | @tsv'
find ~/.claude -name "clone-conversation.sh" 2>/dev/null | sort -V | tail -1

开头那条 30 秒的超时约束,就是在这一步丢的。裁剪之前先做一次预览:

<script-path> --preview <session-id> <project-path>

预览时确认三件事:

  • 第一条保留下来的消息仍能说明任务背景;
  • 最后一条消息对应当前的会话状态;
  • 被舍弃的部分里,没有唯一一份的硬约束、验证证据或关键决策。

如果准备舍弃的早期对话里,藏着整个工程唯一一份关于架构决策、安全阈值或业务边界的结论,先把它们摘进项目记忆或说明文档,确认新会话能从文件里读到,再裁剪历史。确认后执行脚本,再恢复它返回的新会话:

<script-path> <session-id> <project-path>
claude --resume <new-session-id>

忘了 ID 时,用 claude -r 查找带 [HALF-CLONE 时间] 标记的会话。

如果你已经准备好一个检查上下文的脚本,可以用 Stop hook 调用它,在超过阈值时提醒。Stop hook 在 Claude 每次完成一轮回复时运行,下面只展示接入配置,阈值判断由脚本实现:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/scripts/check-context.sh"
          }
        ]
      }
    ]
  }
}

接入前先检查脚本实际读取和写入什么,把访问范围限定在必要的文件。只做提醒的脚本,就让它只提醒:阻止回复结束或自动裁剪会话,都会绕过上面的预览和确认步骤。

06 从历史记录里找回旧方案

需要找回旧方案、排障结论、提示词,或者某段只在对话里出现过、没另存的内容时,可以搜索本地历史。据会话文档,Claude Code 默认把每个会话存成 ~/.claude/projects/<项目>/<会话 ID>.jsonl,其中项目目录名是工作目录路径,非字母数字字符都换成了 -。例如:

/Users/yk/Desktop/projects/claude-code-tips
→ ~/.claude/projects/-Users-yk-Desktop-projects-claude-code-tips/

.jsonl 是每行一条 JSON 记录。下面命令里的用户名、项目路径、... 和会话 ID 都要换成自己的实际值。按关键词和时间查找:

grep -l -i "reddit" ~/.claude/projects/-Users-yk-Desktop-projects-*/*.jsonl
find ~/.claude/projects/-Users-yk-Desktop-projects-*/*.jsonl -mtime 0 -exec grep -l -i "keyword" {} \;

只提取用户消息:

cat ~/.claude/projects/.../conversation-id.jsonl | jq -r 'select(.type=="user") | .message.content'

官方提醒,这些记录的字段格式属于内部实现,会随版本变化,直接解析的脚本可能在某次更新后失效;要长期依赖会话数据时,改用 /export 导出。

设想你要找回三天前只在对话里出现过的构建配置:

  1. 用 ls ~/.claude/projects/ 定位当前项目的历史目录。
  2. 用 grep -l -i "webpack cache" <目录>/*.jsonl 缩小到相关会话。
  3. 用 jq 提取消息,核对用户的确认和最终配置,避免取到被否决的草稿。
  4. 确认适用于当前项目后,保存到 build.config.js,此后从文件维护。

恢复或加工历史前,要同时确认会话 ID 和项目路径。当前 shell 的目录可能已经变了,不能据此推断原会话属于哪个项目。历史记录可能包含项目代码、内部信息和用户输入,搜索范围尽量收窄;要外发时,先截取需要的部分并脱敏。

07 把硬约束搬进 CLAUDE.md

30 秒超时那样的约束,最稳妥的归宿是一个每次启动都会加载的文件。项目根目录和用户级的 CLAUDE.md 在启动时加载;子目录里的 CLAUDE.md 在 Claude 读写该目录下的文件时才按需加载,详见 Claude Code 记忆文档。

适合留在 CLAUDE.md 里的有三类:

  • Claude Code 反复容易违反、每次都要遵守的规则;
  • 当前项目的硬约束;
  • 进入项目时必须知道的最小背景。

很多团队的 CLAUDE.md 只增不减:半年前某个临时脚手架的约定、早已废弃的打包命令、长篇的架构哲学全混在一起。这不仅浪费上下文,互相打架的旧规矩还会让 AI 写代码时左右为难。只针对特定模块的知识,移进对应目录的规则,或做成按需调用的 Skill;规则越精,执行时越能命中。哪些内容该放 CLAUDE.md、哪些该做成 Skill,哪些流程值得用 Claude Code 自动化里有一张对照表。

可以直接让它审查:

请审查当前 `CLAUDE.md`,找出重复、过时、冲突、过于宽泛或应该移到 Skill 的内容,并说明保留、收窄、迁移或删除的理由。

会话历史也能拿来检查规则是否真的被遵守。第三方的 review-claudemd 技能会抽取最近 15 到 20 个会话,对照真实使用情况和现有规则。先定位项目的历史目录:

PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lt "$CONVO_DIR"/*.jsonl | head -20

这段命令只替换了斜杠,路径里有空格、下划线或点号时,按上面的命名规则手动核对目录名。

分析结果可以分成四类,分别处理:

类别含义例子与处理
Instructions violated已有规则经常没被遵守要求中文提交说明,执行却反复用英文:检查加载、适用范围和实际指令,别直接假定移到开头就能解决
Suggested additions - LOCAL只适用于当前项目的稳定规则项目反复要求按受影响文件运行测试,确认稳定后存到项目层
Suggested additions - GLOBAL跨项目都适用的个人规则多个项目都要求改动前列出文件清单,存为个人偏好
Potentially outdated过时、重复或冲突的内容技术方案已迁移,删除或更新旧要求

每条结论都要说明依据和处理位置。审查每条规则时,问它是否仍然有效、是否每次进入项目都要遵守;只服务某一次任务的要求,放进对应的文档或任务记录更合适。

08 按要保留的信息选方法

最后用三个问题收拢:当前会话和当前任务是否仍然一致?哪些历史信息是继续工作不可缺少的?需要保留摘要、任务状态、完整历史,还是某个决策分叉点?

需要保留的内容合适方式
不需要旧历史新会话或 /clear
同一任务的整体摘要/compact
可检查、可长期保存的任务状态handoff 文件
立即交给清爽上下文继续的计划Plan 模式交接
原路线与新路线并存/branch 或 --fork-session
最近一段原始对话half-clone
过去某次的方案或证据搜索 ~/.claude/projects/

开工时留意状态栏上的上下文比例,能更早发现该换会话的时机,Claude Code 状态栏和多账号配置讲了怎么配。

先确认要保留什么,再选工具,就知道压缩、交接或分叉之后还剩下哪些信息。那条 30 秒的约束,只要在裁剪之前被写进文件,换多少次会话都还在。