При создании очередного репозитория к привычному набору boilerplate добавился еще один слой. Почему?

При работе над новым сервисом, создавая очередной репозиторий, я поймал себя на мысли, что к привычному набору boilerplate добавился еще один слой.

Раньше мы стандартизировали вполне понятные вещи:
.gitignore, .dockerignore, Dockerfile, конфигурации линтера, тестов, pre-commit, CI/CD, настройки редактора, зависимости, lock-файлы и так далее. Это была инженерная гигиена. Унификация давала предсказуемость и детерминизм: независимо от того, кто работает с кодом, результат более-менее одинаковый.

Сейчас к этому добавился новый слой это конфигурация работы с LLM-инструментами.

И тут начинается интересное.

Новые файлы, новые правила

У разных инструментов появляются свои конфигурационные файлы:

• .github/copilot-instructions.md для GitHub Copilot
• .cursorrules и .cursor/rules/* для Cursor
• .continue/config.json для Continue
• .cody/* для Sourcegraph Cody
• AGENTS.md, LLM.md, AI_GUIDELINES.md как де-факто командные соглашения

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

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

Проблема множества инструментов

И вот тут возникает сложность.

Если в команде разные инженеры используют разные LLM-инструменты, то:

• файлов становится больше;
• поддерживать их в актуальном состоянии сложнее;
• синхронизировать правила между ними - еще сложнее.

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

Что в них писать?

Отдельный вопрос это содержание.

Насколько детально описывать архитектуру?
Нужно ли прописывать legacy-ограничения?
Стоит ли указывать правила для нового кода?
Какие и насколько детально описывать стандарты кодирования?
Где граница между краткой инструкцией и избыточной детализацией?

Есть рекомендации от вендоров инструментов, есть best practices, но единых строгих требований нет. И свобода творчества приводит к тому, что одна и та же инструкция может быть по-разному интерпретирована разными моделями.

Мы теряем детерминизм. Это не плохо - это просто новая реальность, но со своими минусами. И все равно лучше, чем ничего.

Это документация. А значит - ответственность

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

Кто-то должен поддерживать их в живом состоянии.
Кто-то должен проверять, что в них нет устаревшей или ложной информации.

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

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

А чтобы что-то контролировать - нужно в этом разбираться.

Человек читает или только LLM?

Мне нравится сам подход: наличие такой документации сильно помогает при онбординге. Это краткая инструкция по проекту. Можно не объяснять голосом одно и то же десять раз - все зафиксировано.

Но есть риск: инструкция останется только для LLM. Люди перестанут ее читать, а будут просто «скармливать» модели.

И это, на мой взгляд, опасная зона.

LLM - это инструмент. Очень мощный. Но это не замена инженерного мышления.

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

Интересно, есть ли у вас опыт унификации LLM-конфигураций в команде?
Как вы решаете вопрос актуальности и единых правил?