Правила проекта: CLAUDE.md

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

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

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

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

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

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

Мой реальный файл

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

@AGENTS.md

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

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

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

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

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

Язык

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Цикл простой, и он же — главный совет:

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

Никакого «сесть и написать идеальные правила заранее». Файл вырастает из реальных граблей, поэтому в нём нет мёртвых пунктов. Устаревшее правило чините сразу: неверное правило хуже отсутствующего — агент будет старательно ему следовать.

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

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

Практическое задание

Заведите в своём проекте файл правил на пять строк. Больше пока не надо:

1. Язык комментариев и коммитов.
2. Одна команда, которой вы проверяете результат.
3. Один запрет — то, что агент у вас уже делал и чего вы не хотите.
4. Одна строка про безопасность: секреты в переменных окружения, валидация пользовательского ввода.
5. Одна строка про версии: где лежит документация вашей версии фреймворка и что её надо прочитать до кода.

Дальше неделю живите по циклу «косяк → правка → правило». Через неделю файл будет ваш, а не мой.