Стандарты кода: место им в review

Третий раз за неделю агент кладёт вспомогательный файл в папку, где каждый файл становится публичным маршрутом. Вы снова пишете в чат: «Сколько можно, не клади сюда утилиты!» Агент извиняется, исправляет — и в следующей сессии делает то же самое. Он не помнит упрёков: каждая сессия начинается заново.

Зачем это нужно

Правило, которое живёт только в вашей голове или в прошлом чате, для агента не существует. Его нужно где-то записать. Вопрос — где: в CLAUDE.md, в промпте или в ревью. От ответа зависит, сколько контекста оно стоит и в какой момент сработает.

Как это устроено

Три уровня проверок. Перед тем как код попадёт в main, его проверяют три слоя:

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

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

CLAUDE.md для этого подходит хуже: он загружается в начале каждой сессии и тратит контекст, даже когда правило к задаче не относится. Документация Claude Code советует держать там только то, что нужно в каждой сессии.

CODING_STANDARDS.md. В учебном проекте skill /code-review на одном из шагов ищет в репозитории всё, что описывает, как писать код: CODING_STANDARDS.md, CONTRIBUTING.md. Ось Standards сверяет diff с найденным. Файл может начаться с одной строки и расти по одному правилу:

All files in `./app/routes` are exposed publicly as routes.
Do not put test files or utility files there.

Context menu items always include a leading icon from `lucide-react`.

Каждая строка появляется одинаково: вы заметили, что агент сделал глупость, и записали правило. Поскольку файл читается только на ревью, его размер не так важен, как размер CLAUDE.md.

Даже без файла ось Standards не пустая: skill несёт базовый набор code smells из книги Мартина Фаулера «Refactoring» — Feature Envy, Shotgun Surgery, Mysterious Name и другие. Ваш файл ложится поверх и переопределяет базу: если проект явно разрешает то, что база посчитала бы запахом, замечание снимается.

Практика

В Cadence создайте CODING_STANDARDS.md в корне репозитория с одним правилом, которое агент уже нарушал при вас. Затем выполните ревью последних изменений:

/code-review

Найдите в отчёте раздел Standards и проверьте, сослался ли ревьюер на ваше правило. Если нарушений нет, добавьте правило, которое заведомо нарушено в текущем diff, и запустите ещё раз.

Подводные камни

• /review — не ваш skill. Project skill code-review заменяет встроенный bundled skill /code-review, но не его алиас: /review запустит встроенное ревью, которое ваш CODING_STANDARDS.md может не учитывать.
• Правило для linter-а. Если правило проверяется механически — форматирование, порядок импортов, — ему место в linter-е: там оно бесплатно и детерминировано.
• Правило в чате. Упрёк в сессии исчезает вместе с сессией. Не ругайте агента — запишите правило в файл.

Вывод: заметили, что агент снова делает не так, — допишите строку в CODING_STANDARDS.md, и ревью поймает это в следующий раз.

Проверь себя

Источники

• Anthropic, Extend Claude with skills — «Resolve skills that share a name»
• Anthropic, How Claude remembers your project — когда загружается CLAUDE.md и что в нём держать
• Anthropic, Commands — /code-review, /review
• По мотивам AI Coding Crash Course, AI Hero: «Enforcing Your Coding Standards»