Цей матеріал є перекладом статті Таріка Шіхіпара (Thariq Shihipar) «Lessons from building Claude Code: Prompt caching is everything». Посилання на оригінальну статтю: https://claude.dev/blog/lessons-from-building-claude-code-prompt-caching-is-everything/
В розробці часто кажуть: „Кеш керує всім навколо нас“ . Для агентів він також актуальний
Створення довготривалих агентних продуктів, таких як Claude Code, стало можливим завдяки кешуванню промптів, яке дає змогу повторно використовувати обчислення з попередніх циклів взаємодії та суттєво зменшувати затримки й витрати.
У Claude Code ми будуємо всю інфраструктуру взаємодії агента навколо кешування промптів. Високий відсоток влучань у кеш знижує витрати та допомагає нам встановлювати щедріші ліміти використання для наших тарифних планів за підпискою. Тому ми налаштували сповіщення про показник влучань у кеш промптів і оголошуємо інциденти рівня SEV, якщо цей показник падає надто низько.
Ось уроки, які ми вивчили під час оптимізації кешування промптів у великих масштабах. Деякі з них можуть здатися неочевидними.
СТРУКТУРУЙТЕ ПРОМПТ З УРАХУВАННЯМ КЕШУВАННЯ
Системний промпт Claude Code організовано так, щоб незмінні його частини залишалися в кеші, а від повідомлення до повідомлення збільшувався лише сам діалог.
Кешування промптів працює на основі зіставлення префіксів: API кешує все від початку запиту до кожної контрольної точки cache_control. Це означає, що порядок розміщення елементів має величезне значення: потрібно зробити так, щоб якомога більше запитів мали спільний префікс.
Структура промпту впливає не лише на влучання в кеш, а й на якість результату. Інша важлива складова цієї дисципліни — основи проєктування промптів.
Найкращий підхід — спочатку розміщувати статичний вміст, а динамічний — наприкінці. У Claude Code це виглядає так:
- Статичний системний промпт (Static system prompt) і інструменти (Tools) — кешуються глобально.
- Файл CLAUDE.md (CLAUDE.md) — кешується в межах проєкту.
- Контекст сесії (Session context) — кешується в межах сесії.
- Повідомлення діалогу (Conversation messages).
Так ми максимізуємо кількість сесій, у яких можна повторно використовувати кеш.
Однак цей підхід може виявитися напрочуд крихким. Ми вже порушували такий порядок із різних причин, зокрема додавали детальну часову мітку до статичного системного промпту, непередбачувано змінювали порядок визначень інструментів і оновлювали параметри інструментів (наприклад, перелік агентів, яких може викликати інструмент Agent).
ВИКОРИСТОВУЙТЕ ПОВІДОМЛЕННЯ ДЛЯ ОНОВЛЕНЬ
Іноді інформація, яку ви додали до промпту, може застаріти. Наприклад, може змінитися поточний час або користувач може відредагувати файл. Може виникнути спокуса оновити сам промпт, але це призведе до промаху кешу й потенційно значно збільшить витрати користувача.
Натомість подумайте, чи можна передати цю інформацію в наступному ході агента через повідомлення. У Claude Code ми додаємо тег \<system-reminder> до наступного повідомлення користувача або результату роботи інструмента, передаючи моделі оновлену інформацію. Це допомагає зберегти кеш.
НЕ ЗМІНЮЙТЕ МОДЕЛІ ПОСЕРЕД СЕСІЇ
Кеші промптів прив’язані до конкретних моделей, через що математика кешування промптів може виявитися не такою інтуїтивною, як здається.
Наприклад, якщо ви вже накопичили 100 тисяч токенів у діалозі з Opus і хочете поставити запитання, на яке досить легко відповісти, перехід на Haiku насправді обійдеться дорожче, ніж відповідь Opus. Причина в тому, що для Haiku доведеться заново створювати кеш промпту.
Якщо потрібно змінити модель, найкраще зробити це за допомогою субагентів. Продовжуючи попередній приклад, можна запустити субагента, який попросить Opus підготувати повідомлення для передавання завдання іншій моделі. Ми часто робимо так із дослідницькими агентами Explore у Claude Code, які використовують Haiku.
НІКОЛИ НЕ ДОДАВАЙТЕ Й НЕ ВИДАЛЯЙТЕ ІНСТРУМЕНТИ ПОСЕРЕД СЕСІЇ
Зміна набору інструментів під час діалогу — один із найпоширеніших способів порушити кешування промптів. Інтуїтивно здається, що моделі варто надавати лише ті інструменти, які потрібні їй саме зараз. Але оскільки інструменти є частиною кешованого префікса, додавання або видалення інструмента робить кеш недійсним для всього діалогу.
Використовуйте режим планування з урахуванням обмежень кешу
Режим планування (Plan Mode) — чудовий приклад проєктування функцій з урахуванням обмежень кешування. Інтуїтивний підхід полягав би в тому, щоб під час переходу користувача в режим планування замінювати набір інструментів, залишаючи лише ті, що доступні для читання. Але це порушило б кешування.
Натомість ми завжди залишаємо в запиті всі інструменти, а EnterPlanMode і ExitPlanMode використовуємо як окремі інструменти. Коли користувач активує режим планування, агент отримує системне повідомлення з поясненням, що він перебуває в цьому режимі, а також відповідними інструкціями: дослідити кодову базу, не редагувати файли та викликати ExitPlanMode, коли план буде готовий. Визначення інструментів при цьому не змінюються.
Це також дає додаткову перевагу: оскільки модель може самостійно викликати EnterPlanMode як інструмент, вона здатна автономно переходити в режим планування, коли виявляє складну проблему, — без жодного порушення кешу.
Використовуйте пошук інструментів, щоб відкладати їх завантаження, а не видаляти
Той самий принцип застосовується до нашого інструмента пошуку інструментів (tool search tool). Claude Code може завантажувати десятки інструментів MCP, і включати їх усі в кожен запит було б дорого. Однак видалення інструментів посеред діалогу порушило б кешування.
Наше рішення — defer_loading. Замість видалення інструментів ми надсилаємо полегшені заглушки (лише назву інструмента та параметр defer_loading: true). За потреби модель може «знайти» потрібні інструменти за допомогою пошуку інструментів. Повні схеми інструментів завантажуються лише тоді, коли модель їх обирає. Завдяки цьому кешований префікс залишається незмінним, адже ті самі заглушки завжди присутні в тому самому порядку.
Ви також можете використовувати інструмент пошуку інструментів через наш API, щоб спростити цей процес.
СТИСКАННЯ КОНТЕКСТУ БЕЗ ПОРУШЕННЯ КЕШУ
Коли контекстне вікно заповнюється, Claude Code створює на основі кешованого виклику окремий запит для узагальнення діалогу, а потім продовжує роботу, замінюючи початкові повідомлення їхнім узагальненням.
Стиснення контексту (Compaction) — це процес, який запускається, коли вичерпується доступне контекстне вікно. Ми узагальнюємо перебіг діалогу до цього моменту й продовжуємо роботу в новій сесії, використовуючи це узагальнення.
Стиснення контексту взаємодіє з кешуванням промптів у спосіб, у якому легко припуститися помилки. Щоб стиснути діалог, потрібно передати моделі весь його вміст, аби вона могла підготувати узагальнення. Найпростіший спосіб зробити це — надіслати окремий API-запит із власним системним промптом (наприклад, «узагальни цей діалог») і без підключених інструментів. Але саме тут і криється пастка, яка призводить до зайвих витрат.
Кешування промптів працює лише тоді, коли префікс запиту повністю збігається з уже кешованим — байт у байт, починаючи з першого байта. Основний діалог кешується з одним системним промптом і одним набором інструментів, тоді як запит на узагальнення використовує інший системний промпт і не містить інструментів. Тому префікси розходяться вже на першому токені, і кеш узагалі не використовується. У результаті доводиться платити за весь вхідний контекст, який передається в запиті, за повним тарифом без кешування. І що довший діалог (тобто що гостріша потреба в стисненні контексту), то дорожчим стає цей окремий виклик.
Рішення: створення окремого запиту зі збереженням кешу
Під час стиснення контексту ми використовуємо точно ті самі системний промпт, контекст користувача, системний контекст і визначення інструментів, що й у батьківському діалозі. Спочатку додаємо повідомлення з діалогу батьківської сесії, а потім у кінець додаємо промпт для стиснення як нове повідомлення користувача.
З погляду API цей запит майже не відрізняється від останнього запиту батьківської сесії: той самий префікс, ті самі інструменти, та сама історія діалогу. Завдяки цьому кешований префікс використовується повторно. Єдині нові токени — це сам промпт для стиснення.
Однак це означає, що потрібно передбачити буфер для стиснення контексту (compaction buffer), аби в контекстному вікні залишилося достатньо місця для промпту стиснення та токенів, необхідних для формування узагальнення.
Стиснення контексту — непросте завдання, але, на щастя, вам не потрібно самостійно засвоювати всі ці уроки. Спираючись на наш досвід роботи над Claude Code, ми вбудували механізм стиснення контексту безпосередньо в API, щоб ви могли застосовувати ці підходи у власних застосунках.
ВИСНОВКИ
Ось кілька підходів, які виявилися корисними для оптимізації кешування промптів під час створення агентів.
1. Кешування промптів працює на основі зіставлення префіксів. Будь-яка зміна в будь-якій частині префікса робить недійсним увесь кеш після цієї точки. Проєктуйте всю систему з урахуванням цього обмеження. Якщо правильно впорядкувати елементи, більша частина кешування працюватиме автоматично.
2. Використовуйте повідомлення замість змін системного промпту. Може виникнути спокуса редагувати системний промпт для виконання таких дій, як перехід у режим планування, зміна дати тощо. Натомість краще передавати відповідну інформацію в повідомленнях безпосередньо під час діалогу.
3. Не змінюйте інструменти або моделі посеред діалогу. Використовуйте інструменти для моделювання переходів між станами (наприклад, для режиму планування), замість того щоб змінювати набір інструментів. Відкладайте завантаження інструментів, а не видаляйте їх.
4. Відстежуйте частоту влучань у кеш так само, як відстежуєте доступність сервісу. Ми налаштовуємо сповіщення про порушення кешування та розглядаємо їх як інциденти. Навіть кілька відсоткових пунктів промахів кешу можуть суттєво збільшити витрати й затримки.
5. Окремі операції мають зберігати префікс батьківського запиту. Якщо потрібно виконати допоміжне обчислення (стиснення контексту, узагальнення або виконання навичок), використовуйте ідентичні параметри, сумісні з кешуванням, щоб повторно задіяти кеш вихідного префікса.
Claude Code від самого початку проєктувався з урахуванням кешування промптів. Ми радимо вам дотримуватися такого самого підходу, щоб досягти найкращих результатів під час створення агентів.