Context for coding agents

Средний рабочий репозиторий — миллионы токенов; даже гигантское окно его не вместит, а если бы и вместило — context rot сделал бы это бессмысленным. Кодинг-агенту нужна не полнота, а ориентация: понимать, где что лежит, и уметь дочитать точечно. Решение — карта репозитория: дерево ключевых каталогов с назначением каждого, входные точки, основные модули и связи между ними. Хорошая карта помещается в 1–2 тысячи токенов и отвечает на вопрос «куда смотреть», а не «что там написано».

Дальше работает прогрессивное раскрытие: агент по карте выбирает область, ищет grep-ом конкретные символы, читает только нужные файлы — и лучше не целиком, а диапазонами строк. Это агентный поиск из третьего урока в чистом виде: вместо предзагрузки «всего, что может пригодиться» — точечное дочитывание по мере необходимости. Файловая система выступает внешней памятью, а контекст хранит только пройденный маршрут.

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

CLAUDE.md (и его аналоги вроде AGENTS.md) — файл, который агент автоматически получает в начале каждой сессии. Это самая дорогая недвижимость контекста: он в стабильном префиксе, читается всегда — и поэтому должен окупать каждую строку. Что туда входит: команды сборки, тестов и линта (точные, копируемые); карта архитектуры на пару абзацев; конвенции проекта (стиль импортов, нейминг, правила коммитов); и грабли — неочевидные факты, на которых агент уже ошибался: «порт 8788, не 3000», «restart не перечитывает env, нужен force-recreate».

Чего там быть не должно: копипасты чужой документации (протухает и дублирует то, что модель знает), генерируемых списков файлов (устаревают при первом же рефакторинге), длинных историй принятия решений (им место в памяти или ADR). Ориентир по размеру — сотни строк, не тысячи: CLAUDE.md на 3 000 строк — это уже свалка, в которой тонут действительно важные правила.

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

Для конкретной задачи кодинг-агенту нужен минимальный точный набор, а не «всё, что связано». Золотой состав контекста для багфикса: текст падающего теста и его вывод дословно; сообщение об ошибке с первыми строками stack trace как есть, без пересказа; git diff, если баг появился после изменений; и только те файлы, через которые проходит путь ошибки. Всё — со ссылками на точные пути и строки.

Ошибки — особый случай: их нельзя перефразировать. «Тест падает с ошибкой про типы» — мусорный контекст; полный текст TS-2345 со строкой и файлом — рабочий. То же с воспроизведением: команда, которая падает, и её вывод ценнее абзаца описания. Если агент сам запускает тесты — ещё лучше: свежий вывод инструмента надёжнее любого пересказа в истории.

Обратная сторона — жёсткая граница области. Лишний файл с похожим кодом — дистрактор, повышающий шанс правки не в том месте; устаревший коммент в контексте может увести гипотезу в сторону. Формулируйте границу явно: «правь только src/lib/utils/date.ts, тесты не трогай». Хорошая эвристика: если фрагмент не понадобится для проверки решения, ему нечего делать в контексте постановки. Задача контекст-инженера здесь — собрать досье, а не библиотеку.

Самый мощный приём управления контекстом в кодинге — вынести грязную работу в суб-агента с собственным окном. Поиск по большому репозиторию — это десятки grep-ов и чтений: 50–100 тысяч токенов промежуточного шума. Если всё это течёт в основной контекст, оркестратор захлёбывается за пару задач. Суб-агент сжигает эти токены в своём изолированном окне и возвращает наверх только результат: «функция определена в src/lib/auth.ts:142, используется в трёх местах, вот сигнатура» — сводку на 1–2 тысячи токенов.

В мультиагентной исследовательской системе Anthropic этот паттерн дал измеримый эффект: оркестратор с параллельными суб-агентами обошёл одиночного агента примерно на 90% на внутреннем эвале исследовательских задач — именно за счёт того, что каждый суб-агент тратит своё окно на свою ветку поиска. Цена тоже измерима: агенты расходуют примерно в 4 раза больше токенов, чем чат, а мультиагентные системы — до 15 раз, поэтому паттерн окупается на задачах, где ценность результата высока.

Практические правила: суб-агент получает узкое задание и формат ответа («верни пути, сигнатуры и краткий вывод, не более N строк»); читающие суб-агенты параллелятся свободно, пишущие — разводятся по файлам или worktree; оркестратор не перечитывает работу суб-агента, а доверяет сводке с проверяемыми ссылками. Так основное окно остаётся чистым на протяжении всей задачи — это и есть контекст-инжиниринг в действии.