Контекст-инжиниринг агентов

Один и тот же агент с одним и тем же промптом в одном репозитории работает отлично, а в другом спотыкается на каждом шаге. Причина обычно не в формулировке — а в том, что модель видит: какие файлы, правила, инструменты и историю она получает на каждом ходу. Context engineering — это управление всей информационной средой агента, а не подбор отдельной инструкции. В статье — из каких источников складывается контекст, что и куда класть (rules, skills, hooks, subagents, память), как управлять переполнением окна и почему контекстные файлы — не панацея.

Содержание

От промпта к контексту
Источники контекста агента
Rules: AGENTS.md и постоянные инструкции
Skills и команды
Hooks: детерминированные проверки
Subagents: изоляция контекста
Управление окном: compaction, память и Tool Search
Agentic search против RAG
Не переусердствовать: что говорят исследования
Ключевые тезисы для интервью
Заключение
Полезные ссылки

От промпта к контексту

Prompt engineering оптимизирует один запрос: формулировку, примеры, структуру. Context engineering управляет всем, что модель видит в момент решения задачи. Разница принципиальная: сколько бы вы ни улучшали текст задачи, агент не вспомнит соглашение, которого нет в контексте, и не применит команду, которой ему не дали.

Рабочее определение даёт Anthropic: context engineering — это «подбор минимального набора высокосигнальных токенов, максимизирующего вероятность нужного результата». Ключевое здесь — минимального. Контекстное окно — это не только лимит, но и бюджет внимания: чем больше в нём токенов, тем хуже модель извлекает нужное (эффект context rot и «lost in the middle», см. Ментальная модель LLM). Больше контекста — не лучше, а часто дороже и хуже.

Из этого следуют два практических принципа, на которых держится вся статья:

Постоянное — в rules/skills, одноразовое — в задачу. То, что повторяется в каждой задаче (стек, команды, запреты), живёт в конфигурации агента. То, что специфично для текущей задачи, — в сообщении. Смешение превращает rules-файл в свалку.
Контекст собирается just-in-time. Вместо того чтобы заранее загрузить всё, агент держит лёгкие указатели (пути, ссылки) и подтягивает данные по мере необходимости через инструменты. Anthropic описывает эту модель так: CLAUDE.md кладётся в контекст заранее, а glob/grep позволяют агенту исследовать репозиторий по ходу работы.

Важно и то, что context engineering — часть более широкого понятия harness (всё в агенте, кроме самой модели: цикл, инструменты, права, правила). Устройство harness разбирается в статье Агентские инструменты разработки; здесь мы смотрим на информационную часть — что именно подаётся модели.

Источники контекста агента

Контекст неоднороден: разные источники загружаются в разное время и разными механизмами. Понимание этой таблицы — половина context engineering.

Источник	Кто загружает	Когда	Зачем
Rules (`AGENTS.md`/`CLAUDE.md`)	Среда	Каждая сессия, автоматически	Постоянные правила проекта
Skills / slash-команды	Агент	По релевантности задачи	Переиспользуемые workflow и процедуры
Hooks	Среда	На событиях цикла (до/после инструмента)	Детерминированный контроль
Subagents	Главный агент	При делегировании подзадачи	Изоляция контекста подзадачи
MCP-серверы	Среда	По подключению и вызову	Доступ к внешним данным и действиям
Память (memory)	Среда и модель	Начало сессии / по запросу	Факты, переживающие сессии
Открытые файлы, `grep`/`glob`	Агент	По ходу задачи (just-in-time)	Точные данные о коде

Общий принцип: чем раньше и чаще источник грузится, тем дороже он стоит и тем строже к нему требования. Rules видны в каждом запросе — значит, должны быть короткими. Файлы, которые агент открывает сам, — дешёвы и не требуют ручного курирования.

Отдельно стоит MCP — протокол, через который агент получает доступ к внешним инструментам и данным. Как протокол он разбирается в статье MCP: Model Context Protocol; здесь важно, что MCP-серверы — это дополнительный источник контекста (и токенов) в окне агента.

Rules: AGENTS.md и постоянные инструкции

Rules-файл (AGENTS.md, у Claude Code — CLAUDE.md) — постоянные инструкции проекта, которые среда добавляет к контексту в начале каждой сессии. Это аналог system prompt, живущий в репозитории.

Что класть, а что нет

Главное разделение — постоянное против одноразового:

В rules (постоянное)	В задачу (одноразовое)
Стек, менеджер пакетов, команды (test, lint, build)	Конкретный модуль, который трогаем
Соглашения по структуре каталогов	Что именно исправить в этом баге
Запреты (не менять конфиги, не ставить зависимости)	Критерии приёмки этой фичи
Неочевидные конвенции проекта	Доменные правила конкретной логики

Отдельного внимания заслуживает обзор структуры репозитория. Его обычно рекомендуют добавлять в rules-файлы, но исследования 2026 года показали, что перечисление каталогов не помогает агенту быстрее находить нужные файлы: он и так исследует репозиторий инструментами. Обзор — популярная, но бесполезная секция, которая только расходует окно (см. раздел про исследования).

Размер и структура

Цель — до ~200 строк на файл. Более длинные файлы потребляют больше контекста и хуже соблюдаются: правила «растворяются» среди прочего текста.
Path-scoped rules. Инструкции можно ограничить по путям: правила для *.ts грузятся, только когда агент работает с TypeScript-файлами. Это способ держать базу компактной и релевантной.
Импорты не экономят контекст. @path/to/import в CLAUDE.md раскрывается и грузится при старте наравне с основным файлом — импорты помогают организации, но не уменьшают окно.

Признаки раздутого rules-файла

Длиннее ~200 строк, агент перестаёт учитывать его целиком.
Есть инструкции для отдельных задач («при рефакторинге auth-модуля…») — им место в задаче.
Дублируются правила, уже описанные в конфигах (Prettier, ESLint).
Содержится обзор структуры репозитория.
Файл меняется чаще, чем раз в пару недель, — значит, туда протекает одноразовое.

Правило OpenAI из их harness-эксперимента: AGENTS.md — это карта, а не энциклопедия. Короткий файл (~100 строк) с указателями на структурированные документы работает лучше, чем один монолит: когда всё помечено важным, важного не остаётся.

Skills и команды

Skill — это переиспользуемый набор инструкций, ресурсов и скриптов, который агент подгружает по релевантности. Slash-команды (/deploy) фактически слились со skills: и то и другое — способ «упаковать» повторяющийся workflow.

Progressive disclosure

Главная идея skills — постепенное раскрытие, экономящее контекст:

Метаданные. В начале грузятся только name и description всех скиллов — порядка 100 токенов на скилл. Именно по описанию агент решает, применять ли скилл.
Тело SKILL.md. Загружается, только когда скилл активирован (вручную или моделью). Рекомендованный размер — до ~500 строк.
Ресурсы. Дополнительные файлы (шаблоны, справки, скрипты) читаются по мере надобности. Скрипты вообще можно исполнять, не загружая их содержимое в контекст — в окно попадает только вывод.

---
name: db-migration
description: Правила создания миграций БД: нейминг, откат, проверка на проде
---

# Миграции БД

1. Имя миграции — `YYYYMMDD_короткое_описание`.
2. Каждая миграция обязана иметь рабочий `down`.
3. Перед коммитом: `pnpm db:lint && pnpm db:test`.
4. Не менять уже смёрженные миграции — только новые.

Такое устройство объясняет, почему skills заменили ручные промпты: один раз описанный workflow доступен всем и не расходует окно, пока не понадобится. Скиллы следуют открытому стандарту Agent Skills, поэтому переносимы между инструментами.

Когда заводить скилл: задача повторяется, у неё есть чёткая процедура и её хочется стандартизировать (миграции, релизы, код-ревью, генерация по шаблону). Когда не надо: одноразовая задача — её место в промпте, а не в скилле.

Hooks: детерминированные проверки

Hooks — команды, которые среда выполняет автоматически на событиях цикла агента: PreToolUse (до вызова инструмента), PostToolUse (после успешного вызова), Stop (завершение). Их ключевое свойство — детерминированность: хук срабатывает всегда, независимо от того, «решила» ли модель что-то опасное.

Типовые применения:

PreToolUse на Bash — заблокировать rm -rf, git push --force, обращения к .env и package-lock.json.
PostToolUse на Edit|Write — авто-форматирование (Prettier), прогон линтера.
Stop — отчёт по сессии, уведомление о завершении.

Guides и sensors: рамка harness engineering

Полезно смотреть на hooks шире — как на harness агента (Birgitta Böckeler, Martin Fowler). Harness делит контроли на два типа:

Guides (feedforward) — упреждающее управление до действия: правила, структурные ограничения, read-only инструменты, scoped-инструкции. Повышают вероятность, что агент сделает правильно с первого раза.
Sensors (feedback) — проверка после действия: тесты, линтеры, типы, структурные тесты, AI-ревью. Позволяют агенту самому исправиться до того, как результат увидит человек.

И те и другие бывают вычислительными (детерминированные, дешёвые, надёжные — тесты, линтеры) и инференциальными (семантические, дорогие, недетерминированные — «LLM as judge»). Вычислительные sensors можно гонять на каждое изменение; инференциальные — точечно.

Сильная практика — писать сообщения линтера с инструкцией по исправлению: тогда ошибка не просто сигнализирует о проблеме, а подсказывает агенту, что делать («положительная prompt injection»). OpenAI в своём harness-эксперименте сделали именно так: кастомные линтеры с remediation-инструкциями в тексте ошибки. Правило, которое агент регулярно нарушает, стоит «повышать» из прозы rules-файла в механический sensor — линтер или структурный тест.

Подробнее про хуки конкретных инструментов (формат конфигурации, коды выхода) — в статье Агентские инструменты разработки.

Subagents: изоляция контекста

Subagent — отдельный экземпляр агента для подзадачи. Он запускается с чистым контекстом, собственным system prompt и ограниченным набором инструментов, а в родителя возвращает только финальный результат.

Зачем это нужно с точки зрения контекста:

Не засоряет основное окно. Разведка по кодовой базе («найди, где обрабатывается авторизация») может прочитать десятки файлов. Если делать это в основном диалоге, они навсегда останутся в контексте и будут стоить токенов на каждом следующем шаге. Subagent вернёт только вывод.
Ограничивает права. Subagent только для чтения физически не сможет изменить файлы — это guide уровня harness.
Параллелит независимые проверки. Линтер, security-scan и тесты могут идти одновременно; итог — за время самой долгой задачи, а не суммы.
Экономит деньги. Рутинную подзадачу можно направить на более дешёвую модель.

Subagents — это форма «context offloading»: вместо того чтобы держать всё в одном окне, работа изолируется, а наружу отдаётся сжатый результат. Детали (модели параллелизма, конфигурация subagent’ов) — в статье Агентские инструменты разработки.

Управление окном: compaction, память и Tool Search

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

Механизм	Что делает	Область действия	Когда применять
Compaction	Суммирует историю и продолжает с резюме	Весь transcript	Диалог и рассуждения растут, детали можно сжать
Очистка результатов инструментов	Заменяет старые `tool_result` заглушкой, сохраняя запись о вызове	Подмножество сообщений	Окно забито большими, но перезапрашиваемыми результатами
Память (memory)	Выносит факты за пределы окна	Между сессиями	Знание должно пережить новую сессию

Разница принципиальна: compaction жертвует деталями ради связности (резюме сохраняет решения и факты, но теряет дословность); очистка результатов — точечная и почти без потерь, потому что файл всегда можно перечитать; память решает другую задачу — непрерывность между сессиями (например, MEMORY.md, который агент ведёт сам). Anthropic реализовала все три как first-party API: серверный compaction, context editing (включая очистку результатов) и memory tool.

Tool Search: не грузить все инструменты

Отдельная проблема — определения инструментов. Большой набор инструментов (например, несколько MCP-серверов) может занять десятки тысяч токенов ещё до начала работы: 50 инструментов — это ~10–20K токенов, а мультисерверная конфигурация легко доходит до ~55K. Плюс точность выбора инструмента падает, когда их одновременно доступно больше 30–50.

Tool Search решает это, откладывая загрузку определений: агент получает краткое описание каталога, ищет нужный инструмент по запросу и подгружает 3–5 самых релевантных. По данным Anthropic, это сокращает объём определений более чем на 85%, а точность выбора остаётся высокой даже при тысячах инструментов. Для небольшого набора (<10 инструментов) выгоднее загрузить всё сразу.

Что держать в начале и конце

Из «lost in the middle» следует правило для агента: критические инструкции — в начало (rules/system prompt), конкретную задачу — в конец (текущее сообщение). Длинную середину (история, документы) модель прочитает, но может не акцентировать.

Agentic search против RAG

Поиск по кодовой базе агенты почти всегда делают не векторным retrieval, а обычным glob + grep: точное совпадение символов, нулевая настройка, всегда свежий результат, нет устаревшего индекса. Anthropic описывает это как just-in-time retrieval: агент держит лёгкие ссылки (пути, запросы) и подтягивает данные по мере необходимости, вместо того чтобы заранее загружать всё.

Сравнение подходов:

Критерий	Agentic search (grep/glob)	Векторный RAG
Точность	Точное совпадение символов	Приблизительная близость по смыслу
Актуальность	Всегда свежие файлы	Индекс устаревает
Настройка	Нет	Нужен pipeline, эмбеддинги, хранилище
Стоимость	Дешёвый локальный поиск	Инфраструктура + запросы
Где лучше	Навигация по коду	Большие внешние базы знаний, документы

Claude Code изначально пробовал RAG с локальной векторной базой и отказался от него в пользу agentic search. Это не значит, что RAG бесполезен: для базы знаний, не помещающейся в окно и релевантной по смыслу (документация, тикеты, внешние справочники), retrieval уместен. Но для «найти, где в репозитории определён useAuth» точный поиск выигрывает.

Не переусердствовать: что говорят исследования

Самая важная и самая отрезвляющая часть темы. Контекстные файлы — стандартная практика, но их эффект не гарантирован, и это подтверждают независимые исследования 2026 года.

Данные исследований

MSR 2026 (arXiv:2510.21413). Анализ 466 open-source проектов: единой структуры AGENTS.md нет, стиль подачи сильно варьируется (описательный, предписывающий, запрещающий, объясняющий, условный). Половина файлов не менялась после создания. Вывод — конвенции для этого артефакта ещё в процессе становления.
Evaluating AGENTS.md (arXiv:2602.11988). Контекстные файлы не улучшают успешность решения задач статистически значимо, но увеличивают стоимость более чем на 20% и число шагов. При этом инструкции из файлов хорошо соблюдаются — растёт exploration и тестирование. Обзоры репозитория (популярная рекомендация) оказались бесполезны: агенты не находили нужные файлы быстрее. Файлы, написанные людьми, чуть лучше сгенерированных моделью.
Двухагентная абляция (arXiv:2607.27250). Контролируемый эксперимент на Claude Code и Codex: стратегия подачи контекста (нет / полный AGENTS.md / selective-вики) не меняет корректность — эффект в пределах ~10 п.п. (Claude) и ~15 п.п. (Codex). Механизм: агенты проваливаются на навыке реализации (проектирование фичи, выбор паттерна, точная стыковка), а не на недостатке знаний о репозитории. AGENTS.md ни разу не превратил near-miss в pass.

Практические выводы

Контекстные файлы — для неочевидного. Они полезны для специфичных соглашений, нестандартного тулинга и требований, которых нет в README. Всё, что агент может узнать из кода, дублировать не нужно.
Строить постепенно. Böckeler рекомендует наращивать rules по мере необходимости, а не заливать максимум сразу: то, что требовалось полгода назад, современной модели может быть уже не нужно.
Измерять, а не верить. Любое правило, скилл или файл стоит оценивать по влиянию на результат — в духе sensors из harness engineering.
Помнить о вероятности. Как и любая работа с LLM, context engineering повышает вероятность хорошего результата, но ничего не гарантирует: модель недетерминирована, а «обеспечить» корректность промптом нельзя.

Ключевые тезисы для интервью

Context engineering управляет всей информационной средой агента (что, когда и откуда попадает в контекст), а prompt engineering — только одной формулировкой; цель — минимальный набор высокосигнальных токенов.
Постоянное (стек, команды, запреты) идёт в rules/skills, одноразовое — в задачу; смешение раздувает конфигурацию и ухудшает соблюдение.
Rules-файл (AGENTS.md/CLAUDE.md) грузится каждую сессию, поэтому должен быть коротким (~200 строк): обзоры репозитория бесполезны, а path-scoped rules помогают держать базу релевантной.
Skills работают через progressive disclosure: в старте — только метаданные (~100 токенов), тело — по активации, скрипты исполняются без загрузки в контекст.
Hooks — детерминированные проверки на событиях цикла; в рамке harness engineering guides (feedforward) управляют агентом до действия, а sensors (feedback) ловят проблемы после и дают ему самому исправиться.
Subagents изолируют контекст подзадач, ограничивают инструменты и позволяют параллелизм — это форма context offloading.
Compaction суммирует всю историю, очистка инструментов точечно убирает tool_result, память выносит факты за пределы окна и переживает сессии; Tool Search откладывает загрузку определений инструментов, экономя десятки тысяч токенов.
Agentic search (grep/glob, just-in-time) для навигации по коду надёжнее RAG: точнее, свежее, без инфраструктуры; RAG — для больших внешних баз знаний.
Контекстные файлы не панацея: абляции 2026 показали отсутствие значимого прироста корректности и рост стоимости >20%; агенты чаще проваливаются на реализации, а не на незнании репозитория.

Заключение

Context engineering — это дисциплина проектирования информационной среды агента, а не подбор красивых промптов. Несколько выводов:

Контекст — бюджет, а не склад. Больше информации не значит лучше и почти всегда значит дороже. Цель — минимум высокосигнальных токенов.
Разделяйте постоянное и одноразовое. Rules и skills — для того, что действует всегда; задача — для того, что нужно сейчас.
Опирайтесь на детерминизм там, где он возможен. Hooks, линтеры и тесты как sensors надёжнее, чем просьбы в промпте.
Управляйте окном осознанно. Compaction, очистка результатов, память и Tool Search решают разные задачи — выбирайте под наблюдаемое узкое место.
Проверяйте эффект. Исследования показывают, что контекстные файлы помогают неочевидными конвенциями, а не объёмом. Собирайте контекст итеративно и оценивайте результат.

Начните с короткого AGENTS.md и одного-двух скиллов на повторяющиеся процедуры, добавьте хук на опасные команды — и наращивайте harness по мере появления реальных проблем, а не заранее.