Опубликовано в Профессии

Как дать AI-агенту контекст репозитория

Фигурка передаёт роботу маленький открытый чемодан с инструментами рядом с большим ящиком инструментов.

Время чтения: 5 мин.

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

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

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

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

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

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

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

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

Покажи вход в сценарий и близкий образец

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

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

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

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

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

Отдели постоянные правила от текущей задачи

Постоянные сведения о сборке, проверках и устройстве проекта можно хранить рядом с репозиторием. Формат AGENTS.md предлагает отдельное место для инструкций агентам. В него стоит помещать то, что действительно помогает работать с этим проектом повторно.

Не превращай такой файл в архив всей переписки. Команда запуска, важное ограничение данных и границы модулей полезны; список старых пожеланий без области действия создаёт противоречия. Для каждой инструкции должно быть понятно, когда она применяется.

Конкретные форматы и порядок чтения зависят от инструмента. Например, GitHub описывает repository-wide и path-specific custom instructions. Перед настройкой проверь актуальную поддержку, а не предполагай, что любой агент одинаково прочитает все похожие файлы.

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

Дай команды с понятным назначением

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

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

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

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

Проверяй выбранный контекст по первому ответу

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

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

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

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

Сохрани результат, который можно перепроверить

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

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

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

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

Проверь задачу и полученный diff

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

Выбрать ментора