Контекст-инжиниринг: агенту нужен не идеальный промпт, а правильно собранное окно

Игорь попросил агента починить баг: после оплаты клиентам не приходит чек. Агент ответил за минуту, уверенно и красиво. Расписал причину, предложил правку на десять строк. Игорь применил её, и всё стало работать хуже: теперь не уходили вообще никакие письма.

Что пошло не так? Агент не был глупым. Ему просто не показали главное: лог ошибки, из которого было видно, что письмо отклоняет почтовый сервер. Зато в его «поле зрения» оказалась документация почтового провайдера на шестьдесят страниц и переписка в чате за неделю. Он собрал ответ из того, что видел, и достроил недостающее.

Эта история про то, что у современной работы с ИИ-агентами появилась новая дисциплина. Её называют контекст-инжинирингом: умением собрать для модели ровно то, что нужно для задачи. Давайте разберём её на демо, а не на слайдах.

Что на самом деле лежит в окне

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

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

Токены: во что считается всё это

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

Зачем это знать? Токены считают в трёх местах сразу. Они ограничивают, сколько поместится в окно. Они определяют цену запроса (об этом отдельный разбор про стоимость ИИ-функций). И, что менее очевидно, они определяют качество: чем больше всего накидано, тем сложнее модели удержать внимание на нужном.

«Больше» не значит «лучше»

Производители гордо сообщают, что их модели умеют читать сотни тысяч токенов. Но способность прочитать не равна способности использовать. В исследовании 2023 года «Lost in the Middle» показали интересную закономерность: когда нужный факт лежит в начале или в конце длинного контекста, модель находит его заметно лучше, чем когда он спрятан посередине. Эта «U-образная» картина с тех пор смягчилась у новых моделей, но не исчезла полностью.

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

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

Где вы это встречаете. Агент в долгой сессии начинает «забывать» первое задание, повторять уже сделанное или противоречить себе. Дело не в характере. Окно забито, и важное тонет. Обычное лечение: начать свежую сессию, перенеся в неё короткое резюме.

Как агент добывает контекст

Чтобы не загружать всё сразу, агенты умеют искать. Вместо того чтобы получить репозиторий целиком, они запускают поиск, открывают нужные файлы и подтягивают только найденное. Такой подход называют RAG (поиск с дополнением генерации), а протоколы вроде MCP стандартизируют, как агент подключается к источникам.

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

Файл правил: онбординг для агента

Одна из самых недооценённых вещей в работе с агентами выглядит скучно. Это текстовый файл в корне репозитория с правилами проекта. Его называют AGENTS.md (формат поддерживает много инструментов) или CLAUDE.md (так он называется в Claude Code). Смысл у них один: агент читает файл перед работой, как новичок читает онбординг.

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

Сравните, как ведёт себя один и тот же агент без файла правил и с ним:

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

Три слоя контекста

Удобно думать о контексте как о трёх слоях с разной скоростью жизни.

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

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

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

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

Шесть типичных ошибок

1. «Положим всю документацию, вдруг пригодится». Не пригодится: она вытеснит нужное и размоет внимание.
2. Описание задачи в двух словах. «Почини чек» против «после оплаты не приходит чек, вот лог, подозреваю отправку писем». Второе занимает пять секунд и экономит час.
3. Устаревший контекст. Описание кода, который давно переписан, модель воспринимает как правду. Старое либо обновляют, либо убирают.
4. Правила, которые противоречат друг другу. В одном файле «пиши тесты всегда», в другом «не трогай каталог tests». Агент выберет что-то одно, и не обязательно то.
5. Слишком много инструментов. Двадцать подключённых сервисов занимают окно и путают выбор: агент хуже решает, какой вызвать.
6. Никакой проверки того, что видел агент. Если ответ странный, первым делом посмотрите, какой контекст ему подали. Чаще всего причина именно там, а не в «слабой модели».

Как понять, что контекст собран плохо

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

Хорошая привычка на ревью: просить агента не только результат, но и перечень того, на что он опирался (какие файлы читал, какие команды запускал). Это как смотреть на источники в статье. Если опора слабая, то и ответ стоит перепроверить.

Практикум: соберите окно

Вернёмся к Игорю. Задача: найти причину, почему чек не уходит. У вас окно на 8 000 токенов и десять карточек, которые вместе заметно превышают его. Что вы отправите агенту? Не пытайтесь запихнуть всё: смысл в отборе.

Что вы, скорее всего, заметили. Нужное (лог, функция, схема, тест) вместе умещается в несколько тысяч токенов, и окно остаётся наполовину пустым. Самые «солидные» карточки (документация, чат) оказались самыми бесполезными. А устаревшие материалы (старый PR) хуже отсутствующих: модель принимает описание несуществующего кода за правду.

Приёмы, которыми пользуются на практике

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

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

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

1. Заведите в репозитории короткий файл правил для агента и допишите туда три вещи: как запускать тесты, какой стиль кода и что трогать нельзя.
2. Проверьте, сколько инструментов подключено к агенту. Отключите те, которыми не пользовались за месяц.
3. Для каждой типичной задачи решите, какой минимальный набор контекста ей нужен (код, тест, схема, лог), и дайте его сразу.
4. Начинайте свежую сессию, когда замечаете, что агент повторяется или забывает начало.
5. Проверяйте не только ответ, но и то, что агент видел. Если причина выдумана, посмотрите, чего ему не хватило.

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

Источники и что почитать

• Lost in the Middle: How Language Models Use Long Contexts — исследование 2023 года про «потерянную середину».
• AGENTS.md — описание формата файла правил для агентов.
• Model Context Protocol — протокол подключения агентов к источникам и инструментам.
• Anthropic: Building effective agents — принципы построения агентов.

---

Пишу из практики студии MKDGRUPP: ведём разработку с агентами, правилами проекта в репозитории и ревью сеньора на каждый PR. Подробнее: mkdgrupp.ru/uslugi/ai.