Claude Code /cd 切目录别丢提示缓存：v2.1.169 实测 + 3 个翻车点
(updated )
claude-codeclaudetutorialprompt-cache

Claude Code /cd 切目录别丢提示缓存：v2.1.169 实测 + 3 个翻车点

2026 年呼声最高的 Claude Code 功能，悄悄在 v2.1.169 上线了，多数人还不知道它切目录时能把提示缓存保住，不是清掉重来。

如果你以前每次想去 git worktree 或者隔壁仓库工作，都得退出 Claude Code 重启——这套仪式从 2026-06-08 起可以扔掉了。新出的 /cd 命令让会话中途切到任何目录，前缀缓存还能活着。对 Claude Opus 4.8（输入 5 美元/M token、缓存读 0.5 美元/M token）来说，这意味着原本要重发的那一堆上下文打了一折。

但”保住缓存”这句话带 3 个星号。这篇把可验证的机制、操作步骤、3 个会让缓存悄悄失效的翻车点都讲清楚。

/cd 能干什么、不能干什么

想跳过对比表先把环境配上，可以直接看下一节的操作步骤；如果还在用 Anthropic 官方 API 经常撞额度，可以顺手把 base URL 切到 ofox：Claude Code 配置 ofox.ai 指南目前有 8 折充值券，新用户首次 ≥ 50 美元再叠 15% bonus，自带 5 美元试用额度，UTM 链接走 claude-code-cd-zh。

能做不能做
一条命令切到任意目录切到当前用户没有读权限的目录
保留所有历史对话、tool 历史、plan-mode 笔记把旧目录的 CLAUDE.md “替换”掉——新的是追加，两份并存
大多数情况下下一轮还能命中 cache_read_input_tokensHaiku / Vertex / 自定义 ANTHROPIC_BASE_URL 配上新目录 MCP 不一样时，会触发 tools 层重建
/cd + /add-dir 配合跨目录编辑在后台 agent 里用（截至 v2.1.172 是交互式 CLI 专属）
在 git worktree 之间切来切去不丢 plan-mode 笔记在 Claude Code < v2.1.169 用——先升级

30 秒心智模型：/cd 是”换个屋子工作，已经说过的话全部保留”，/add-dir 是”留在原屋子，再开一扇能看到隔壁的门”，Bash 里的 cd 两个都不是——它只改一次 shell 调用，下一次又回到原点。

什么时候用 /cd、什么时候别用

该用 /cd

  1. 已经规划到一半，发现真代码在 .worktrees/feature-x/ 里，根目录是空的
  2. 在 backend/ 和 mobile/ 两个仓库之间排错，想跳过去又不丢 cache_read_input_tokens 折扣
  3. CLI 从 /Users/you/ 启动，项目实际在 /Users/you/projects/api/——一条命令省一次重启

别用 /cd

  1. 只想读第二个目录的文件，工作根不想动——这是 /add-dir 该干的活，缓存保留得更完整（连 system 块都不碰）
  2. 在写非交互式脚本（claude -p "..."）——启动进程时把目标目录当 CWD 传进去
  3. 新目录的 .mcp.json 明显不同，而且用的是自定义 ANTHROPIC_BASE_URL 或者 Haiku/Vertex 这种不支持 tool search 的链路——这种组合缓存反正要重建，干脆重启换个干净状态。如果只是 CLAUDE.md 不一样，/cd 会把它追加成消息，缓存还活着，不用纠结

止损规则：目的只是”在另一个仓库读一个文件”，停在 /add-dir <dir> + Read /absolute/path/to/file 就够了，用 /cd 反而要付部分失效成本。要在那边写文件，/cd 才划算。

系统要求

要求怎么核
Claude Code v2.1.169 或更新claude --version
交互式 CLI 会话（不是后台 agent）用 claude 启动的、有交互 REPL
操作系统层面对目标目录有读权限ls <target> 不报错
目标目录要么没 CLAUDE.md，要么跟当前根的一样diff CLAUDE.md <target>/CLAUDE.md
同样的 .mcp.json 和 .claude/settings.json（想保缓存的话）diff -r .claude/ <target>/.claude/

低于 v2.1.169 先升级：npm i -g @anthropic-ai/claude-code，CLI 启动时会自动检测新版本。

一步步切目录不丢缓存

Step 1：确认当前根目录

大多数会话的提示前缀那行会显示工作根。没显示就直接问 Claude which directory are you in?，它会从工具上下文里打出绝对路径。预期结果：一个指向当前会话根的绝对路径。

Step 2：用绝对路径跑 /cd

> /cd /Users/you/projects/api/.worktrees/feature-payments

Claude Code 会确认会话已经移动。用绝对路径——相对路径像 /cd ../mobile 也能跑，但会基于当前根来解析，连续切两三次就开始绕晕。

Step 3：下一轮消息看缓存命中

发任意消息，盯着 API 报的 cache_read_input_tokens 和 cache_creation_input_tokens。/cost（别名 /usage）只展示会话总花费和套餐用量，不细到每轮缓存命中。每轮实时看的话，官方文档推荐写一个 statusline 脚本 读 current_usage 对象：

cache_read_input_tokens: 47,832    ← 缓存活着
cache_creation_input_tokens: 142   ← 只写入了增量

cache_read_input_tokens 非零、且接近 /cd 前的前缀大小，说明缓存保住了。读为 0、写很大，就说明 cache-key 路径上有东西变了——下一节挨个排。

Step 4：当作从新目录启动 CLI 那样继续工作

Glob、Grep、Bash 都基于新根定位，写文件落到新树里，plan-mode 缓冲区、todo 列表、对话历史全部带过去。没有”会话重置”这一步。

跑 /cd 时常见的显式报错（以及背后含义）

显式失败容易认。静默失败——/cd 返回成功但缓存其实死了——放下一节专门讲。

现象可能原因快速修法
/cd: command not found（或者提示未知斜杠命令）Claude Code 还在 v2.1.169 之前npm i -g @anthropic-ai/claude-code 然后重启
/cd <path> 后报 Permission denied进程用户对目标目录没读权限chmod 或者切到有权限的用户跑 Claude Code
No such file or directory路径写错，或者相对路径锚错根了改成绝对路径重跑，shell 历史里 tab 补全省事
/cd 没报错，但 Glob/Grep 还是命中旧目录你跑的是 Bash 里的 cd，不是 /cd——两个不一样补上前面的斜杠重跑；Bash cd 只影响一次 shell 调用
下一轮 cache_creation_input_tokens 飙高而不是 cache_read_input_tokens 命中MCP server 集合变了且 tools 没走 deferred（Haiku、Vertex、自定义 base URL），或者两个目录 PreToolUse hook 不一样看下一节 Edge Case 2
/cd 后 Bash 命令时好时坏之前的 /add-dir 授权和新工作根有重叠看下一节 Edge Case 3
/cd 接受了，但后台 agent 还往旧根里写后台 agent 的工作目录来自项目 settings，/cd 是交互式专属在项目 settings 里改 additionalDirectories

3 个让缓存静默失效的翻车点

下面这 3 个是大多数人踩的坑。每一种从技术上都是”缓存应该失效”——但”保留提示缓存”的官方说法容易让人以为是普适的，实际并不是。

翻车点 1：新目录 CLAUDE.md 不同（其实没你想的严重）

大多数人最担心的是这一种，但 /cd 处理得很巧。按官方 Claude Code /cd 命令参考，新目录的 CLAUDE.md 会作为一条消息追加到对话里，不会重建系统提示：

/cd ~/projects/mobile     ← CLAUDE.md 不一样
→ tools 缓存：    HIT
→ system 缓存：   HIT
→ messages 缓存：HIT（已有轮次不变，新 CLAUDE.md 作为追加内容）
+ 新 CLAUDE.md 内容触发一次少量 cache write

代价是新 CLAUDE.md 落到对话层而不是（已缓存的）系统层，根据文件大小要付几百到几千 token 的 cache write 费，但已缓存的前缀完整保留。你最担心的”tools 缓存丢了”在这里不会发生。

怎么修：缓存这块不用修——设计本身就是保留的。真正要担心的是语义：给项目 A 写的规则套到项目 B 上可能误导 agent。把跨项目通用规则放 ~/.claude/CLAUDE.md 这种用户级位置，项目级文件留给真正项目专属的内容。

翻车点 2：MCP server 不同——只在 tool search 关掉时才失效

这个翻车点是有条件的。Claude Code 官方提示缓存文档里有一句关键：deferred tools（受支持模型的默认形态）在 MCP server 连接/断开/工具列表变化时只是追加新内容，已缓存的前缀活着。只有当 tools 加进前缀本身——也就是 Haiku 模型、Vertex AI、或者自定义 ANTHROPIC_BASE_URL 网关的场景——MCP 变化才会全量重建。

你要是走 ofox.ai 这类自定义 base URL，按 MCP 变化会失效来准备：

/cd ~/projects/data-pipeline    ← 多了一个 postgres MCP server，走网关路由
→ tools 缓存：MISS  （新工具定义没走 deferred）
→ system 缓存：MISS （连锁失效）
→ messages 缓存：MISS （连锁失效）

10 万 token 的前缀，写入大概 0.625 美元，读只要 0.05 美元——比干净 /cd 贵 12 倍左右。直连 Anthropic + deferred tools 时，同样这条 /cd 基本是免费的。

怎么修：直连 Anthropic 且模型支持就没事；走自定义网关的话，要么在常来回切的项目之间统一 MCP server 列表，要么把共用 server 提到用户级 ~/.claude/settings.json，这样工作根换它们也不变。Claude Code 安全、钩子、worktrees 完整指南 里有用户级配置的清单。

翻车点 3：先 /add-dir 再 /cd 到那个目录

这一种很隐蔽。如果你之前跑过 /add-dir ~/projects/mobile，然后又 /cd ~/projects/mobile，那个额外目录授权还在，工作根也搬进去了。原本走 additional-directory 查找表的路径解析，现在也会命中新工作根，Bash 调用收到的 CWD 会因为传的是绝对路径还是相对路径而不一致。

你不会直接看到 cache miss，但 Bash 命令的行为会忽冷忽热——有时落到旧根、有时落到新根——结果是工具调用轮次多了几次，每次都是 cache 写而不是读。

怎么修：/cd 后回头看一眼 /add-dir 授权，把和新工作根重叠的撤掉——要么走斜杠命令的交互式提示，要么干脆重启换个干净状态。另一种思路是 /cd 之后所有 Bash 和文件操作都用绝对路径，直接避开歧义。

缓存失效矩阵：/cd 之后哪些东西活着

两个目录的差异toolssystemmessages实际影响
CLAUDE.md 一样、.mcp.json 一样、.claude/ 一样HITHITHIT免费 /cd，缓存全保
只有 CLAUDE.md 不一样HITHITHIT（+追加）新 CLAUDE.md 追加为消息，少量 cache write
.mcp.json 不一样——deferred tools（直连 Anthropic 默认）HITHITHIT（+追加）新工具定义追加，已缓存前缀完整
.mcp.json 不一样——tools 进前缀（Haiku / Vertex / 自定义 ANTHROPIC_BASE_URL）MISSMISSMISS全量重建，约 12× 成本
.claude/settings.json 的 PreToolUse 钩子不一样MISSMISSMISS全量重建
配置一样，只是文件内容不同HITHITHIT免费 /cd（文件内容不在系统提示里）

缓存层级来自 Anthropic Prompt Caching 文档，失效是从 tools 往下连锁到 system 再到 messages。

团队 / 多开发者怎么配

团队共用 /cd 模式（典型场景：monorepo 多 worktree，或者多仓后端）的话，下面 3 条约定能让所有人都保住缓存：

约定在哪儿设为什么有用
统一一份 CLAUDE.md 提升到 ~/.claude/CLAUDE.md用户级一次根治该开发者所有仓库的翻车点 1
MCP server 全写到 ~/.claude/settings.json，不放项目 .mcp.json用户级根治翻车点 2，tools 缓存随 /cd 保温
worktree 一律不带本地 .claude/ 目录仓库内部规范防止 .claude/settings.json 在 worktree 之间漂移

要在团队范围标准化 Claude Code，可以再配一套 dotfiles 风格的共享 ~/.claude/ 布局，用 Chezmoi 或 Ansible 同步。两个对齐过的 worktree 之间第一次 /cd，下一轮的 cache_read_input_tokens 和上一轮基本一致——这就是团队配置对了的验证方式。

如果在直连 Anthropic 时撞到了账户额度（这正是 /cd 缓存价值最大的场景），用 Anthropic 兼容网关绕开额度限制、cache_control 语义照常保留。接入只要一个环境变量，详见Claude Code + ofox.ai 配置指南里 ANTHROPIC_BASE_URL 的具体配法。ofox 路由的是同一批 model ID（anthropic/claude-opus-4.8、anthropic/claude-sonnet-4.6），cache 头原样透传，前面的算账不会变。

进阶：多 provider 场景下的 /cd

/cd 跟模型无关——你直连 Anthropic、走 ofox 路由、还是本地兜底，它都不挑。但缓存折扣只在认 cache_control 的 provider 上才有。3 条具体建议：

  1. 同一会话混 provider：如果有些轮次走 Claude Opus 4.8（认缓存）、有些轮次走本地模型（不认），/cd 只对走 Claude 的轮次有用。把 /cd 安排在长前缀那一轮之前，不是之后。
  2. 每 feature 一个 worktree、共享基底：worktree 之间 base prompt 和工具列表保持完全一致。/cd 之后缓存前缀的哈希命中靠的是字节级完全一致，不是”语义等价”。
  3. 长 plan 会话：在 plan mode 待了 30 分钟以上，5 分钟 TTL 早就过期了，缓存自然冷掉，跟 /cd 无关。这种场景设 ENABLE_PROMPT_CACHING_1H=1 上 1 小时 TTL（写入贵 2 倍，但长规划场景值这个钱）。

想看缓存命中率的量化模型和长会话成本算账，参考 Claude Code Token 优化的 5 个策略——同一组 cache_read_input_tokens / cache_creation_input_tokens 是两边的共同诊断面。在 /cd 之前先挑会话锚定的 Claude 模型，参考 Claude Opus 4.8 上线指南里 4.6 / 4.7 / 4.8 三代缓存价差。

值得带走的心智模型：/cd 设计上就是为了保住提示缓存，大多数情况下也做到了——CLAUDE.md 不一样它会作为消息追加，不重建系统提示。真正会翻车的是 PreToolUse 钩子不一样，或者走网关时 MCP server 变化。把这些挪到用户级配置，/cd 基本就是免费的。

本次核实过的来源

相关文章

Claude Code --safe-mode 怎么用：一个开关关掉 5 道防线，10 秒上手（2026）

Claude Code Token 优化 2026：把 API 账单砍 60-90% 的 5 个策略

Claude Code 安全实战：用 Hooks、权限、Git Worktrees 防误删（2026）

← 返回文章列表