Контекст Claude Code: как progressive disclosure экономит деньги

Контекст Claude Code — это бюджет, который расходуется при каждом действии агента. Когда он забит лишним, качество ответов падает, а стоимость сессии растёт. Именно поэтому в skills заложен механизм progressive disclosure — прогрессивного раскрытия: в контекст попадает ровно то, что нужно прямо сейчас, не больше.

Разберём, как это устроено, как проектировать skills по этому принципу и почему это важно на реальном проекте.

Почему контекст — это бюджет, а не свалка

Агент видит только то, что находится в контексте в данный момент: ваш запрос, прочитанные файлы, историю диалога, инструкции из CLAUDE.md, загруженные skills. Всё это потребляет токены — и за объём вы платите напрямую (деньгами или временем обработки).

Но есть второй, менее очевидный эффект: чем больше в контексте шума, тем хуже агент справляется с задачей. Когда рядом с нужной инструкцией лежат две тысячи слов справочного текста, который не нужен прямо сейчас, агент «тонет» в нём. Он охватывает весь контекст целиком, а не фокусируется на сути.

Хороший skill не пытается быть энциклопедией. Он отвечает на вопрос агента «что делать и куда смотреть за деталями» — и не более.

Три уровня загрузки: как устроены skills

Skills в Claude Code работают как трёхуровневая система. Каждый уровень попадает в контекст в разный момент:

Уровень	Что это	Когда в контексте	Типичный объём
1. Метаданные	name + description	Всегда	~100 слов
2. Тело SKILL.md	Сами инструкции	Когда skill сработал	держать < 200–300 слов
3. Ресурсы	references/, scripts/, assets/	Только когда тело за ними отправит	практически без лимита

Метаданные — это «вывеска». Они дёшево лежат в контексте всегда, именно поэтому можно держать десятки skills без боли за бюджет.

Тело подгружается целиком в момент срабатывания. Это значит, что каждое лишнее слово в теле — налог, который платится при каждом вызове skill. Тело должно быть навигатором: дать агенту ориентир и указать, куда идти за деталями.

Ресурсы лежат на диске и не занимают контекст, пока агент их не прочитает. Сюда идут длинные справочники, таблицы соответствий, наборы примеров, шаблоны файлов.

Отдельный нюанс — scripts/: скрипт можно запустить, не грузя его текст в контекст. Детерминированную логику (генерацию файлов по шаблону, форматирование, проверки) выгоднее оформить скриптом, чем описывать словами в теле.

О том, что такое skills в принципе и как они устроены изнутри, — в отдельной статье.

Анатомия раздутого skill и его проблемы

Вот типичный «плохой» skill для создания React-компонентов:

---
name: react-component
description: Помогает с компонентами React и фронтендом.
---

# Создание React-компонента

(2500 слов: история хуков, полный гайд по TypeScript-типам,
12 примеров компонентов целиком, таблица ESLint-правил,
рассуждения про CSS-модули, правила тестирования...)

Три проблемы сразу:

1. Description размытый — «помогает с фронтендом» — skill будет срабатывать невпопад или не срабатывать вовсе.
2. Тело-энциклопедия — при каждом срабатывании 2500 слов въезжают в контекст, 90% которых для конкретной задачи не нужны.
3. Шум мешает точности — агент видит всё разом, ему труднее выделить главное.

Как применить progressive disclosure: практический разбор

Тот же навык в компактном варианте выглядит иначе. Структура файлов:

react-component/
├── SKILL.md            (~40 строк)
├── references/
│   ├── prop-typing.md
│   └── eslint-rules.md
└── assets/
    └── component.tsx.template

Тело skill:

---
name: react-component
description: This skill should be used when the user asks to "создай компонент",
"сделай React-компонент", "добавь компонент по конвенциям", or mentions
создание UI-компонента в этом проекте.
---

# React-компонент по конвенциям проекта

1. Взять шаблон из `assets/component.tsx.template`.
2. Имя файла и компонента — по правилам из `references/naming` (PascalCase).
3. Типизировать пропсы согласно `references/prop-typing.md`.
4. При сомнениях по стилю — сверить с `references/eslint-rules.md`.
5. Добавить базовый тест рядом с компонентом.

Что изменилось:

• description конкретный с триггер-фразами → skill срабатывает надёжно и только тогда, когда надо.
• Тело — навигатор на 5 шагов: агент сразу знает, что делать.
• eslint-rules.md на 2000 слов загрузится в контекст только если агент реально засомневается в стиле — а не каждый раз.

Было 2500 слов при каждом срабатывании. Стало ~150 слов тела и точечная подгрузка по необходимости.

Что куда класть: правило раскладки

В тело SKILL.md:

• Краткое назначение (1–2 предложения).
• Шаги высокого уровня — что делать и в каком порядке.
• Ключевые правила, без которых результат будет неверным.
• Ссылки на ресурсы: «подробные конвенции — см. references/naming.md».

В references/:

• Длинные справочники, таблицы соответствий.
• Редко нужные крайние случаи.
• Подробные примеры «было/стало».

В scripts/:

• Детерминированные операции, которые лучше выполнить, чем описать.

В assets/:

• Шаблоны файлов, заготовки — то, что идёт в результат как есть.

Признаки, что пора выносить из тела: тело перевалило за пару экранов, большая часть текста не нужна на типичном срабатывании, в теле есть повторяющиеся шаблоны кода.

На реальном проекте: CoffeeCRM

На практике это ощущается сразу. Представьте skill crud-entity для CoffeeCRM (Next.js + NestJS + PostgreSQL): если свалить в тело все конвенции именования, правила миграций, шаблоны контроллеров и схемы DTO — получится портянка, которая грузится при каждом «создай сущность Product».

Правильный подход: тело описывает порядок — создать модуль, сгенерировать сущность, добавить миграцию, создать DTO. Детали конвенций — в references/naming.md. Шаблоны — в assets/. Скрипт генерации модуля — в scripts/generate-module.sh.

В итоге типичный вызов skill загружает ~200 слов вместо 3000. Детали подтягиваются только когда нужны. Агент работает точнее, а бюджет расходуется рационально.

Настройка CLAUDE.md под проект — отдельная тема: как направлять контекст через инструкции и что грузить при старте сессии — разбираем в статье про настройку CLAUDE.md.

Как рефакторить раздутый skill: агент делает это сам

Мета-приём: попросить Claude Code переложить раздутый skill по принципу progressive disclosure. Запрос выглядит примерно так:

Это раздутый skill. Примени progressive disclosure: оставь в теле SKILL.md
только назначение, шаги и ссылки на ресурсы; справочные простыни вынеси
в references/, шаблоны — в assets/. Description сделай конкретным с
триггер-фразами.

После этого нужно проверить: тело сократилось, появились references/ и assets/, ссылки из тела корректны, skill по-прежнему срабатывает на нужные фразы.

Важно: информация не выбрасывается, она перекладывается на правильный уровень. Ничего не теряется, контекст разгружается.

Подробнее о том, как именно агент работает с контекстом и инструментами, — в статье «Что такое Claude Code».

Вывод

Progressive disclosure — не тонкая оптимизация, а базовый принцип проектирования skills. Три уровня: метаданные как вывеска, тело как навигатор, ресурсы как детали по требованию. Каждый уровень загружается в нужный момент и не раньше.

Результат: агент работает точнее, сессия стоит меньше, а навыки масштабируются без боли — можно держать десятки skills, не жертвуя бюджетом контекста.

Если хотите освоить проектирование skills и управление контекстом системно — от первого skill до CRUD-генератора на реальном проекте — посмотрите полный курс по Claude Code.