Начнём с важной оговорки, чтобы не возникло недоразумения. REVIEW.md — не системный файл Claude Code. В отличие от CLAUDE.md, .claude/rules/ и каталога auto memory, этот файл нигде не описан в документации, автоматически не загружается и специального смысла для инструмента не имеет. Это обычный markdown в вашем репозитории, а имя выбрано командами по договорённости.

Зачем тогда о нём говорить? Затем, что он решает реальную задачу, для которой пройденные механизмы не подходят. Требования к код-ревью — это чек-лист: что смотреть, что считать блокирующим, что оставить на усмотрение автора. Он объёмный, нужен строго в момент проверки диффа и должен читаться людьми не меньше, чем агентом.

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

Что уже умеем / что добавим

В прошлом уроке вы вывели алгоритм выбора механизма: нужно всегда — CLAUDE.md, часть кодовой базы — правило с paths, справочник или процедура — скилл. Теперь применим этот алгоритм к конкретной задаче и увидим, что делать в промежуточном случае: когда материал уже перерос CLAUDE.md, но оформлять его вы пока не готовы.

Что вы узнаете в рамках статьи

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

Ключевые термины

• Практический паттерн — способ организации работы, придуманный командой, а не заложенный в инструмент.
• Чек-лист ревью — перечень проверок, применяемых к изменениям перед приёмкой.
• Блокирующее замечание — проблема, из-за которой изменения не принимаются, в отличие от необязательного пожелания.
• Явное подключение — передача файла в контекст через @-ссылку в промпте.
• Постоянное подключение — импорт файла в CLAUDE.md через @path, при котором он грузится в каждой сессии.

Почему требования к ревью не помещаются в известные механизмы

Прогоним материал через алгоритм трёх вопросов.

Нужен ли он в каждой сессии? Нет. Когда вы правите баг, чек-лист проверки диффа в контексте бесполезен. К тому же он объёмный: полноценный список занимает десятки строк, а CLAUDE.md рекомендуется держать до 200.

Касается ли он части кодовой базы? Тоже нет, и это ломает paths. Ревью применяется к изменениям, а не к файлам определённого типа: сегодня в дифф попал API, завтра стили. Привязка сработала бы криво — правило подключалось бы при чтении файлов, а не при разборе диффа.

Остаётся третий вариант: справочник или процедура. Ответ здесь — да, и логично оформить это скиллом. Но скиллы мы разберём только в следующей главе, а задача есть уже сейчас. К тому же у обычного файла есть достоинство, которого нет у скилла: его читают люди. REVIEW.md в корне репозитория виден любому, кто открывает проект.

Отсюда паттерн: держать чек-лист обычным файлом и подключать в нужный момент.

Как выглядит рабочий чек-лист

Главное отличие работающего чек-листа от неработающего — в разделении обязательного и желательного. Без этого разделения на выходе получается список из двадцати замечаний, где принципиальная утечка соседствует с предпочтением по именованию переменной.

# Требования к ревью

## Блокирующее: без исправления изменения не принимаются

- Ошибки корректности: неучтённые граничные случаи, гонки,
  необработанные ветки исполнения
- Секреты в коде: ключи, пароли, токены в любом виде
- Отсутствие тестов на новое поведение при наличии тестовой базы
- Обратно несовместимые изменения публичного API без пометки

## Обязательные проверки

- Изменения соответствуют заявленной задаче, лишнего нет
- Обработка ошибок присутствует и не является пустым перехватом
- Новые зависимости обоснованы и зафиксированы в lock-файле

## Необязательное: отмечать, но не блокировать

- Предложения по именованию и структуре
- Возможности упростить без изменения поведения

## Не отмечать

- Форматирование: за него отвечает линтер
- Стилистические предпочтения без влияния на поведение

Обратите внимание на последний раздел. Он не менее полезен, чем первый: явный запрет на замечания о форматировании убирает шум и не даёт проверке выродиться в спор о пробелах.

Формулировки должны быть проверяемы, как и в CLAUDE.md. «Хорошая обработка ошибок» ничего не даёт; «обработка ошибок не является пустым перехватом» — даёт.

Как подключить файл

Способов три, и различаются они стоимостью контекста.

Явное подключение через @ в промпте — основной вариант. Файл попадает в контекст ровно тогда, когда нужен, и ничего не стоит в остальное время.

Проверь текущий дифф по требованиям из @REVIEW.md.
Раздели замечания на блокирующие и необязательные.
По каждому укажи файл и строку.
Отмечай только то, что реально влияет на корректность
или нарушает перечисленные требования.

Постоянное подключение импортом — строка @REVIEW.md в CLAUDE.md, после чего файл грузится каждую сессию. Для чек-листа ревью это плохой выбор: постоянная плата за материал, нужный изредка.

Указание в CLAUDE.md без импорта — компромисс. Одна строка с упоминанием файла в обратных кавычках, чтобы она не превратилась в импорт:

- Перед приёмкой изменений сверяйтесь с `REVIEW.md`

Это стоит одной строки контекста и напоминает о существовании файла, оставляя загрузку на момент реальной надобности.

Как не получить выдуманные замечания

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

Лечится это двумя приёмами. Первый — в самом файле: явный раздел «не отмечать» задаёт границу снизу. Второй — в промпте: прямое указание отмечать только влияющее на корректность или нарушающее заявленные требования. Формулировка «отмечай пробелы, а не стилистические предпочтения» работает лучше, чем «проверь внимательно».

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

Когда паттерн пора превращать в механизм

Файл в репозитории — хорошее начало, но у него есть предел.

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

Признак второй: файл разросся, и внутри появились разделы под разные ситуации — отдельно для миграций, отдельно для API. Часть из них удобнее переложить в правила с привязкой к путям.

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

Пока же паттерн решает задачу малой кровью, и это его главное достоинство.

Частые ошибки

• Считать REVIEW.md системным файлом. Он не загружается автоматически и специального значения для Claude Code не имеет. Не подключите явно или импортом — агент о нём не узнает.
• Чек-лист без градации важности. Список без разделения на блокирующее и необязательное даёт поток равнозначных замечаний, где серьёзное теряется среди косметического.
• Непроверяемые формулировки. «Код должен быть поддерживаемым» нельзя применить как критерий. Переводите пункты в наблюдаемые признаки: наличие теста, отсутствие пустого перехвата.
• Постоянный импорт объёмного файла. Строка @REVIEW.md в CLAUDE.md грузит чек-лист каждую сессию, включая те, где он не нужен. Подключайте через @ в момент проверки.

Наиболее частые вопросы

• Обязательно ли имя REVIEW.md? — Нет, имя произвольное: это договорённость команды, а не требование инструмента. Важно лишь, чтобы все знали, где файл лежит.
• Загрузится ли файл сам, если положить его в корень? — Нет. Автоматически загружаются только CLAUDE.md, CLAUDE.local.md и файлы из .claude/rules/; остальное подключается явно.
• Чем это лучше, чем написать требования прямо в промпте? — Файл переживает сессии, лежит в репозитории, доступен команде и правится обычным pull request.
• Можно ли применить паттерн к другим задачам? — Да, схема универсальна: чек-листы развёртывания, шаблоны разбора инцидентов, регламенты миграций.
• Что делать, если проверка находит слишком много мелочей? — Расширьте в файле раздел «не отмечать» и потребуйте в промпте отмечать только влияющее на корректность и заявленные требования.

Итоги

Отличная работа: вы освоили не только конкретный файл, но и более общий навык — отличать практический паттерн от системного механизма. REVIEW.md не загружается сам и ничего не значит для инструмента, но закрывает задачу, для которой в пройденном материале готового ответа нет. Вы умеете построить чек-лист с градацией важности, подключить его без лишних трат контекста и добиться замечаний по делу вместо потока придирок.

Вы также знаете, куда паттерн разовьётся: в скилл, когда сценарий станет повторяться, или в обязательную проверку, когда её нельзя доверить просьбе. В следующем уроке останемся в теме документов, но шире: разберём документацию кода, README и материалы в docs/ — и как не получить формальные комментарии вместо полезных объяснений.