Бюджеты контекста для ассистентов по программированию в больших репозиториях

Почему большие репозитории сбивают с толку ассистентов по программированию

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

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

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

Распространённая ошибка — считать, что больше контекста значит лучше контекст. Команды кидают в подсказку целые папки, потому что хотят, чтобы ассистент «понял проект». На практике это обычно ухудшает ответ. Модель начинает смешивать несвязанные модули, подтягивать неправильные типы или решать не ту проблему.

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

Возьмём изменение в биллинге. Ассистенту обычно не нужен весь моно-репозиторий. Ему нужен роут-хендлер, типы запроса и ответа, сервис, отвечающий за логику биллинга, и тест, который показывает текущее поведение. Этот меньший пакет даёт модели гораздо больше шансов дать безопасный ответ.

Когда команды используют ассистентов по программированию в большом репозитории, фокус побеждает объём. Модель пишет лучший код, когда вы даёте ей файлы, которые определяют контракт, и файлы, которые вы собираетесь менять. Всё остальное увеличивает вероятность уверенного, но ошибочного ответа.

Что должно быть в подсказке

Большинство команд отправляет слишком много. Модель тратит внимание на файлы, которые не контролируют изменение, и ответ становится расплывчатым.

Начните с файлов, которые определяют контракт. В зависимости от задачи это может быть спецификация API, общие типы, интерфейс, схема, правило валидации, тест, фиксирующий поведение, или props компонента, от которых уже зависит другой код. Если вы меняете платежный эндпоинт, файл OpenAPI, типы запроса и ответа, правила валидации и падающий тест важнее, чем остальная часть папки биллинга.

Затем добавьте только файлы, на которые задача влияет прямо сейчас. В смешанной стеке, например Next.js с Go или Python-сервисами за ним, это может быть один обработчик, одна форма в UI, один файл общих типов и одна миграция. Часто этого достаточно для первого прохода.

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

Худой подсказка часто состоит из четырёх частей: файл контракта, файл реализации, который вы будете править, тест, доказывающий изменение, и один ближайший пример, который следует тому же паттерну.

Оставляйте вне папки, которые не формируют решение. Старые эксперименты, сгенерированные клиенты, артефакты сборки, скопированный vendor-код и широкие утилитные директории обычно тратят токены впустую. Огромные логи и длинные CI-файлы делают то же самое, если задача не про деплой или дебаг.

Хороший контекст кажется слегка узким. Это не недостаток. Ассистенту лучше, когда он видит правила, актуальные файлы и один ясный прецедент.

Как сформировать полезный пакет контекста

Начните с рабочего элемента, а не с кода. Тикет, отчёт об ошибке или запрос на изменение объясняет ассистенту, что изменилось и почему. Без этого он пытается угадать цель по тому, какие файлы вы отправили.

Далее подтяните файлы, которые определяют контракт. Обычно это типы запроса/ответа, файлы схем, определения интерфейсов, правила валидации и краткая спецификация, фиксирующая поведение. Они говорят модели, что должно оставаться верным.

После этого добавьте код, который сейчас несёт изменение. Выберите контроллер, сервис, компонент, джоб или файл с запросом, который вы собираетесь править. Если задача касается одного эндпоинта и одного валидатора — отправьте их. Вам не нужна половина папки только потому, что она рядом.

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

Добавьте одну короткую инструкцию перед файлами. Держите её простой и конкретной. Предложение вроде «Добавить фильтр по статусу в эндпоинт orders. Сохранить форму ответа. Обновить тесты для некорректных значений» даёт ассистенту чёткую цель без траты места.

Небольшая команда может собрать такой пакет за несколько минут. Если разработчику нужно добавить поле в ответ API, обычно достаточно тикета, типа ответа, хендлера, сериализатора и теста, который проверяет JSON-форму. Этого достаточно для сфокусированного ответа.

Обновляйте пакет по мере продвижения задачи. Если простая правка UI превращается в изменение базы данных, замените пакет миграцией, схемой и кодом репозитория. Если задача смещается из фичевой работы в падение пайплайна, удалите продактовые файлы и добавьте CI-job, скрипт и вывод ошибки. Устаревший контекст незаметно сбивает модель с курса.

Какие файлы обычно важны в первую очередь

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

API-схемы и общие типы обычно должны быть в наборе первыми. Они определяют имена полей, перечисления, правила null и форматы ответов. Если нужно добавить свойство, эти файлы показывают, где оно начинается и куда должно попадать.

Граничные файлы тоже важны: интерфейсы сервисов, методы репозиториев, props компонентов и контракты событий рассказывают модели, чего ждёт остальной код. Без них ассистент может выдумать новый паттерн вызова, который сломает существующий код.

Ближайшие тесты часто объясняют поведение лучше, чем комментарии. Они показывают ожидаемый вывод, обработку ошибок и неудобные крайние случаи, которые при чтении по happy-path можно пропустить.

Файлы конфигурации имеют значение только если они могут изменить поведение во время выполнения для данной задачи. Флаги фич, роут-конфиг, настройка DI, сборка и правила линтера могут превратить корректно выглядящий код в сломанный. Если они не влияют на изменение — не включайте их.

Недавние диффы тоже помогают. Они показывают актуальное именование, свежие правила и локальные соглашения. Если команда вчера переименовала accountId в customerId, ассистент должен следовать этому изменению, а не возвращать старое имя.

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

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

Реалистичный пример из продуктовой команды

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

Большинство плохих ответов начинается с чрезмерно объёмной подсказки. Ассистент видит половину репозитория и начинает догадываться, как скидки связаны с инвойсами, ролями пользователей или бэкофис-инструментами.

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

Этого достаточно. Ассистент видит форму входных данных, ожидаемый выход и место, где живёт правило.

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

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

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

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

Ошибки, которые тратят контекст зря

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

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

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

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

Устаревший контекст легко не заметить, когда задача сдвигается. Вы начинаете с правки сериализатора, затем выясняете, что реальная проблема в валидации запросов. Если вы держите старые файлы и добавляете новые, подсказка превращается в скрапбук. Остановитесь, обрежьте и перестройте вокруг новой задачи.

Одна длинная сессия чата может создать ту же проблему. Люди держат сессию ассистента открытой часами, а потом удивляются, почему ответы начинают дрейфовать. Как только цель меняется или модель начинает смешивать старые предположения с новой работой — начните сначала.

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

Как сделать это рутиной

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

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

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

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

Простая рутина достаточна:

• выбрать тип задачи
• загрузить соответствующий шаблон подсказки
• добавить файлы контракта для этой области
• добавить только файлы, затронутые текущим изменением
• перезапустить чат, когда задача или область меняется

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

Это также паттерн, о котором говорит Oleg Sotnikov в своей работе CTO с фокусом на ИИ на oleg.is: дайте модели контракт, локальную логику и доказательство. Если задача узкая, контекст тоже должен быть узким.

Что делать дальше

Начните с одного узкого рабочего процесса и протестируйте идею там. Багфиксы — хорошее место для старта. Малые рефакторы тоже подходят. У обоих ясные задачи, короткие циклы обратной связи и меньше движущихся частей, чем у больших фич.

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

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

Это не требует длинного процесса. Одной страницы в командном пространстве достаточно. Цель — сделать выбор контекста репозитория простым для повторения, а не идеальным.

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

Если нужна помощь в настройке такого рабочего процесса, Oleg Sotnikov предлагает услуги Fractional CTO и консультации для стартапов, ориентированные на практическую ИИ-разработку и автоматизацию. Это часто полезно, когда команде нужна внешняя помощь в определении контрактных файлов, правил подсказок и лёгкого процесса, которым люди действительно будут пользоваться.

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