CLAUDE.md: как заставить AI писать код в стиле твоего проекта

Знакомая картина: агент выдаёт код, код работает, а в проект его вставлять неловко. Комментарии по-английски, хотя весь остальной репозиторий русский. Рядом с готовой функцией появилась вторая, такая же. В коде торчит токен, который вообще-то живёт в переменных окружения. И где-то используется API фреймворка, который в твоей версии уже переименовали.

Ошибок нет. Стиля тоже.

Лечится это не более длинными промптами. Лечится файлом правил, который лежит в корне репозитория и читается агентом автоматически — в моём случае это CLAUDE.md.

Что такое файл правил проекта

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

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

Мой реальный CLAUDE.md

Не буду сочинять пример, покажу файл из репозитория этого сайта целиком.

@AGENTS.md

# Правила проекта

## Язык
- Все комментарии, коммиты, документация и общение — на русском языке.

## Качество кода
- Писать чистый, читаемый и поддерживаемый код.
- Следовать принципам SOLID и DRY.
- Не оставлять мёртвый код, закомментированные блоки и TODO без описания.

## Безопасность
- Всегда писать безопасный код: проверять входные данные, экранировать вывод.
- Не допускать SQL injection, XSS, CSRF, path traversal и других уязвимостей
  из OWASP Top 10.
- Не хардкодить секреты, токены и пароли — использовать переменные окружения.
- Валидировать данные на границах системы (API входы, пользовательский ввод).

Меньше двадцати строк. Разберу, почему именно эти.

Язык

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

Качество кода

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

Отдельно ценю строчку про мёртвый код. Агенты обожают оставлять закомментированные блоки «на всякий случай» и TODO без пояснений. В продукте, который живёт долго, это накапливается тоннами: у себя в сервисе я в какой-то момент выносил 7000 строк старого кода и 6 неиспользуемых таблиц. Правило в файле дешевле, чем такая уборка.

Безопасность

Это блок, ради которого стоит завести файл, даже если больше в нём ничего не будет.

Агент по умолчанию решает ту задачу, которую ты озвучил. Ты попросил форму обратной связи — он сделает форму. Валидацию входа, экранирование вывода и защиту от инъекций он добавит, если это часть его правил. Явное упоминание OWASP Top 10, секретов в переменных окружения и валидации на границах системы превращает безопасность из «хорошо бы» в требование по умолчанию.

Самое важное правило лежит в соседнем файле

Первая строка CLAUDE.md — @AGENTS.md. Это импорт: содержимое соседнего файла подтягивается в правила. Там всего три предложения, и они важнее всего остального:

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may
all differ from your training data. Read the relevant guide in
`node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.

Перевод по смыслу: это не тот Next.js, который ты знаешь; версия ломающая, API и структура файлов могут отличаться от твоих обучающих данных; прочитай нужный гайд в документации внутри node_modules до того, как писать код; обращай внимание на предупреждения об устаревании.

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

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

Как писать правила, которые работают

Что я вынес, пока доводил свой файл до нынешнего вида.

Правило должно быть проверяемым. «Пиши хороший код» — не правило: непонятно, нарушено оно или нет. «Не оставлять TODO без описания» — правило, нарушение видно глазами.

Указывай действие, а не пожелание. Не «учитывай, что версия свежая», а «прочитай гайд вот здесь перед тем, как писать код».

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

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

Короткий файл лучше длинного. Правила живут в контексте постоянно, и раздутый файл на пятьсот строк размывает главное. Мой — на двадцать строк, и это осознанно.

Не дублируй README. README — для людей и про то, как запустить проект. Файл правил — про то, как в нём писать код.

Как файл наполняется на практике

У меня простой цикл, и он же — главный совет.

1. Агент делает косяк.
2. Я его правлю.
3. Если такой косяк может повториться — правило едет в файл.

Всё. Никакого «сесть и написать идеальные правила заранее». Файл вырастает из реальных граблей, поэтому в нём нет мёртвых пунктов.

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

Чего от файла правил ждать не стоит

Он не заменяет архитектуру. Он не проверит код за тебя — для этого есть тесты и ревью. И он не спасает от плохо поставленной задачи: если ты не объяснил, что нужно, идеальные правила стиля не помогут — с этого начинается совсем другой разговор, про то, как разложить задачу до того, как писать код.

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

Хочешь настроить это под свой проект?

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

Формат — один на один, на твоей реальной задаче. Подробности и запись — на странице курса, вопросы — в Telegram.