Claude Code /cd: смена директории без потери prompt cache (v2.1.169)

Самая запрашиваемая фича Claude Code 2026 года вышла тихо в v2.1.169, и большинство пользователей всё ещё не знают, что она сохраняет prompt cache, а не сбрасывает его.

Если вы каждый раз закрывали и перезапускали Claude Code, чтобы перейти в git worktree или соседний репозиторий — этот ритуал закончился 2026-06-08. Команда /cd переносит сессию в новую рабочую директорию на лету, не ломая кэшированный префикс. На Claude Opus 4.8 (input $5/M, cache read $0.50/M) это означает скидку 90% на всё, что иначе пришлось бы пересылать заново.

Но «сохраняет prompt cache» идёт с тремя сносками. Этот гайд разбирает проверенную механику, пошаговый процесс и три кейса, где кэш всё-таки молча умирает.

Что /cd умеет и чего не умеет

Если торопитесь к практике — переходите к пошаговой инструкции. Если упираетесь в лимиты прямого Anthropic API, ofox прозрачно прокидывает cache_control: см. гайд по подключению Claude Code к ofox.ai — сейчас купоны 20% off, бонус 15% при первом депозите ≥ $50, $5 пробного баланса, UTM claude-code-cd-ru.

Ментальная модель на 30 секунд: /cd — это «перенесём комнату, где работаю, оставив всё сказанное». /add-dir — «остаюсь в этой комнате, дай заглянуть в соседнюю». cd в Bash — ни то, ни другое: он меняет один вызов оболочки и сбрасывается на следующем.

Когда /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 Code неинтерактивно (claude -p "...") — передайте директорию как CWD при старте процесса.
3. В новой директории заметно другой .mcp.json и вы маршрутизируетесь через кастомный ANTHROPIC_BASE_URL или модель без tool search (Haiku, Vertex AI). В такой связке кэш всё равно пересоберётся — лучше перезапустить и получить чистое состояние. Один лишь другой CLAUDE.md — не проблема: /cd добавит его как сообщение и сохранит кэш.

Правило стопа. Если задача — прочитать один файл в другом репо, остановитесь на /add-dir плюс Read /absolute/path/to/file. /cd для этого — перебор, и обойдётся в частичную инвалидацию кэша. Если задача — писать файлы там, /cd окупается.

Системные требования

Если у вас ниже v2.1.169: npm i -g @anthropic-ai/claude-code (CLI сам ловит новые версии при старте).

Пошагово: меняем директорию посреди сессии

Шаг 1: подтвердить текущий корень

Большинство сессий показывают рабочий корень в строке-префиксе. Если у вас нет — спросите Claude напрямую: which directory are you in?. Он выведет абсолютный путь из контекста инструментов. Ожидаемый результат: абсолютный путь к корню сессии.

Шаг 2: запустить /cd с абсолютным путём

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

Claude Code подтвердит, что сессия перенеслась. Используйте абсолютные пути — относительные вроде /cd ../mobile тоже работают, но резолвятся относительно текущего корня, что путает после двух-трёх переходов.

Шаг 3: проверить кэш в следующем сообщении

Отправьте любое сообщение и следите за cache_read_input_tokens и cache_creation_input_tokens в ответе API. /cost (он же /usage) показывает общие расходы сессии и потребление плана, но не per-turn счётчики кэша. Для живой видимости на каждом ходе официальная документация рекомендует statusline-скрипт, читающий объект current_usage:

cache_read_input_tokens: 47,832    ← кэш сохранился
cache_creation_input_tokens: 142   ← записан только диф

Ненулевой cache_read_input_tokens рядом с размером предыдущего префикса — /cd сохранил кэш горячим. Ноль чтений плюс крупный cache_creation_input_tokens — что-то на пути cache-key изменилось, разбираемся в следующем разделе.

Шаг 4: работаем как будто CLI стартовал из новой директории

Glob, Grep и Bash теперь привязаны к новому корню. Запись файлов идёт в новое дерево. Plan-mode, todo-список и история диалога едут вместе. Никакого «сброса сессии» не происходит.

Типичные явные ошибки /cd (и что они значат)

Явные сбои распознать легко. Тихие — когда /cd отработала успешно, но кэш мёртв — в следующем разделе.

3 случая, когда кэш молча инвалидируется

Это три самых частых режима отказа. Каждый технически корректен (кэш действительно грязный), но фраза «сохраняет prompt cache» наводит на мысль об универсальности — это вводит в заблуждение.

Кейс 1: в новой директории другой CLAUDE.md (страшилки преувеличены)

Этого боится большинство, но /cd обрабатывает кейс изящно. По официальному справочнику команды /cd, CLAUDE.md новой директории добавляется как сообщение, а не встраивается в системный промпт заново:

/cd ~/projects/mobile     ← другой CLAUDE.md
→ tools cache:    HIT
→ system cache:   HIT
→ messages cache: HIT (старые ходы не меняются, новый CLAUDE.md добавлен)
+ небольшая запись в кэш для добавленного содержимого CLAUDE.md

Цена в том, что новый CLAUDE.md оказывается в слое диалога, а не в (закэшированном) системном слое — это стоит несколько сотен или тысяч токенов записи в кэш в зависимости от размера файла, но кэшированный префикс остаётся целым. Режим отказа «потерян tools cache», которого вы боялись, здесь не наступает.

Что чинить. По поведению кэша — ничего, дизайн уже корректен. Реальная забота с разным CLAUDE.md — семантическая: правила для проекта A могут сбивать агента в проекте B. Держите один общий ~/.claude/CLAUDE.md на пользовательском уровне для кросс-проектных правил и оставляйте локальные файлы под действительно проектную специфику.

Кейс 2: разные MCP-серверы — инвалидация только при выключенном tool search

Этот кейс условный. Официальная документация Claude Code по prompt caching отмечает: отложенные tools (default на поддерживаемых моделях) только дополняют контекст при подключении/отключении MCP-сервера или изменении списка инструментов — кэшированный префикс выживает. Полная пересборка кэша при изменениях MCP происходит, только когда tools загружаются в префикс: на Haiku, на Vertex AI или через кастомный шлюз ANTHROPIC_BASE_URL.

Если маршрутизируетесь через кастомный base URL (включая ofox.ai), считайте, что изменения MCP инвалидируют кэш:

/cd ~/projects/data-pipeline    ← добавлен postgres MCP-сервер, роутинг через шлюз
→ tools cache: MISS  (новые определения tools, не отложены)
→ system cache: MISS (каскадно)
→ messages cache: MISS (каскадно)

На префиксе 100K токенов это примерно $0.625 на запись против $0.05 на чтение — примерно в 12× дороже, чем чистый /cd. На прямом Anthropic с отложенными tools та же /cd фактически бесплатна.

Что чинить. Если вы на прямом Anthropic и поддерживаемых моделях — уже всё хорошо. На кастомном шлюзе либо выровняйте MCP-серверы между проектами, между которыми скачете, либо вынесите общие серверы в пользовательский ~/.claude/settings.json, чтобы они не менялись со сменой рабочего корня.

Кейс 3: сначала /add-dir, потом /cd в ту же директорию

Этот кейс хитрый. Если вы раньше запустили /add-dir ~/projects/mobile, а затем /cd ~/projects/mobile, грант на дополнительную директорию по-прежнему активен, и рабочий корень переехал внутрь. Инструменты, резолвившие пути через таблицу additional-directory, теперь также матчатся с новым рабочим корнем — Bash-вызовы получают разные CWD в зависимости от того, передан путь как абсолютный или относительный.

Прямого cache miss вы не увидите, но Bash-команды поведут себя непоследовательно — иногда резолвятся относительно исходного корня, иногда нового — и это стоит лишних tool-call раундов, каждый из которых — запись в кэш, а не чтение.

Что чинить. После /cd пересмотрите гранты /add-dir и снимите все, что пересекаются с новым рабочим корнем — через интерактивный prompt слеш-команды или перезапуском из чистого состояния. Альтернатива — после /cd использовать абсолютные пути во всех Bash и file-write запросах, чтобы полностью обойти неоднозначность резолва.

Матрица инвалидации: что переживает /cd

Иерархия кэша приведена в документации Anthropic по prompt caching, инвалидация каскадирует сверху вниз от tools через system к messages.

Команда / мульти-разработчик: как настроить

Для команд, разделяющих сценарии /cd по многим репозиториям (типичный случай — монорепо с несколькими worktree или полирепо-бэкенд), три соглашения держат кэш горячим у всех:

Для стандартизации Claude Code по команде можно также завести dotfiles-стиль общий лэйаут ~/.claude/ в Chezmoi или Ansible. Первый же /cd между двумя правильно выровненными worktree даст 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) и прокидывает заголовки кэша без изменений, так что расчёт выше не меняется.

Advanced: /cd в мульти-провайдерных сценариях

/cd модель-агностична — без разницы, идёте ли вы напрямую в Anthropic, через ofox или локальный fallback. Но скидка на кэш материализуется только у провайдеров, уважающих cache_control. Три конкретных совета:

1. Смешанные провайдеры по ходам. Если сессия иногда идёт в Claude Opus 4.8 (cache-aware), а иногда в локальную модель (без кэша), /cd помогает только ходам через Claude. Планируйте вызовы /cd перед ходами с дорогим префиксом, а не после.
2. Worktree на каждую feature, общая база. Держите базовый промпт и список tools идентичными между worktree. Хэши префикса кэша выживают /cd, только когда байты совпадают побайтово, не «семантически».
3. Длинные планы. Если вы в plan mode 30+ минут, 5-минутный TTL истёк и кэш холодный независимо от /cd. Используйте ENABLE_PROMPT_CACHING_1H=1 для 1-часового TTL (запись в 2× дороже, но в долгих планах окупается).

Глубже про математику cache-hit и количественную модель стоимости длинных сессий — в гайде по оптимизации токенов в Claude Code: та же пара cache_read_input_tokens / cache_creation_input_tokens — общая диагностическая поверхность для обоих кейсов. Если перед /cd важно выбрать модель Claude для якоря сессии — в обзоре релиза Claude Opus 4.8 разобраны различия в ценах кэша по линейке 4.6 / 4.7 / 4.8.

Ментальная модель, которую стоит унести: /cd спроектирована, чтобы сохранять prompt cache, и в большинстве случаев это делает — изменения CLAUDE.md обрабатываются добавлением файла как сообщения, а не пересборкой системного промпта. Реальный режим отказа — это различия хуков PreToolUse или изменения MCP-серверов при роутинге через шлюз без отложенных tools. Поднимите их в пользовательский конфиг — и /cd фактически бесплатна.

Источники, проверенные для этого обновления

• Claude Code CHANGELOG (проверено 2026-06-11): github.com/anthropics/claude-code/blob/main/CHANGELOG.md — подтверждена запись о /cd в v2.1.169
• Справочник команды Claude Code /cd (проверено 2026-06-11): code.claude.com/docs/en/commands — подтверждает, что CLAUDE.md добавляется как сообщение, а не встраивается в системный промпт
• Гайд Claude Code по prompt caching (проверено 2026-06-11): code.claude.com/docs/en/prompt-caching — поведение отложенных tools, переменные ENABLE_PROMPT_CACHING_1H и FORCE_PROMPT_CACHING_5M, statusline для видимости кэша
• Документация Anthropic по Prompt Caching (проверено 2026-06-11): platform.claude.com/docs/en/build-with-claude/prompt-caching — иерархия кэша tools → system → messages и множители цен (0.1× read, 1.25× 5-min write, 2.0× 1-hour write)
• GitHub issue #25322 «Allow switching working directory mid-session»: github.com/anthropics/claude-code/issues/25322 — исходный запрос фичи и боли с worktree (закрыт как duplicate после выхода /cd)
• Срез витрины моделей ofox (проверено 2026-06-11): ofox.ai/ru/models — цены Claude Opus 4.8 / 4.7 / 4.6 и Sonnet 4.6