Правила проекта для AI-агента: как получить код в стиле команды

Типичная жалоба на AI-агентов звучит так: код формально правильный, но чужой. Другие имена, другая структура, свой способ логировать ошибки, самописный запрос вместо штатного API платформы. Через несколько таких правок проект превращается в лоскутное одеяло.

Почему так происходит

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

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

Что стоит записать

Работает не длинный документ, а короткий и конкретный. Полезное наполнение:

• Что это за проект. Два-три предложения: назначение, стек, версии. Модель иначе угадывает по коду и иногда угадывает неверно.
• Структура каталогов. Где приложения, где шаблоны, где статика, куда класть новый код. Это устраняет самый частый источник расхождений.
• Команды. Как запустить сервер, тесты, линтер, миграции. Конкретные строки, а не «стандартным способом».
• Соглашения по коду. Язык комментариев, стиль именования, подход к обработке ошибок и логированию, что запрещено использовать.
• Особенности платформы. Например: не обращаться к базе напрямую в обход API, не править ядро, не добавлять зависимости без обсуждения.
• Границы автономии. Что агент может делать сам, а что требует подтверждения: миграции, удаление файлов, изменение конфигурации, работа с продакшен-данными.

Чего класть не стоит

Файл правил портится теми же способами, что и любая документация:

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

Конкретика вместо пожеланий

Разница между работающим и неработающим правилом — в проверяемости. «Пиши понятные комментарии» не даёт модели никакого критерия. «Комментарии на русском, объясняют причину решения, а не пересказывают код» — даёт.

То же с запретами. «Не используй устаревшие подходы» бесполезно, потому что список устаревшего у модели свой. «Не использовать прямые SQL-запросы, только ORM; исключение — отчёты, они лежат в отдельном модуле» работает.

Как проверить, что правила действительно применяются

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

На что смотреть:

• Файл создан там, где принято, или в корне «как удобнее»?
• Использовано штатное API платформы или написан обход?
• Ошибки обрабатываются принятым в проекте способом?
• Комментарии на нужном языке и по делу?

Каждое расхождение — это не претензия к модели, а пропущенное правило. Так документ и наполняется: не заранее, а по факту первого несовпадения.

Правила стареют быстрее кода

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

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

Что это даёт

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