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

Наивная модель проста: контекст - это склад, и чем он полнее, тем лучше. Раз агент читает быстро, пусть читает всё, а нужное выберет сам. Такое рассуждение переносит на модель человеческую привычку "перебдеть": лучше дать лишнее, чем недодать. С человеком, умеющим игнорировать нерелевантное, оно даже работает - но агент устроен иначе.

Ломается это на том, что лишний контекст не нейтрален. Каждый приложенный файл - это сигнал "смотри сюда", и десять таких сигналов размывают тот единственный, что вёл к цели. Retrieval и внимание модели работают тем точнее, чем чётче форма вопроса; поток слабо связанных артефактов, наоборот, повышает шанс, что агент зацепится за похожее, но не то. У модели ограниченный бюджет внимания на один turn, и он делится между всем, что вы положили: чем больше кусков, тем меньше веса достаётся каждому, включая тот единственный, ради которого всё и затевалось. Склад не помогает найти нужное - он прячет его среди похожего.

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

Отдельный приём внутри карты - разделять факты и гипотезы, и делать это явно. "Тест падает на строке X с таким сообщением" - факт, его можно проверить. "Вероятно, это race condition" - гипотеза, и подавать её нужно как гипотезу, а не как установленную причину. Смешение опасно тем, что агент принимает вашу догадку за данность и начинает чинить предполагаемую причину вместо наблюдаемого симптома, уводя работу в сторону с самого начала.

Почему точечный якорь надёжнее массивного дампа, видно из устройства поиска по коду. @-mention конкретного файла или символа - это точный якорь: он говорит "начни отсюда", не утверждая "больше нигде не смотри". Агент от него разворачивает поиск сам и находит то, что вы могли не знать. Разница видна на практике: по одному якорю "начни с этого хендлера" агент сам поднимет его вызовы и покрывающие тесты; по папке из тридцати файлов он с большей вероятностью опишет то, что бросается в глаза, а не то, что относится к делу. Массив прикреплённого, наоборот, и якорь размывает, и самостоятельный retrieval подавляет - модель считает, что всё нужное уже дано, и перестаёт искать.