Контекст в кодовой базе: файлы правил, skills и прогрессивное раскрытие

Техники предыдущих частей работают внутри одной сессии или поверх накопленной памяти. Эта часть — про контекст, который живёт в кодовой базе постоянно: файлы правил, skills и прогрессивное раскрытие.

Контекст в кодовой базе: файлы правил, skills и прогрессивное раскрытие

Файлы правил, skills, спеки и индексы в репозитории — это контекст, за который ты платишь каждой сессией, пригодился он или нет. Поэтому главный вопрос раздела — в какой момент текст попадает в окно. Ответ индустрии — прогрессивное раскрытие.

Прогрессивное раскрытие: три уровня

Barry Zhang и Mahesh Murag из Anthropic («Don't Build Agents, Build Skills Instead») описывают механизм так: skill — это просто папка с файлами, и в рантайме модель видит только метаданные скилла. Когда скилл нужен, читается SKILL.md с основной инструкцией и оглавлением папки. Всё остальное открывается по необходимости. Цель дизайна названа прямо: «защитить context window, чтобы в него влезли сотни скиллов и они были композируемы».

Раскладка по токенам (DataRobot, «Skills are the New SDKs», и IBM Technology):

Уровень 1 — фронтматтер, всегда в системном промпте: обычно меньше 100 токенов на skill. Это «оглавление» всех доступных скиллов.

Уровень 2 — тело markdown, читается только при активации: обычно меньше 5K токенов.

Уровень 3 — всё остальное: скрипты, references/, assets/. Скрипт либо исполняется, и в контекст возвращается только вывод, либо служит примером кода.

Без этого механизма, как формулирует DataRobot, сотня skills «сожгла бы бюджет токенов ещё до первого вопроса». Отсюда следствие для того, как писать skill: description во фронтматтере всегда в контексте, а тело — нет. IBM подчёркивает, что description работает как триггер («use this when the user asks to...»), и сопоставление задачи со скиллом делает сама модель своим рассуждением — качество description критично, качество тела влияет только после активации.

Сколько стоит MCP и сколько стоят skills

Самое важное сравнение стоимости — у DataRobot. Подключённые MCP-серверы платят полную цену определений инструментов в каждой сессии до начала разговора: 15 MCP-серверов — больше 100 000 токенов только в описаниях инструментов. Skills за счёт прогрессивного раскрытия дают ту же операционную функциональность примерно в 10 раз дешевле. Докладчик оговаривается, что цифры оценочные и методика не приведена, — но порядок величины проверяется у себя за пять минут.

Похожий бытовой замер из практики (Jono Catliff, «12 Rules»): описания подключённых MCP-инструментов заняли 24,1k токенов — 12% окна ещё до первого сообщения. Тоже порядок величины, не лабораторное измерение, но он объясняет, почему «контекст кончается ниоткуда»: восьмая часть окна уходит на инструменты, которые могут не понадобиться.

Из этого не следует «выключить MCP». Граница проходит по природе ресурса, и лучше всего её формулирует ведущий Confluent Developer: skills — это статическое справочное знание и локальная файловая система. MCP-ресурсы — живые данные (клиенты, тикеты, сообщение из Kafka прямо сейчас) и действия во внешнем мире, требующие аутентификации. DataRobot добавляет то же с другой стороны: MCP нужен там, где требуются аутентификация, изоляция процесса и «лошадиные силы» — GPU, семантический поиск по сотням терабайт. И наблюдение оттуда же: у Codex и Claude Code всего около десятка встроенных инструментов.

Файлы правил: раздувать почти не окупается

Здесь есть неудобный замер. Тот же практик (Jono Catliff) задал один и тот же вопрос — «объясни структуру проекта и предложи улучшения» — с CLAUDE.md на 910 строк и на 33 строки. Результат: 45% окна против 41%, разница в 4 процентных пункта.

Вывод здесь тоньше, чем «раздувай, всё равно дёшево»: раздувание файла правил почти не окупается. Ты платишь эти проценты каждым сообщением, а взамен получаешь текст, в котором 90% нерелевантно текущей задаче. Настоящая экономия приходит от выноса знания в skill: замер того же автора — отлаженный skill для разбора банковского CSV занял 27% окна против 45% при работе «через общий CLAUDE.md и серию уточняющих вопросов».

Что произошло: файл правил на 910 строк переписали в skills

• Кто: практик Jono Catliff, доклад «12 Rules» (бытовые замеры, порядок величины — не лабораторное измерение).
• Что делали: всё, что раньше сваливалось в один rules-файл и грузилось каждым сообщением, разбили на skills по воркфлоу. Общие куски (tone of voice, banned phrases) вынесли в reference-файлы, на которые skill только ссылается: «открой, если понадобится, иначе пропусти».
• Результат: сокращение самого файла правил дало мало (с 910 до 33 строк окно ужалось с 45% до 41%). Вынос воркфлоу в skill — заметно больше: 27% против 45%. Skill в 31 строку со ссылками против 457 строк с зашитыми референсами — 25% против 31% окна на сообщение.
• Вывод: экономит перенос знания на уровень, загружаемый по требованию. Сценарии замеров несопоставимы (отлаженный скилл против хаотичного диалога) — доверять стоит направлению, а не точным числам.

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

Context priming вместо always-on файла (IndyDevDan): набор слэш-команд /prime, /prime_bug, /prime_feature со структурой purpose → run → read → report — каждая читает ровно те файлы, что нужны под свой тип задачи. В CLAUDE.md остаётся то, что нужно 100% агентов в 100% случаев. Замер автора: ~350 токенов в memory-файле против 23 000 до рефакторинга. Ограничение — надо помнить о запуске нужного prime.

Скоупы и подкаталоги (David Mahler): корень проекта, .claude/ (уезжает с git-клоном), ~/.claude (личные предпочтения) и CLAUDE.md в подкаталоге, который грузится только когда агент полез в файлы этой папки. Последнее — готовый механизм прогрессивного раскрытия по областям монорепо, и он сильно недооценён.

CLAUDE.md как слой маршрутизации (Ben AI, идею индексных файлов приписывает Karpathy): при большой базе корневой файл становится инструкцией навигации — где какой тип знания лежит, куда писать обновления, синтаксис ссылок. Дальше в каждой подпапке свой индексный файл, читаемый при заходе туда.

И отдельное правило от Ben AI, самое практичное при росте: skills должны ссылаться на общую базу вместо того, чтобы носить копии контекста. Если класть документы внутрь скилла, в references/, один и тот же файл дублируется по нескольким скиллам. Правильно — оставить в SKILL.md процесс и ссылки: тогда правка одного документа «обновляет» все скиллы разом.

Файл с диска вместо вставки в чат

Ещё один замер того же порядка величины: одно и то же содержимое, прочитанное агентом с диска, заняло 38% окна против 71% при вставке прямо в чат. Разница почти двукратная, объяснение простое: вставленный текст навсегда становится частью истории сообщений, а прочитанный файл — результат вызова инструмента, который можно вытеснить, ужать или перечитать позже.

Отсюда две привычки. Первая: клади содержимое в файл и давай агенту путь. Вторая, из «How AI Coding Agents Work» (The Working Thesis): ничего важного не оставляй висеть в чате — если агент выдал прекрасный markdown в ответе, попроси сохранить его в architecture_plan.md, иначе при компакции план на 500 слов превратится в пункт «brainstormed architecture». Тот же класс приёмов: разделять scratchpad (трекер прогресса, удаляется по завершении) и record-keeping файл, остающийся в репозитории как запись решений (Ragunath Jawahar), и класть в проектный файл явные compact instructions — что сохранять при сжатии (пример Anthropic: «focus on test output and code changes»).

Иерархия: плохая строка research дороже плохой строки кода

Dex Horthy из HumanLayer («Advanced Context Engineering for Agents») даёт правило, расставляющее приоритеты по всей цепочке: «плохая строка research порождает тысячи плохих строк кода». Отсюда раскладка бюджета: фаза research может занимать 60–80% окна, но её артефакт — то, что уходит дальше в реализацию, — ужимается до 15–20%. На исследование не жалко потратить почти всё окно, но передавать дальше нужно сжатый вычитанный результат без истории рассуждений.

Из той же практики — отношение к файлам правил как к продуктовому артефакту: CLAUDE.md и слэш-команды «мы буквально тестируем неделями, прежде чем кому-либо разрешено их менять». Прямая противоположность привычке дописывать строчку в CLAUDE.md после каждой неудачной сессии.

Skills, написанные моделью, измеримо вредят

Популярная идея self-evolving skills получает прямое опровержение от DataRobot со ссылкой на опубликованные исследования: skills, сгенерированные LLM, ухудшают производительность — тратят больше токенов и больше времени на рассуждение вместо того, чтобы ускорять работу и экономить контекст. Формулировка спикера: «skill ровно настолько хорош, насколько хорош человек, который его написал». Направление эффекта названо, точных чисел в докладе нет.

Практический вывод: модель может помогать писать skill, но приёмка и структура — на человеке, ровно как с кодом. Рядом вторая проблема — безопасность: skills исполняют скрипты локально с доступом к файловой системе, переменным окружения и API-ключам, изоляции процесса в отличие от MCP нет, а аудиты публичных скиллов находят prompt injection, tool poisoning и скрытую малварь (IBM Technology и DataRobot; упоминается репозиторий на 85 000 скиллов). Аналогия честная — NPM десять лет назад: ставь чужой skill как обычную зависимость, с ревью.

Anthropic отдельно перечисляет нерешённое: тестирование и eval скиллов; тулинг, проверяющий, что агент подтянул нужный скилл в нужный момент; версионирование; явные зависимости между skills, MCP и пакетами. Stephen Chin из Neo4j описывает ту же проблему с земли: иногда подгружается не тот скилл, а иногда отсутствует звено цепочки — есть навык «открыть раковину», нет навыка «съесть».

Как разложить репозиторий под агента

Сводя всё вместе:

В файлах правил — только то, что нужно 100% агентов в 100% случаев: как запускать тесты, жёсткие запреты, навигация по репозиторию. Добавь индексные файлы в подкаталогах, которые грузятся при заходе в область.

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

Скриптом внутри скилла оформляй всё, что модель раз за разом пишет заново. Три претензии Anthropic к инструментам: описания двусмысленны, модель не может починить инструмент, когда он мешает, и инструменты всегда живут в context window. Код лишён этих проблем и лежит на диске, пока не понадобится.

В спеках рядом с кодом — форматы и контракты. Zach Blumenfeld (Neo4j) описывает связку из CLI, умеющего отдавать схему, доменного skill и markdown-спеки формата в docs/: агент читает схему, пишет запрос и следует спеке вместо угадывания по промпту.

Состояние — наружу, в репозиторий. Beads (инструмент Steve Yegge в изложении Ragunath Jawahar): issue tracker внутри version control, задачи в JSONL коммитятся, SQLite — производный индекс. Это одновременно вынос состояния и координация параллельных агентов.

Два ограничения, чтобы не переоценить подход. Первое — масштаб: Stephen Chin (Neo4j) говорит, что в типовой раскладке из AGENTS.md, файлов памяти и файлов инструментов его агенты грузят минимум 100k токенов на каждый раунд, потому что тянут «всё подряд в надежде, что что-то пригодится». На малом масштабе с сильной моделью это работает, на большом — уже нет. Второе — позиция Emil Eifrem (Neo4j): «markdown-файлы — часть решения, но не решение». На десятках агентов данные дублированы и непонятно, какая копия правильная, ломается DRY, нет кросс-агентного обмена, потому что связь между намерением и источником зашита в код и промпты. Это позиция вендора графовой БД, но список проверяется самостоятельно.

Наконец, репозиторий надо чинить не только для агента, но и от агента. Cole Murray (OpenInspect) описывает деградацию кодовой базы до уровня худшего инженера: не проверяющий код разработчик цементирует свои паттерны, дальше AI читает их как норму и размножает — 12 разных хелперов форматирования даты. Лечится процессом: плановые чистки, контракты между модулями и lint-правила против «подписей» AI-кода (hasattr и getattr вместо прямого обращения, dict[str, Any]). Встречное требование от Cognition: репозиторий должен быть локально тестируемым — локальная БД, docker-compose с Postgres, — чтобы агент запускал код без продовых кредов.

Что с этим делать

Проведи аудит подключённых MCP. Посчитай, сколько токенов уходит на описания инструментов до первого сообщения (ориентир DataRobot — 15 серверов дают больше 100k). Оставь MCP там, где нужны живые данные, аутентификация или удалённое исполнение.

Переноси знание из файла правил в skills, не ограничиваясь сокращением файла. Сокращение даёт единицы процентов окна (с 910 до 33 строк окно ужалось с 45% до 41%), перенос в скилл — десятки (27% против 45%). В корневом файле оставь навигацию, остальное разложи по подкаталожным файлам и skills.

Читай файлы с диска вместо вставки в чат (38% против 71% окна) и сразу сохраняй в файл всё ценное из ответов агента — иначе компакция превратит план на 500 слов в один пункт списка.

Выстрой иерархию артефактов по правилу HumanLayer. Research может съесть 60–80% окна, но дальше передаётся сжатый артефакт на 15–20%.

Skills пиши руками. Сгенерированные моделью скиллы измеримо ухудшают работу (DataRobot). Чужие ревьюй как npm-зависимость — изоляции процесса у них нет. Свои версионируй в git и меняй файлы правил как продукт: HumanLayer тестирует их неделями.

Держи в скиллах ссылки на общие документы вместо их копий (Ben AI) и выноси повторяющийся код агента в скрипты внутри скилла — они не занимают окно.