Claude Code Best Practices: управление контекстом и context engineering — официальное руководство Anthropic

Решение, которое реально меняет модель AI-затрат вашей команды, — это не то, какую модель вы выбираете, а то, сколько токенов сжигает одна сессия coding-агента. Опубликованное Anthropic официальное руководство по best practices Claude Code на code.claude.com/docs/en/best-practices впервые формулирует это явно через единое управляющее ограничение: context window наполняется быстро, и производительность LLM деградирует по мере его наполнения. Для команд, маршрутизирующих вызовы Claude Code через API gateway, это не рекомендация по UX. Это сигнал о стоимости и надёжности, который напрямую влияет на то, как вы моделируете расходы на токены, наблюдаете за сессиями и настраиваете fallback в routing.

Что произошло

Anthropic выпустила исчерпывающее официальное руководство по best practices для Claude Code — своей агентной среды программирования на базе терминала. Документ носит авторитетный характер, охватывает внутренние инженерные процессы самой Anthropic и построен вокруг одного центрального ресурсного ограничения: бюджета context window.

Ключевые паттерны, которые фиксирует руководство:

Context window — это главный ресурс, которым нужно управлять. Каждое чтение файла, каждый вывод команды, каждое сообщение в сессии Claude Code накапливаются в context window. Одна сессия отладки или исследования кода может потратить десятки тысяч токенов. По мере наполнения окна модель начинает терять более ранние инструкции и чаще ошибаться. Руководство прямо требует от инженеров непрерывно отслеживать использование контекста через кастомный status line.

Фазирование explore-plan-code снижает потери контекста. Рекомендованный четырёхфазный workflow (исследование в read-only «plan mode» → генерация плана → реализация → коммит) существует не только ради качества вывода, но и ради того, чтобы сократить число чтений файлов и tool-вызовов, которые накапливаются до начала реализации. Каждое лишнее чтение — это токены, которые уже не вернуть.

CLAUDE.md — это базовый примитив operator-конфигурации. Команда /init создаёт файл CLAUDE.md, переживающий перезапуски сессий. Руководство недвусмысленно: держите его коротким, выкидывайте всё, что Claude может вывести из самого кода, и проверяйте — действительно ли поведение Claude меняется. Раздутый CLAUDE.md впустую тратит токены при каждом старте сессии и может привести к тому, что Claude начнёт игнорировать действительно важные правила.

Параллельные sub-агенты умножают стоимость контекста. Руководство явно одобряет одновременный запуск нескольких агентов Claude Code на независимых задачах. У каждой параллельной сессии собственный context window, собственные вызовы модели и собственный расход токенов. Три параллельных агента, изучающих большую кодовую базу, в сумме сжигают токены втрое быстрее, чем одна сессия, — и без какого-либо разделения токенов между сессиями.

Skills — это инжекция контекста по требованию. Skills (доменные .md-файлы, на которые ссылается CLAUDE.md) загружаются только при вызове, а не при старте сессии. Это рекомендованный руководством способ работы с большими базами знаний — подгружать только то, что нужно текущей задаче.

Почему это важно для AI-инженерных команд

По сути, руководство по best practices Claude Code — это архитектурный документ о потреблении токенов, замаскированный под гайд по workflow. Любую рекомендацию можно переформулировать в терминах стоимости:

Верификация уменьшает повторные прогоны. Самая важная рекомендация руководства — дать Claude способ верифицировать собственную работу: тесты, ожидаемые выводы, результаты линтеров. С точки зрения routing это значит вот что: без петель верификации проваленные сессии требуют полного перезапуска, и каждая стартует со свежим context window. Команда, которая запускает десять сессий Claude Code ради одного хорошего результата, оплачивает десять бюджетов контекста на исход, а не один.

Plan mode — это дешёвый предварительный обзор. Plan mode не даёт Claude вносить правки во время исследования. С точки зрения токенов это важно, потому что предотвращает накопление tool-call ответов (записи в файлы, подтверждения команд), которые раздувают контекст быстрее, чем чистые чтения. Команды могут продвигать «сначала plan mode» как дисциплину контроля затрат.

Параллельные сессии требуют отдельного учёта. Большинство биллинговых API показывает агрегированное использование токенов. Если ваша команда запускает Claude Code с sub-агентами, телеметрия gateway должна атрибутировать расход токенов на сессию, а не на запрос. Один пользователь, запустивший пять параллельных агентов Claude Code, порождает пять одновременных потоков токенов — и каждый по отдельности невидим, если ваш слой observability не сегментирует данные по session ID.

Дрейф CLAUDE.md — это скрытая статья расхода. Если инженеры дописывают в CLAUDE.md, ничего не удаляя, каждый старт сессии становится дороже. Команды, эксплуатирующие Claude Code в масштабе, должны относиться к CLAUDE.md как к конфигурационному артефакту с явной стоимостью в токенах за сессию — и ревизовать его так же, как ревизуют список зависимостей.

Угол зрения router/operator

Для команд, использующих routing-gateway для вызовов API Claude Code:

Fallback, триггерящийся по контексту, — это отдельная потребность. Стандартная логика routing fallback срабатывает по ошибкам провайдера, по rate limit или по порогам latency. Claude Code добавляет новый триггер: исчерпание context window. Когда контекст сессии переполняется и модель начинает деградировать, правильный ответ — это, возможно, не повторный вызов той же модели, а маршрутизация на модель с большим context window или сигнал harness начать новую сессию. Для этого gateway должен быть осведомлён о context window, а не только об ошибках.

Модель стоимости токенов для агентных сессий отличается от чатовых. Чат-вызовы API, как правило, ограничены: пользователь шлёт сообщение, получает ответ. Сессии Claude Code по дизайну неограниченны: агент читает файлы, выполняет команды, итеративно дорабатывает результат и может работать минутами или часами. Модель за «$0,003 за 1K токенов», выглядящая дешёвой в чате, легко превращается в счёт «$2–$5» за одну coding-сессию, если агент исследует крупную кодовую базу перед реализацией. Команды, верстающие бюджет из допущений о стоимости одного запроса, существенно недооценят фактический расход.

Observability сессий должна отслеживать скорость заполнения контекста, а не только число запросов. Руководство рекомендует кастомный status line, непрерывно показывающий процент заполнения контекста. На уровне gateway аналог — это запись утилизации context window по каждой сессии как временного ряда, а не только суммарных токенов по запросам. Именно эти данные позволяют поймать «убегающую» сессию до того, как она выест квоту, и поднять алерт, когда сессия пересекает 70% заполнения контекста, где начинается деградация качества.

Workflow с параллельными агентами требует атрибуции биллинга на агента. Если ваша команда выдаёт каждому разработчику персональный API-ключ для Claude Code, вы получите расход по разработчику, но не по сессии или задаче. Если все сессии идут через общий ключ gateway, вы получите агрегированную сумму, но потеряете индивидуальную атрибуцию. Правильная схема — gateway, сегментирующий и по идентичности пользователя, и по session ID, — тогда на вопрос «какая задача сожрала больше всего контекста на прошлой неделе» можно ответить без ручного парсинга логов.

Правила routing для CLAUDE.md. Паттерн CLAUDE.md из руководства имеет прямой аналог на стороне gateway: управление системным prompt. Команды, конфигурирующие Claude Code разными CLAUDE.md под окружения (production vs. staging, frontend vs. backend в монорепо), по сути задают разные системные промпты для разных контекстов. Если эти сессии идут через gateway, он должен относиться к конфигурациям, выведенным из CLAUDE.md, как к измерению политики, а не как к невидимой клиентской настройке.

За чем следить и что попробовать

• Измеряйте заполнение контекста на сессию, а не только токены на запрос. Если логи gateway показывают суммарные токены, но не утилизацию context window внутри сессии, вы упускаете главный драйвер стоимости агентных нагрузок. Добавьте теггинг по session ID и метрику заполнения контекста.

• Поднимите алерты на расход по сессии до того, как масштабируете параллельные workflow. Руководство явно одобряет параллельные sub-агенты. До того как команда начнёт гонять по пять агентов одновременно, настройте на уровне gateway алерты по расходу на пользователя или на сессию, чтобы ловить убегающие сессии до того, как они выест дневную квоту.

• Аудитируйте токеновую стоимость CLAUDE.md раз в квартал. Прикидка простая: строк в CLAUDE.md × среднее число сессий в день × стоимость за токен. Если получается больше 5% от общего расхода — пора прореживать. Руководство советует оставлять в CLAUDE.md только то, что Claude не может вывести сам; относитесь к этому как к дисциплине затрат, а не только к гигиене ясности.

• Сконфигурируйте политику routing на переполнение контекста. Если routing-слой это поддерживает, определите, что должно происходить, когда сессия Claude Code запрашивает context window, превышающий лимит модели: апгрейд на модель с бо́льшим контекстом, сброс сессии или алерт. Аккуратно обработанное переполнение контекста невидимо для разработчика; обработанное плохо — даёт молчаливую деградацию качества, которую тяжело отлаживать.

TheRouter маршрутизирует API-вызовы моделей и фиксирует потребление токенов по сессиям. Для workflow Claude Code ключевые добавки в телеметрии — это трекинг session ID и утилизация context window на сессию, чтобы модель стоимости токенов отражала агентную реальность: одна задача разработчика растягивается на десятки API-вызовов в рамках одного бюджета контекста. Команды, использующие TheRouter, могут опираться на трекинг расхода по ключу или по тегу как на приближённую атрибуцию по сессиям, пока нативные метаданные session ID не появятся как первоклассная фича.