Как приручить ИИ-агента в монолите: один файл правил, который спасет ваши нервы на ревью

В большом репозитории ваш ИИ-помощник напоминает стажера с доступом ко всему коду сразу. Он честно пытается помочь, но тянет правила из корня проекта туда, где они ломают логику. В /backend он требует TypeScript там, где исторически живет Python, а в /infrastructure заставляет писать тесты по стандартам UI-библиотеки.

Что происходит: контекстный голод агента в корневом README

Когда вы просите нейросеть поправить одну кнопку в мобильном приложении, она сначала читает главный файл инструкций в корне (обычно это AGENTS.md или просто длинное описание задачи). Там написано обобщенно: «Используем Prettier», «Покрываем тестами всё». Агент берет этот общий инструмент и начинает применять его к специфике мобильной платформы. Ему неоткуда узнать, что внутри папки /mobile у вас жесткое правило — два пробела вместо четырех, полный запрет console.log и обязательное прикрепление скриншота интерфейса к каждому пул-реквесту (запросу на слияние кода). В итоге на выходе вы получаете идеальный с точки зрения общего стандарта, но абсолютно нерабочий для вашей платформы код. Вы тратите время на гневное ревью, агент извиняется, обещает учесть контекст «в следующий раз», но через пять минут повторяет ту же ошибку в соседнем файле.

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

Почему парент-каталоги побеждают корень: механика наследования контекста

Современные среды разработки (например, Cursor, GitHub Copilot Workspace) умеют читать иерархию файлов сверху вниз. Заходя в подпапку /mobile, агент первым делом ищет инструкции именно в ней. Если находит файл .ai-instructions.txt или AGENTS.md — общие настройки из корня уходят на второй план, становятся фоном.

Это работает как строгий пост охраны на въезде в закрытый город. Общие правила страны никто не отменял, но внутренние уставы гарнизона важнее. Для машины это выглядит как смена системного промпта (основной команды): модель получает новый приоритет без необходимости переобучаться. Она физически видит файл рядом с тем куском кода, который вы открыли, и ее математическая уверенность в правильности этих локальных указаний кратно возрастает. Главное техническое условие здесь одно: имя файла должно быть идентичным во всех подпапках, чтобы среда разработки могла надежно подхватывать его автоматически.

Как проверить свою боль за 10 минут: аудит последнего коммита

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

Зайдите в историю этого коммита и посмотрите вкладку «Conversations» или «AI Context», если ваша IDE (интегрированная среда разработки) это позволяет. Увидите ли вы там упоминание ваших внутренних договоренностей про те самые два пробела или запрет логов? Скорее всего, нет. Значит, агент опирался только на общую память прошлых диалогов и корневые тексты, которые давно покрылись пылью и противоречат текущему состоянию ветки.

Второй маркер проблемы — конфликты в CI/CD (автоматических проверках сборки). Если билд падает со странной ошибкой линтеров (программ проверки стиля), которую агент сам же и внес час назад, пытаясь «улучшить читаемость» чужого для него модуля — диагноз подтвержден. Агент полез наводить порядок там, где действуют другие законы физики.

Делаем манифест: ровно три строки, которые поймет любая модель

Никаких эссе на полстраницы. Длинные полотна текста модель воспринимает как художественную литературу и пропускает детали. Нужен суровый чек-лист. Создайте в целевой подпапке (например, /mobile или /packages/ui) текстовый файл с именем .ai-instructions.txt. Внутри напишите строго три пункта:

Стиль кода: отступы — 2 пробела; запрещены табы; перенос строк — 80 символов. Это снимает вопросы о вкусовщине. Модель любит спорить об эстетике, жесткие цифры закрывают дискуссию.

Именование: компоненты — MobileHeader.tsx; хуки — useMobileAuth(); константы пишем в SCREAMING_SNAKE_CASE (заглавными буквами через подчеркивание). Четкий паттерн имен помогает агенту правильно генерировать импорты и связи между файлами.

Чек-лист PR: обязательный ручной скриншот на реальном устройстве; никаких console.log; ссылка на тикет в описании. Это переводит абстрактную задачу в понятный машине алгоритм приемки результата.

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

Проверка в бою: первый сегодняшний пул-реквест

Откройте любой старый баг в трекере задач, который касается этой папки. Скопируйте ссылку на него и киньте агенту вместе с задачей: «Исправь падение кнопки Логин в /mobile. Правила лежат в .ai-instructions.txt».

На ревью проверьте не столько сам код, сколько метаданные. Соблюдено ли ограничение в два пробела? Нет ли закомментированного вывода в консоль? Есть ли в описании ссылки на тикет и приложенный артефакт (скриншот)? Если все три пункта на месте — механику можно масштабировать на остальные части монолита. Если агент снова забыл про скриншот — добавьте в начало файла жирную строку: «НИКОГДА НЕ СЛИВАЙ БЕЗ СКРИНШОТА». Модели отлично считывают капс и стоп-слова как высший приоритет запрета.

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

Завтра утром: конкретный план внедрения

1. Выберите самую проблемную зону, куда агент заходит чаще всего (обычно это либо свежий модуль, либо самая старая легаси-подпапка, где накоплено больше всего технического долга). 2. Положите туда .ai-instructions.txt с тремя строками выше. Не пытайтесь описать всю архитектуру приложения, описывайте только границы дозволенного в этой конкретной коробке. 3. Зайдите в настройки вашего редактора или чат-бота и принудительно обновите индекс файлов, чтобы система увидела новую инструкцию до начала генерации. 4. Поставьте агенту микро-задачу на рефакторинг одной функции внутри этой папки и внимательно посмотрите на дифф (разницу в коде) первого же ответа. 5. Проверьте результат на ближайшем стендапе: сравните количество комментариев от старших разработчиков на этом участке кода за прошлую неделю и за завтрашний день. Разница станет вашим главным аргументом для остальной команды, когда вы понесете эту практику в /backend и /infra.

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