Модель приходит в проект без памяти. Каждая новая сессия — это новый человек
в команде: толковый, быстрый, но не знающий ни ваших соглашений, ни того,
почему тут так странно сделано. Объяснять всё это заново в каждом чате — самая
дорогая привычка в вайбкодинге.
Решение простое: описать проект один раз, файлом в репозитории, который
инструмент подхватывает сам.
У большинства инструментов есть такое соглашение: CLAUDE.md, AGENTS.md,
.cursorrules, .github/copilot-instructions.md. Смысл один — текст, который
подставляется в контекст автоматически, без напоминаний.
Что туда правда стоит писать:
Что это за проект. Три предложения. Чем занимается, для кого, что важно.
Стек и версии. Не «React», а «React 19, Vite, TypeScript strict». Модель
иначе напишет код позапрошлого мажора — того, которого в обучении было больше.
Команды. Как собрать, как прогнать тесты, как поднять локально. Это самое
окупаемое: агент сможет проверять себя сам, не спрашивая.
Соглашения, которые не выводятся из кода. Почему состояние живёт вот
здесь, почему запросы идут через этот слой, что считается публичным API.
Чего не делать. Не добавлять зависимостей без спроса, не трогать
сгенерированные файлы, не менять миграции задним числом, не переформатировать
чужие куски. Список запретов ценнее списка пожеланий.
Отказы и их причины. «Не используем ORM — нужен контроль над запросами».
Без этого модель раз в неделю будет предлагать ORM, и каждый раз убедительно.
Структура каталогов, список файлов, описание функций, история изменений.
Всё это уже есть в репозитории и умеет устаревать.
Устаревший файл контекста хуже отсутствующего: он врёт уверенно, и модель ему
верит больше, чем коду. Правило простое — если утверждение можно проверить,
прочитав код, оно там лишнее. Файл нужен для того, чего в коде нет: причин,
намерений, границ.
Второе правило — размер. Этот текст занимает контекст в каждой сессии,
поэтому за него надо платить пользой. Полторы-две страницы плотного текста
работают; десять страниц читают по диагонали и вы, и модель.
Не пишите с нуля и по памяти — получится список благих намерений.
Поддерживать так же: меняется соглашение — правится файл, в том же коммите.
Файл, который не менялся полгода, почти наверняка уже врёт.
Тесты. Лучшая документация поведения: их нельзя «забыть обновить»,
они падают. Проект с быстрыми тестами понятен модели без единого слова
объяснений.
Типы. Строгий TypeScript, Go, схемы валидации — это ограничения, которые
проверяются машиной, а не надеждой. Модель не сможет придумать несуществующее
поле: не соберётся.
Спецификации. Если API описан OpenAPI и код из него генерируется,
разойтись они не могут. Это дороже комментария, но перестаёт быть вашей
заботой навсегда.
Внятные имена и мелкие модули. Файл на сорок строк с говорящим названием
модель поймёт по имени; файл на две тысячи придётся читать целиком, отъедая
окно.
История git. Осмысленные сообщения коммитов — второй по полезности
источник «почему так». Агент умеет их читать.
Ни один файл инструкций не спасёт проект, где сборка идёт двадцать минут,
тестов нет, а половина знаний живёт в голове одного человека. Контекст —
это в первую очередь свойство проекта, и только потом текстовый файл.
Даже с идеально описанным проектом окно конечно, и его надо беречь: