Cache miss в Claude Code обычно означает, что дешевое чтение из кеша не сработало для повторно используемого префикса. Дорогим становится не слово "miss", а то, что входной контекст был снова обработан, снова записан в prompt cache или совпал только частично. Выходные токены при этом остаются обычной отдельной частью стоимости.
На 24 мая 2026 года формула Anthropic объясняет популярное "12.5x" без мистики: 5-минутная cache write стоит 1.25x базового input, а cache read стоит 0.1x для тех же токенов. 1.25 / 0.1 = 12.5. Это сравнение записи и чтения, а не официальная отдельная доплата за cache miss.
Перед тем как менять процесс, назовите маршрут, который породил число: подписка Claude, API key, оценка Agent SDK, Bedrock, Vertex, Foundry или gateway. Затем сравните cache_creation_input_tokens, cache_read_input_tokens, модель, список MCP, команды вроде /compact, версию Claude Code и биллинговую поверхность именно этого маршрута. Без такого набора данных легко перепутать нормальную инвалидацию кеша с багом.
Быстрый разбор: сначала маршрут, потом кеш
| Вопрос | Короткий ответ | Какие доказательства нужны |
|---|---|---|
| Cache miss - это отдельная плата? | Нет. Это означает, что префикс не был дешево прочитан из кеша и был обработан или записан снова. | Поля cache creation и cache read в одном маршруте. |
| Почему говорят о 12.5x? | 5-minute write стоит 1.25x, read стоит 0.1x, поэтому для того же объема 1.25 / 0.1 = 12.5. | Актуальная страница цен Anthropic и usage-поля. |
| Что проверить первым? | Владельца маршрута: подписка, API key, SDK, облачный провайдер или gateway. | /status, /cost, Claude Console, Usage and Cost API, invoice провайдера. |
| Когда spike выглядит подозрительно? | Когда похожие turn подряд создают много кеша и почти не читают его при стабильной модели, MCP и маршруте. | Временные метки, модель, версия, MCP-список, поля usage. |
| Что не делать первым? | Не запускать /compact вслепую и не менять provider до диагностики. | Сначала назвать действие, которое изменило префикс. |
Если главный вопрос - какой счетчик вообще активен, используйте карту Claude Code API key против подписочного биллинга. Если проблема шире и связана с тяжелыми MCP definitions или раздуванием контекста, полезнее путь Claude Code MCP context overload. Cache miss объясняет входную экономику одного turn, но не заменяет расследование лимитов, подписки или provider-инвойса.
12.5x - это математика write/read
Страница цен Claude API разделяет обычные input-токены, cache write, cache read и output. Текущая публичная логика такова: 5-минутная запись в кеш стоит 1.25x от базового input, 1-часовая запись стоит 2x, чтение из кеша стоит 0.1x.
text5-minute cache write / cache read = 1.25 / 0.1 = 12.5 1-hour cache write / cache read = 2.0 / 0.1 = 20
Эта формула полезна только при одном условии: сравнивается один и тот же объем префикса, но в одном случае он записывается, а в другом читается. Она не доказывает, что в Claude Code есть отдельная строка "cache miss fee". Она также не доказывает баг. Новая сессия, смена модели, подключение MCP, долгое ожидание, upgrade Claude Code или компактирование разговора могут привести к ожидаемой новой записи.
Практический риск растет вместе с размером префикса. Большая история разговора, project context, результаты инструментов, MCP server definitions, subagent context, большие file packs или длинный system prompt превращают один промах в заметную сумму. Малый miss может быть шумом; повторная высокая cache creation на похожих turn - уже диагностический сигнал.
Реестр токенов: общий total не отвечает на вопрос
Не анализируйте дорогой turn только по total tokens. Total показывает масштаб, но не объясняет причину. Нужно разложить запись по классам.
| Счетчик | Что означает | Как использовать |
|---|---|---|
| Обычные input tokens | Вход, который был обработан моделью без дешевого read. | Базовая стоимость при отсутствии кеша или частичном совпадении. |
cache_creation_input_tokens | Токены, записанные или подготовленные для prompt cache. | Один высокий write может быть нормальным; повторный высокий write - сигнал. |
cache_read_input_tokens | Токены, прочитанные из существующего cache entry. | Высокий read относительно creation обычно означает, что кеш работает. |
| Output tokens | Сгенерированный ответ модели. | Экономия на входе не делает output бесплатным. |
| Subscription usage | Окна плана, seat usage, reset и лимиты подписки. | Нельзя напрямую сравнивать с API invoice. |
/cost и поля SDK | Локальные или клиентские оценки. | Хороши для трендов, слабее официального биллинга. |
| Console, Usage and Cost API, invoice провайдера | Авторитетная поверхность для своего маршрута. | Используется для итогового spend proof и support packet. |
Документация Agent SDK cost tracking описывает total_cost_usd и costUSD как оценки. Это не делает их бесполезными: они помогают ловить runaway-сессии и сравнивать похожие turn. Но если нужен финансовый вывод, сверяйтесь с Claude Console, Usage and Cost API или провайдерским invoice.
Когда маршрут неясен, сначала выполните минимальную проверку:
bashclaude /status /cost
/status помогает понять активный аккаунт или route. /cost может помочь при API-style monitoring, но окончательное доказательство принадлежит тому маршруту, где выполнялся запрос.
Что ломает совпадение кеша в Claude Code
Документация Claude Code prompt caching опирается на prefix matching. Если ранняя часть запроса изменилась, все последующее может перестать совпадать, даже если пользовательский текст выглядит похожим. Поэтому важен не только размер контекста, но и последнее действие перед дорогим turn.
| Недавнее действие | Риск | Следующая проверка |
|---|---|---|
| Смена модели | Высокий | Сравните model и timestamp до и после spike. |
| Подключение или отключение MCP server | Высокий | Tool definitions могут менять ранний префикс. |
| Deny целого инструмента | Высокий | Whole-tool denial меняет доступный tool context. |
/compact | Высокий | Compact переписывает conversation context и может разорвать reuse. |
| Upgrade Claude Code | Высокий | Версия может изменить prompt shape или cache scope. |
| Смена API route, provider или gateway | Высокий | Меняется и cache scope, и владелец биллинга. |
| Долгий idle gap | Средний | TTL мог истечь до следующего read. |
| Subagents, forks, worktrees, directory changes | Средний | Контекст может разделиться по пути, процессу или agent scope. |
| Изменение файлов | Ниже | Добавляет контекст, но не всегда меняет ранний prefix. |
| Output style или permission mode | Ниже | Все равно стоит записать, если совпадает по времени. |
/recap или rewind | Ниже | Полезно для навигации, но поля usage нужно проверить. |
Консервативная интерпретация лучше поспешного вывода. Cache write после осмысленного изменения может быть ожидаемым. Повторный write при том же route, той же модели, том же MCP setup, коротком интервале и похожем контексте - более сильный признак проблемы.
Маршруты и доказательства: один workflow, разные контракты
Число на экране может относиться к разным поверхностям. Подписка, API key, SDK estimate, cloud provider и gateway могут показывать usage или cost, но это разные юридические и технические контракты.
| Маршрут | Что может означать число | Более сильное доказательство |
|---|---|---|
| Claude subscription login | Usage плана, seat limits, reset timing, included usage. | Help Center usage language, account status, /status, plan messages. |
| Claude API key | Pay-as-you-go API token billing. | Claude Console, Usage and Cost API, project billing settings. |
| Agent SDK | Usage и cost estimate из SDK messages. | SDK fields плюс Console или Usage and Cost API. |
| Bedrock, Vertex, Foundry | Provider-routed model use, provider billing, cache-support boundary. | Cloud invoice и request logs этого provider. |
| Gateway | Gateway usage и pass-through поведение к upstream provider. | Gateway logs плюс upstream billing, если доступен. |
Claude Code costs и Help Center usage article важны именно потому, что отделяют subscription usage от API billing. Не используйте subscription limit message как доказательство API spend. Не используйте SDK estimate как доказательство списания по подписке.
Если реальный симптом - окно лимита, переходите к Claude Code rate limit или Claude Code rate limit reached. Cache math объясняет входную часть потребления, но не является полным playbook для восстановления quota.
Порядок исправлений: минимальное изменение и следующий замер
Дорогой turn не требует сразу менять весь workflow. Работайте с одним фактором за раз.
- Назовите маршрут. Подписка, API key, SDK estimate, provider route или gateway.
- Сравните поля кеша. Несколько похожих turn должны показать отношение
cache_creation_input_tokensкcache_read_input_tokens. - Найдите invalidator. Модель, MCP, whole-tool denial,
/compact, upgrade, provider, TTL, subagent, fork, worktree или directory scope. - Стабилизируйте ранний prefix. Не меняйте модель и MCP setup посреди одной задачи без причины.
- Разделяйте несвязанные задачи через
/clear. Смешанный контекст делает prefix большим и нестабильным. - Используйте
/compactна естественных границах. Это инструмент для слишком большого разговора, а не первая реакция на один spike. - Оценивайте 1-hour TTL по cadence. Более длинный TTL дороже при записи и окупается только будущими read.
- Проверьте следующий похожий turn. После удачного исправления repeated creation падает, а cache read растет при той же модели и route.
Если одновременно сменить модель, отключить MCP, выполнить compact и перейти на другой gateway, результат невозможно интерпретировать. Снижение cost будет реальным, но вы не узнаете, какой фактор сработал.
Пакет для подозрительного spike
Фраза "у меня cache bug" слабее набора данных. Для коллеги, FinOps или support engineer важна возможность сравнить один маршрут, одну временную линию и похожую форму контекста.
| Доказательство | Зачем нужно |
|---|---|
| Timestamp и timezone | Сводит usage records и invoices. |
| Версия Claude Code | Upgrade может менять prompt shape. |
| Model | Смена модели - известный invalidator. |
| Active route | Подписка, API key, SDK, provider и gateway не смешиваются. |
| MCP server list до и после | Connect/disconnect меняет ранний prefix. |
| Tool permission changes | Whole-tool denial меняет tool context. |
/compact, /clear, /recap, rewind history | Conversation-shape actions влияют на интерпретацию. |
cache_creation_input_tokens и cache_read_input_tokens | Главное доказательство write/read. |
| Пара похожих hit/miss turn | Сравнение сильнее одиночного скриншота. |
| Billing surface | Console, Usage and Cost API, provider invoice или subscription usage. |
Один cache write после изменения контекста - не повод для эскалации. Повторная высокая creation при стабильном route, model, MCP setup, коротком интервале и похожем контексте - уже повод собрать support packet.
Часто задаваемые вопросы
Cache miss в Claude Code - это отдельная плата?
Нет. Это лучше описывать как дорогую сторону prompt caching: повторно используемый префикс не был дешево прочитан, а был обработан или записан снова. Ищите token class, а не отдельную строку штрафа.
Откуда берется 12.5x?
Из текущих множителей Anthropic: 5-minute cache write стоит 1.25x базового input, а cache read стоит 0.1x. Для того же объема токенов 1.25 / 0.1 = 12.5.
Какие поля доказывают cache miss?
Начинайте с cache_creation_input_tokens и cache_read_input_tokens. Высокая creation и низкий read означают, что префикс не был переиспользован дешево. Повторение на похожих turn гораздо важнее одной записи.
Поможет ли /compact снизить расходы?
Иногда да, но не как универсальный cache fix. /compact может уменьшить слишком большой conversation, но он также переписывает контекст и способен сломать существующий reuse.
Когда нужен 1-hour TTL?
Только если маршрут поддерживает его и последующие read действительно окупят более дорогую запись. Более длинный TTL помогает при подходящем cadence, а не сам по себе.
/cost - это мой счет Claude?
Нет. /cost и SDK cost fields полезны для monitoring, но финальное доказательство - Claude Console, Usage and Cost API, cloud invoice, gateway records или subscription usage surface активного маршрута.
Когда можно подозревать баг кеша?
После same-route evidence: timestamp, version, model, route, MCP setup, permission changes, cache fields, похожие hit/miss turn и billing surface. До этого вероятнее обычная инвалидация или TTL expiry.