Контекстная инженерия для ИИ-агентов: руководство

Контекстная инженерия — это решение о том, что ИИ-агент кодинга видит на каждом шаге: какие инструкции, файлы правил, определения инструментов, прочитанные файлы, результаты инструментов и история лежат в его контекстном окне, а что остаётся за его пределами. Для агентов кодинга это обычно важнее, чем шлифовка промпта: промпт, который вы набираете, — лишь малая часть того, что читает модель. Большую часть окна занимают файлы правил, вывод инструментов и весь предыдущий диалог. Держите этот контекст небольшим и релевантным — и результат будет лучше, чем от любой переформулировки промпта.

В этом руководстве разберём, что попадает в контекст агента, почему длинный контекст деградирует, какие приёмы помогают и как понять, что они работают. Данные о Claude Code и Codex актуальны на октябрь 2026 года.

Что такое контекстная инженерия

Инженерная статья Anthropic Effective context engineering for AI agents (29 сентября 2025 года) определяет контекст как набор токенов, включаемых при генерации ответа модели, а контекстную инженерию — как отбор и поддержание наилучшего набора этих токенов во время инференса.

Отличие от промпт-инжиниринга — в охвате и во времени:

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

Что попадает в контекст агента кодинга

До вашего первого сообщения и по ходу сессии:

• Системный промпт и встроенные инструменты. Их задаёт CLI. Вы их не контролируете, но платите за них на каждом шаге.
• Файлы правил. CLAUDE.md для Claude Code, AGENTS.md для Codex и многих других агентов. Они загружаются в начале сессии.
• Определения инструментов и MCP. У каждого инструмента, который может вызвать агент, есть имя и описание. MCP-серверы добавляют новые. Claude Code откладывает загрузку полных определений MCP-инструментов до их использования, поэтому сразу загружаются только имена и инструкции серверов.
• Извлечённое содержимое. Файлы, которые читает агент, результаты поиска, документация, которую он подтягивает.
• Результаты инструментов. Прогоны тестов, логи сборки, git diff, запросы к базе, снимки страниц.
• История диалога. Ваши сообщения, ответы агента и каждая неудачная попытка.

Чтобы оценить постоянную часть: мы измерили первый запрос Claude Code — около 34,4 тыс. токенов в стандартной конфигурации и около 13,3 тыс. в облегчённой (см. нашу статью о расходе токенов). Эта база отправляется заново на каждом шаге. Подробности о /context, /compact и /clear в Claude Code — в руководстве по контекстному окну Claude Code.

Почему больше контекста не значит лучше: context rot

У контекстного окна есть жёсткий предел, но мягкий наступает раньше. Статья Anthropic описывает «бюджет внимания»: трансформеры связывают каждый токен с каждым другим, так что n токенов дают n² попарных связей, и каждый новый токен ещё сильнее размывает внимание. Чем больше заполнено окно, тем хуже модель вспоминает то, что в нём лежит.

Независимые исследования показывают то же самое. В отчёте Context Rot компании Chroma (14 июля 2025 года) проверили 18 моделей и выяснили, что во всех экспериментах качество падает с ростом длины входа, даже на простых задачах. Несколько выводов, важных для кодинга:

• Даже один отвлекающий фрагмент — текст, который выглядит релевантным, но таким не является, — снижал точность, и эффект усиливался с ростом длины входа.
• В бенчмарке на длинную память все модели справлялись заметно лучше с коротким сфокусированным промптом примерно на 300 токенов, чем с полным промптом примерно на 113 тыс. токенов.

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

Приёмы, которые работают

Ниже — приёмы из статьи Anthropic, переложенные на то, что вы делаете с агентом кодинга.

1. Короткие файлы правил с узкой областью действия

Файлы правил оплачиваются в каждой сессии, поэтому каждая строка должна оправдывать своё место. Документация по памяти Claude Code советует держать каждый CLAUDE.md короче 200 строк и отмечает, что длинные файлы соблюдаются хуже. Вместо одного длинного файла:

• Правила для части кода кладите в .claude/rules/ с полем paths. Они загружаются, только когда Claude читает или редактирует подходящий файл.
• Используйте вложенные CLAUDE.md в подпапках. Claude Code загружает их по требованию, когда начинает работать в этой папке.
• Помните, что импорты @path упорядочивают файл, но не снижают его стоимость: импортированные файлы загружаются вместе с импортирующим.

---
paths:
  - "src/api/**/*.ts"
---

# Правила API

- Проверяй тело каждого запроса общей схемой.
- Возвращай ошибки в стандартном формате ошибок.

Codex работает похоже с AGENTS.md: он читает глобальный файл из ~/.codex, затем по одному файлу на каталог от корня проекта до рабочей папки; более близкие файлы идут позже и имеют приоритет. Добавление файлов прекращается при достижении project_doc_max_bytes, по умолчанию 32 КиБ. Что писать в эти файлы, мы разобрали в руководстве по CLAUDE.md и AGENTS.md.

По содержанию Anthropic советует писать на «правильной высоте»: достаточно конкретно, чтобы направлять поведение, и достаточно обобщённо, чтобы не зашивать хрупкую логику if-else. Несколько показательных примеров работают лучше длинного списка пограничных случаев.

2. Извлекать по требованию

Вместо того чтобы загружать всё заранее, держите лёгкие ссылки (пути к файлам, имена функций, ссылки) и позвольте агенту загружать содержимое, когда оно понадобится. Anthropic приводит в пример Claude Code: он находит файлы через glob и grep, а большие данные просматривает с помощью head и tail, не загружая их целиком. На практике:

• Укажите агенту конкретный файл или символ вместо просьбы «осмотреться».
• Просите структуру файла или диапазон строк, прежде чем читать большой файл целиком.
• Держите в файле правил короткую карту репозитория (где лежит API, где тесты), а остальное пусть агент подтягивает сам.

3. Изолировать работу в субагентах

Субагент работает в собственном чистом контекстном окне. Он может потратить десятки тысяч токенов на исследование и вернуть только сжатое резюме; по словам Anthropic, такие резюме часто занимают от 1000 до 2000 токенов. Хорошие кандидаты — исследование кодовой базы, чтение длинных логов и ревью диффа в свежем контексте.

Субагенты не бесплатны. В статье Anthropic о мультиагентной исследовательской системе (13 июня 2025 года) сказано, что агенты расходуют примерно в 4 раза больше токенов, чем чат, а мультиагентные системы — примерно в 15 раз больше. Вы покупаете чистую основную ветку, а не меньший счёт.

4. Сжимать и убирать старые результаты инструментов

Сжатие (compaction) суммирует диалог, приблизившийся к пределу, и продолжает работу от резюме. Anthropic называет очистку старых результатов инструментов одной из самых безопасных форм сжатия: агенту редко нужен сырой вывод теста сорокашаговой давности. На стороне API анонс Anthropic об управлении контекстом (29 сентября 2025 года) сообщал, что редактирование контекста, удаляющее устаревшие вызовы и результаты инструментов, сократило расход токенов на 84% в оценке веб-поиска на 100 шагов.

В CLI для кодинга направляйте резюме сами, а не ждите, пока оно сработает на пределе:

/compact Сохрани список изменённых файлов, падающий тест и решение по API

А когда переходите к несвязанной задаче, начните новую сессию вместо сжатия старой.

5. Дать агенту заметки вне окна

Структурированные заметки — это когда агент записывает прогресс в файл и потом перечитывает его. Среди примеров Anthropic — файл NOTES.md и списки задач. Так работает и автопамять Claude Code: индекс MEMORY.md для каждого репозитория, первые 200 строк или 25 КБ которого загружаются в начале каждой сессии. Для нескольких агентов и сессий общая память проекта идёт дальше; о ней мы рассказали в статье об общей памяти для AI-агентов.

6. Карта кода вместо слепого поиска

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

7. Короткий вывод инструментов

Результаты инструментов часто самая объёмная и шумная часть окна. Статья Anthropic Writing effective tools for agents (11 сентября 2025 года) рекомендует пагинацию, выбор диапазона, фильтрацию и обрезку с разумными значениями по умолчанию и сообщает, что Claude Code по умолчанию ограничивает ответы инструментов 25 000 токенов. Ту же идею можно применять снаружи:

• Запускайте один тестовый файл, а не весь набор.
• Фильтруйте логи через grep или tail, прежде чем агент их прочитает.
• Предпочитайте точечную CLI-команду инструменту, который возвращает целую страницу или таблицу.
• Отключайте MCP-серверы, которые проекту не нужны.

Как измерять контекстную инженерию

Без измерений вы снова гадаете. Полезные сигналы:

• Разбивка. /context в Claude Code показывает, что занимает окно по категориям и какие файлы правил и памяти загружены. Проверяйте её после изменений в файлах правил или настройке MCP.
• Токены на задачу. Сравнивайте похожие задачи до и после изменения, а не отдельные сессии.
• Повторные поправки. Если вы снова и снова повторяете правило, его либо нет в файле правил, либо оно там затерялось.
• Успех с первой попытки. Меньше уточняющих промптов на сопоставимых задачах — вот результат, который вам на самом деле нужен.
• Признаки деградации. Повторное чтение файлов, забытые ранние инструкции, возврат к отвергнутому подходу. Заметили — сожмите контекст или начните заново.

Меняйте одну переменную за раз. В мультиагентной статье Anthropic расход токенов сам по себе объяснял около 80% разброса качества в оценке BrowseComp — напоминание о том, что больше токенов может выглядеть как лучший результат. Сравнивайте стоимость и качество вместе.

Чек-лист

Где здесь AgentVera

AgentVera запускает Claude Code, Codex и другие CLI-агенты рядом в одном десктопном приложении. Она не заменяет описанные привычки, но ряд функций применяет их к каждому запущенному агенту. Всё это описано на страницах функций:

• Экономия токенов: профили контекста, уменьшающие стартовую базу, размер контекста в реальном времени в каждой панели, автосжатие, включённое по умолчанию с порогом 150 тыс. токенов через собственную команду каждого CLI, и RTK, который сокращает вывод тестов, сборки и git до того, как он попадёт к модели.
• Карта проекта: локальный индекс символов, импортов, тестов и файлов, которые меняются вместе; агенты обращаются к нему через MCP-инструменты agentvera-map, например map_related и map_outline. Вкладка AI ROI сравнивает диалоги, где карта использовалась, с теми, где нет, в том числе по токенам на задачу.
• Brain: память проекта, собранная из документации, коммитов, PR и диалогов агентов. Агенты ищут в ней через brain_recall и сохраняют поправки через brain_remember; новым агентам можно выдавать необязательный контекстный пакет объёмом до 2500 символов.
• Умные инструменты для Claude Code: отклоняют повторное чтение неизменённого файла, сначала выдают структуру большого файла и сужают полный прогон тестов до затронутых тестов.

Если вы работаете с одним агентом в одном терминале, приёмы из этой статьи прекрасно работают и сами по себе: /context, /compact и ухоженный файл правил решают большую часть задачи. AgentVera полезнее всего, когда вы запускаете несколько агентов и хотите применять ко всем одну и ту же дисциплину контекста. Её можно скачать и попробовать на одном проекте.

Итоги

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