Контекст: упоминания файлов, картинки, сжатие

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

Что занимает окно

Ещё до вашего первого сообщения в окне лежат системные инструкции, описание инструментов, правила песочницы, содержимое AGENTS.md и сведения об окружении. Если подключены MCP-серверы, добавляются описания их инструментов.

Дальше окно растёт с каждым шагом агента. Чтение большого файла с фикстурами, полный лог тестов, вывод composer show — каждое такое действие добавляет тысячи токенов. Поэтому один и тот же агент в свежей сессии и в сессии, где уже разобрали три бага, ведёт себя по-разному.

Посмотреть, сколько окна осталось, можно командой:

/status

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

Упоминания файлов

Самый дешёвый способ дать агенту контекст — указать файл, а не ждать, пока он найдёт его сам.

• Наберите @ в поле ввода и начните печатать имя — Codex найдёт файл в рабочем каталоге и вставит путь в сообщение.
• Команда /mention прикрепляет файл к чату, чтобы последующие ходы опирались на него напрямую:

/mention plugins/acme/crm/classes/LeadSender.php

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

Картинки

Для вёрстки, визуальных багов и схем картинка понятнее любого описания. В CLI есть два способа:

• вставить изображение прямо в поле ввода;
• передать файл при запуске флагом --image (короткая форма -i):

codex -i bug-mobile-menu.png "На iPhone SE меню перекрывает логотип. Найди причину в стилях шапки и исправь, не меняя десктопную версию"
codex --image layout.png,current.png "Сравни макет с текущей страницей и перечисли расхождения в отступах и шрифтах"

Поддерживаются распространённые форматы, включая PNG и JPEG. В десктопном приложении и IDE картинку можно перетащить в поле ввода с зажатым Shift.

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

Логи и ошибки

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

• из стек-трейса оставьте сообщение и верхние кадры из вашего кода, а не сотню строк фреймворка;
• из лога — строки вокруг ошибки, а не весь файл за сутки;
• если лог большой, лучше положите его в файл и попросите агента найти в нём нужное через grep.

Сжатие истории

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

/compact

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

Сжатие — это всегда потеря части деталей. Поэтому:

• постоянные правила держите в AGENTS.md, а не в переписке (урок «AGENTS.md»);
• важные промежуточные выводы фиксируйте в файле — заметке с планом или описанием задачи, — если задача длинная;
• порог автоматического сжатия можно настроить ключом model_auto_compact_token_limit в config.toml, но для начала оставьте значение по умолчанию.

Если нужно просто вспомнить, о чём шла речь, не сжимая контекст, есть команда /recap — она даёт краткое изложение разговора.

Одна сессия — одна задача

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

На практике:

• новая несвязанная задача — новый чат: /new (в той же CLI-сессии) или /clear (заодно очистит экран);
• побочный вопрос посреди работы — /side: откроется временный чат, отдельный от основного, а основной продолжит работу;
• задача та же, но хочется попробовать другой подход — /fork (урок «Сессии»).

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

Что ещё раздувает контекст

• Размытые задачи. «Разберись, как тут всё устроено» запускает чтение десятков файлов. Сужайте до сценария или модуля.
• Лишние MCP-серверы. Каждый подключённый сервер добавляет описания своих инструментов. Отключайте те, что не нужны в этом проекте, — подробнее в уроке «MCP».
• Длинный AGENTS.md. Он загружается в каждую сессию. Детали для частных случаев выносите в отдельные документы, на которые AGENTS.md ссылается.
• Повторные исправления. После двух-трёх неудачных попыток окно полно неудачных вариантов. Чистая сессия с уточнённой постановкой обычно работает лучше.