Контекст для ИИ-агента: 5 правил отбора нужных файлов в 2026

Контекст включает отобранные файлы, сведения о задаче, ограничения и ожидаемый результат, но не весь проект. Чем точнее набор контекста, тем меньше лишних вопросов и неверных изменений. Если агент выходит за пределы задачи, сначала проверь, заданы ли в запросе файлы, ограничения и критерий готовности.

Что такое значимый контекст для агента?

Anthropic формулирует этот принцип так:

Слово «минимальный» здесь не означает короткий. Если для изменения формы нужны типы, API и тест, их нельзя выбрасывать ради экономии. Минимум означает отсутствие лишнего материала.

Для задачи полезна карта контекста. Я разделяю контекст на два слоя:

• Постоянный слой. Правила проекта, команды сборки и тестирования, стиль кода, устройство окружения, ограничения.
• Рабочий слой. Файлы, данные и решения только для текущей задачи.

Постоянный слой не должен превращаться в энциклопедию. Рабочий слой не должен превращаться в копию всего репозитория. Агенту нужны сведения для ближайшего решения. Само по себе увеличение объёма контекста не гарантирует пользы и может снижать фокус модели.

Какие данные и файлы передать агенту?

В CLAUDE.md Anthropic предлагает держать команды, ключевые файлы, стиль, правила тестирования, окружение и неожиданные ограничения. Это постоянные сведения. Их не надо заново вставлять в каждый запрос.

Тема контекста связана с практикой шире одного промпта. На практикуме по вайб-кодингу я показываю руками, как собирать карту задачи, разделять постоянные правила и рабочие файлы, а затем принимать результат по проверяемому критерию.

Для рабочей задачи собери такой набор:

• цель изменения;
• файл, который точно изменится;
• связанные типы или схему данных;
• API или функцию, через которую проходит изменение;
• тесты и команду проверки;
• конфигурацию, если она влияет на поведение;
• ограничения: что нельзя менять и какой результат нельзя сломать.

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

• путь к каталогу;
• имя функции или компонента;
• строка поиска;
• диапазон строк;
• имя таблицы или поля;
• ссылка на файл с правилами.

Такой подход позволяет агенту собирать понимание по частям, если инструменты и критерии поиска настроены корректно. Anthropic описывает этот подход как постепенную сборку понимания: агент получает указатель, выполняет поиск и подгружает данные по необходимости.

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

Как собрать контекст проекта?

Дальше я использую такую последовательность.

1. Определи точку изменения.

   Запиши, что должно измениться и где пользователь увидит результат.

   Посмотри корневые правила проекта. Найди команду проверки и файл, который отвечает за нужное поведение.

2. Собери обязательные пути.

   Добавь целевой файл, тесты, типы, API и конфигурацию, если они связаны с задачей.

   Не копируй содержимое заранее. Сначала передай пути и попроси агента подтвердить связи между ними.

3. Оставь поиск на потом.

   Вынеси в отдельную зону похожие реализации, документацию и историю изменений.

   Эти материалы агент ищет только при необходимости. Они не должны попадать в каждый запрос автоматически.

4. Задай запреты.

   Запиши каталоги, секреты, сгенерированные файлы и соседние части проекта, которые нельзя читать или менять.

   Файловая граница ограничивает, какие пути агент может читать и изменять в sandbox. Сетевая граница определяет, к каким доменам ему разрешён доступ. Настройка обеих границ описана в материале Anthropic о sandbox.

5. Зафиксируй проверку.

   Укажи команду, тест или наблюдаемый результат, который покажет готовность.

   Одного сообщения «готово» недостаточно. Нужен результат проверки, по протоколу проверки после каждой правки.

Модель карты выглядит так:

Задача:
Что должно измениться:

Постоянные правила:
- CLAUDE.md
- команды проверки
- ограничения проекта

Прочитать обязательно:
- путь к целевому файлу
- путь к тестам
- путь к типам или API
- путь к конфигурации

Найти по необходимости:
- связанные реализации
- документацию
- похожие компоненты
- историю изменений

Не читать и не менять:
- секреты
- соседние проекты
- сгенерированные файлы
- нерелевантные каталоги

Проверка:
- команда
- ожидаемый результат

Такой список лучше длинной инструкции на все случаи. Агент видит рабочую область, но не получает разрешение бесконтрольно ходить по проекту.

Как описать контекст запроса?

Стартовая просьба может выглядеть так:

Задача: изменить поведение формы регистрации.

Сначала найди релевантные файлы и объясни связи между ними:
- компонент формы;
- типы данных;
- API;
- тесты;
- конфигурация, если она влияет на поведение.

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

Код пока не меняй. Если сведений не хватает, сначала назови конкретный путь или факт, который нужно найти.

В хорошем запросе нет просьбы «сделай красиво» без критерия. Есть наблюдаемый результат: что должно появиться, сохраниться или перестать происходить.

Ограничения пиши отдельно. Например: не менять API, не трогать миграции, сохранить формат ответа, не переписывать соседние компоненты. Это не гарантирует идеальное поведение, но сужает пространство решений.

Первую проверку тоже задавай заранее. Агент должен знать, что делать после плана: открыть тест, выполнить команду, найти обработчик или проверить конкретный сценарий.

Как понять, что контекста уже достаточно?

Проверь пять признаков:

1. Агент может одним предложением повторить, что должно измениться.
2. Агент называет файлы, которые нужно прочитать или изменить.
3. Агент видит запреты и границы рабочей области.
4. Агент знает, чем проверить готовность.
5. Агент называет ближайшее действие вместо пересказа проекта.

Если одного признака нет, добавь недостающий указатель. Не отправляй весь диалог заново. Передай путь, имя функции, найденную строку или короткий результат поиска.

Материалы удобно разделить на три категории:

• Обязательные. Без них решение может сломать задачу.
• Проверочные. Нужны, чтобы подтвердить изменение.
• По необходимости. Агент загружает их только после разведки.

Для узкой разведки я использую sub-agent. Даю ему узкую роль, понятный результат и короткий возврат в основной контекст, как в сценарии с read-only-субагентом. В ответе прошу пути, факты, риски и следующий шаг. Общая оценка «всё нормально» не помогает главному агенту продолжить работу.

Почему большой контекст мешает?

В одном issue Claude Code показал первые 2 171 строки CSS-файла и добавил в контекст 62 374 токена. После этого даже простой запрос continue начал падать с ECONNRESET. Для больших файлов сначала сужай область через Grep, а потом читай конкретный фрагмент.

rg -n "название-функции|название-класса|уникальная-строка" path/to/project

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

В другом случае контекст вырос примерно с 50 000 до 692 190 токенов за 923 сообщения. Автор связывает основной рост с накоплением system-reminder после изменений файлов, но отмечает, что вклад других источников контекста не исключён. Поэтому этот случай не следует считать описанием стабильного поведения всех версий Claude Code.

Корневой CLAUDE.md загружается в каждую сессию, поэтому нерелевантные инструкции увеличивают контекст, как объясняет материал Anthropic. Держи постоянные правила короткими, а локальные инструкции не складывай в корневой файл без причины.

Сжатие истории помогает, но не превращает её в надёжную память. /compact заменяет старую историю кратким описанием. При сжатии могут потеряться детали, если они не были вынесены в устойчивую внешнюю заметку. В одном issue ручной /compact завершался ошибкой лимита даже при отображаемом использовании около 20%.

Перед сжатием сохрани:

1. текущую цель;
2. изменённые файлы;
3. решения и ограничения;
4. известные риски;
5. оставшиеся действия;
6. команду проверки.

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

Что делать, если агент загружает лишние файлы?

Лишний контекст появляется и без явной команды Read. В issue #4464 описан случай, когда системные напоминания автоматически вставляли полное содержимое изменённого JSON. Пользователь не просил читать файл, но он всё равно попадал в историю.

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

Аварийная схема:

1. Останови агента, если он начал менять нерелевантные файлы.
2. Сохрани состояние задачи во внешнем файле.
3. Запиши пути, диапазоны строк, факты, риски и следующий шаг.
4. Начни новую сессию.
5. Передай только карту и обязательные материалы.
6. Проверь изменённые файлы отдельно.

Внешний файл хранит состояние задачи. /compact сжимает историю. Это разные действия. Сжатие не гарантирует сохранение всех деталей.

Для результата sub-agent используй короткий формат:

Файл:
Диапазон строк:
Факт:
Риск:
Следующий шаг:

Если в основной контекст возвращается только общая оценка, исследование придётся повторять. Путь и конкретный факт ценнее длинного журнала действий.

Вопросы и ответы