Промахи кешу промптів у Claude Code: чому 86% влучань приховують справжню вартість

Частка влучань 86% звучить чудово. Але за змодельований вечір роботи з Claude Code сім промахів кешу коштували більше, ніж решта 33 ходи разом. Картина змінюється, щойно ви призначаєте ціну кожному промаху й знаходите його причину.

Версія 2.1.260 Claude Code додала в /cost новий рядок: найкращу здогадку про те, чому стався останній промах кешу промптів. Кандидати — змінені визначення інструментів, змінений системний промпт або пауза, довша за TTL. Потім 2.1.261 принесла /skill-doctor, який показує завантажені, але жодного разу не використані скіли й скільки вони коштують у контексті. У тому самому релізі виправили баг, через який учасники агентної команди повторювали оголошення інструментів першого ходу на другому, змінюючи префікс запиту й промахуючись повз кеш.

Разом ці записи свідчать, що вендор почав ставитися до збирання контексту як до проєктування ключів кешу, а більшість користувачів — ні. Кеш промптів — це кеш префіксів. Усе, що стоїть перед діалогом, у тому порядку, у якому ви це поставили, і є ключ. Щоб побачити, скільки це коштує у звичайний день, цифри нижче взято з моделі однієї сесії.

Як кеш будує ключі запитів

Документація Anthropic з кешування описує структуру прямо. Запит складається з шарів: інструменти, потім system, потім повідомлення, і будь-яка зміна на одному шарі стирає цей шар і всі наступні. Перейменували інструмент чи зачепили його схему — викидається весь кеш; підправили системний промпт — запис з інструментами лишається, решта губиться. З кожним запитом API хешує префікс до вашої точки розриву (breakpoint), а якщо збігу немає, відступає назад блок за блоком, перевіряючи не більше 20 позицій. Точок розриву можна задати до чотирьох; у цій моделі вони стоять після масиву інструментів, після системного промпту й на останньому повідомленні.

За замовчуванням запис живе п'ять хвилин, і кожне читання безкоштовно його подовжує. Запис на годину коштує вдвічі дорожче за базову ціну вводу. Claude Fable 5.1 бере $10 за мільйон вхідних токенів, $12,50 за мільйон під час запису п'ятихвилинного запису, $20 за годинний і $0,25 за мільйон під час читання. Отже, читання з кешу коштує 2,5% від надсилання тих самих токенів без кешу, а новий п'ятихвилинний запис — у 50 разів дорожчий за читання. Тому промах — не дрібне сповільнення: усе, що випало з кешу, раптом тарифікується в 50 разів дорожче.

Один вечір, сім звичайних подій

Swift-пакет ContextCacheKit розкладає запит так, як його хешує API, симулює кеш за задокументованими правилами TTL і відступу назад та призначає ціну кожному ходу. Його тестовий сценарій імітує реалістичну сесію в iOS-монорепозиторії. Набір інструментів: 16 інструментів гарнесу й 17 MCP-інструментів від Xcode, GitHub і Linear (19 140 токенів). Решта — преамбула гарнесу, CLAUDE.md на 200 рядків, файл пам'яті й пара скілів, що завантажуються під час старту (17 700 токенів). Кожен хід починається з цього спільного префікса на 36 840 токенів, а далі йдуть 40 користувацьких ходів з інтервалом 45 секунд.

Потім стаються сім подій із тих, що бувають у реальних командах. На другому ході колега переписує перше повідомлення. Восьмий хід завантажує скіл для роботи з мережею, вклеєний у системний промпт. На 14-му ході MCP-сервер GitHub перепідключається й наново реєструє свої вісім інструментів у кінці списку. Перед 20-м ходом — обід на 22 хвилини. На 26-му ході вливається зміна в CLAUDE.md, на 33-му завантажується новий скіл для тестів, а на 37-му перепідключений клієнт наново рендерить визначення інструмента Bash, і воно зростає з 1450 до 1480 токенів.

Загалом сесія влучає в кеш у 85,6% випадків — на дашборді така цифра ні в кого не викличе питань. Журнал витрат каже інше. Ввід коштував $4,65. Ідеальне перевикористання попереднього префікса на кожному ході коштувало б $1,53, а без кешу взагалі — $23,10. Сім промахів дають $3,41 рахунку, а решта 33 ходи разом — $1,24.

Якщо відсортувати за доларами понад ідеал, головний винуватець — повторний рендер схеми інструмента, $0,91. Далі три окремі зміни системного промпту, разом $0,88, потім обідня перерва — $0,69, перестановка інструментів — $0,64 і далеко позаду переписування колеги — $0,002.

Два пункти цього рейтингу змінюють уявлення про те, звідки беруться витрати. Тридцять зайвих токенів у схемі Bash змусили систему наново надіслати всі 75 249 токенів запиту, бо інструменти стоять на чолі ієрархії. Звичайна перестановка інструментів GitHub, за побайтово незмінної схеми, зробила те саме з 52 648 токенами. А баг, що заслужив запис у ченджлозі, — колега, який переписав нульове повідомлення, — виявився найдешевшим промахом: перекешувалося лише 157 токенів, бо повідомлення розташовані в самому низу. Гарнес полагодив промах, який бачив сам, а дорогі промахи йдуть із вашої власної конфігурації.

Логіка діагностики проста: перемагає перше в порядку хешування, що ламає префікс.

// Abridged from MissDiagnoser.swift: the first thing in hash order that would break the prefix wins.
public static func diagnose(previous: ContextSnapshot?, current: ContextSnapshot,
                            elapsed: TimeInterval, ttl: CacheTTL) -> MissCause {
    guard let previous else { return .none }            // cold start, not a miss
    if toolsDiffer(previous, current) { return .toolSetChanged(...) }
    if previous.tools.map(\.name) != current.tools.map(\.name) { return .toolOrderChanged }
    if previous.system != current.system { return .systemSegmentChanged(segments: changed) }
    if let i = firstRewrittenMessage(previous, current) { return .messagePrefixRewritten(atIndex: i) }
    return elapsed > ttl.seconds ? .idlePastTTL(idleSeconds: elapsed) : .none
}

Ставтеся до префікса як до ключа кешу

Проженімо той самий вечір зі спроєктованим префіксом — сценарієм stabilized. Порядок інструментів зафіксовано, схеми заморожено на всю сесію. Скіли потрапляють у діалог як повідомлення з роллю system, а не як текст, вклеєний у системний промпт верхнього рівня; за документацією на Fable 5.1 це лишає кеші system і повідомлень недоторканими. Злиття CLAUDE.md відкладається до межі сесії. Обід лишається як є, бо TTL — це рішення політики, а не дефект префікса.

У цьому прогоні один промах — обідня перерва. Частка влучань — 94,2%. Вартість — $2,22, тобто на $0,69 вище за ідеал. Усі виправлення змінювали те, що надсилає гарнес; поведінки моделі не торкалося жодне.

Останній важіль — TTL. Переведіть стабілізований прогін на годинні записи, і промахів не лишиться, за вартості $2,11. Це заощаджує лише 11 центів порівняно з п'ятихвилинним варіантом, бо кожен свіжий токен тепер коштує $20 на запис, а не $12,50, і за вечір ця надбавка набігає приблизно на одну обідню перерву. Довгий TTL окуповується лише в дні з паузами, тож налаштовуйте його для кожної команди, а не глобально.

Найбільше грошей рухає розміщення скіла. Той самий скіл, ті самі 5200 токенів, відрізняється лише місце:

// Same skill, same 5,200 tokens. Only the placement changes.
.loadSkill(name: "skill:networking-layer", tokens: 5_200, placement: .systemPrompt)
// → system prompt changed: re-sends the transcript after it
.loadSkill(name: "skill:networking-layer", tokens: 5_200, placement: .appendedMessage)
// → hit: costs only its own 5,200 tokens, once

Що відстежувати

Плануйте спільний префікс, як час запуску застосунку. Інструменти й скіли, які ваш монорепозиторій вантажить за замовчуванням, складаються в 36 840 токенів, що хешуються на кожному ході, а частка влучань усереднює всю сесію й ховає, на якому ході згоріли гроші. Цифра, яку варто вивести на дашборд, — долари понад ідеал, за причинами й за днями. Причину тепер дає /cost, долари — журнал витрат.

Частка влучань — це середнє, а промах кешу — подія, тож закладайте бюджет на події.

Сценарій — це модель, а не телеметрія, і його константи — припущення, тож із вашим списком інструментів і розмірами префікса рейтинг зсунеться. Загальна форма — ні. Найдорожче коштують причини на вершині ієрархії, і жоден ченджлог їх за вас не полагодить. Симулятор, сценарії, 30 тестів і подання журналу на SwiftUI лежать у демо-репозиторії проєкту; на момент публікації таргет Demo в симуляторі ще не запускали.