Навыки проверки

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

Зачем проверка нужна как отдельный механизм

Claude останавливается, когда работа выглядит готовой. Без проверки, которую он может запустить, «выглядит готовой» — единственный доступный сигнал. Каждая ошибка тогда ждёт, пока её заметите вы. С проверкой цикл замыкается: Claude делает работу, запускает проверку, читает результат и правит, пока проверка не пройдёт.

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

• в промпте — «реализуй, прогони тесты, исправь падения» (работает сразу, но зависит от того, вспомнили ли вы);
• как навык — правила проверки в файле, вызываются командой или подключаются сами (этот урок);
• как жёсткий барьер — хук на событие Stop, который не даёт завершить ход, пока проверка не пройдёт (урок «Хуки»).

Отдельно важно требовать доказательства. «Тесты проходят» — утверждение. Вывод команды с числом пройденных тестов — доказательство. Проверить доказательство быстрее, чем перезапустить всё самому, и это единственный способ доверять сессии, которую вы не смотрели.

Что такое навык

Навык — папка с файлом SKILL.md. В начале файла — YAML-описание (frontmatter), дальше — инструкции обычным текстом. Навык подключается двумя способами: вы вызываете его командой /имя, или Claude сам решает, что он подходит к задаче, — по полю description.

Где лежат:

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

Поля frontmatter, которые понадобятся

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

• name — имя для вызова; по умолчанию берётся имя папки.
• description — когда использовать. Именно по этому полю Claude решает, подключить ли навык сам. Пишите про ситуацию, а не про содержимое: «Используй перед тем, как сообщить, что задача выполнена».
• disable-model-invocation: true — запретить Claude вызывать навык самостоятельно; остаётся только /имя. Нужно для навыков с побочными эффектами (деплой, коммит).
• user-invocable: false — скрыть из меню /; вызывать может только Claude. Подходит для фоновых знаний.
• allowed-tools — инструменты, заранее разрешённые на время работы навыка: Bash(pnpm test *). Это не ограничение, а предварительное одобрение, чтобы проверка не останавливалась на вопросах.
• argument-hint — подсказка при автодополнении: [путь или область].
• context: fork — выполнить навык в отдельном субагенте с чистым контекстом; полезно для ревью, чтобы проверяющий не видел рассуждений, которые привели к коду.

В тексте навыка доступна подстановка $ARGUMENTS — всё, что написано после имени команды. И есть динамический контекст: строка вида !`git diff --stat` выполняется до того, как Claude увидит навык, и заменяется выводом команды.

Пишем навык проверки

Задача: перед любым отчётом о завершении Claude обязан прогнать линтер, проверку типов и тесты, показать вывод и честно перечислить, что не прошло. Файл .claude/skills/verify/SKILL.md:

---
name: verify
description: Проверить результат перед отчётом о выполнении. Используй всегда, когда собираешься сказать, что задача сделана, изменения готовы к коммиту или PR можно открывать.
allowed-tools: Bash(pnpm lint *) Bash(pnpm typecheck *) Bash(pnpm test *) Bash(git diff *) Bash(git status *)
argument-hint: "[область: web | api | all]"
---

## Что изменилось

!`git status --short`

!`git diff --stat`

## Порядок проверки

Запусти по очереди и не пропускай шаги, даже если уверен в результате:

1. `pnpm lint` — ошибки исправь, предупреждения перечисли.
2. `pnpm typecheck` — при ошибках правь код, а не добавляй `any` и `@ts-ignore`.
3. `pnpm test` — при падении сначала выясни, тест сломан или код; не удаляй и не отключай тесты без объяснения.
4. Если аргумент `$ARGUMENTS` равен `web`, дополнительно `pnpm --filter web build`.

## Формат отчёта

- Для каждого шага — команда и последние строки её вывода, включая итоговые числа.
- Список того, что не прошло и почему, если такое есть. Не пиши «готово», пока список не пуст или пока каждый пункт не объяснён.
- Список файлов из `git diff --stat`, которые ты не планировал менять, — с объяснением, зачем они изменились.

Разберём, что здесь работает на цель.

Динамический контекст в начале показывает Claude фактический диф до того, как он начнёт отчитываться, — так сложнее «забыть» про случайно изменённый файл. Пункты про any и удаление тестов закрывают два самых частых способа «пройти проверку», не исправив проблему. Формат отчёта требует вывод команд, а не пересказ. А description написан так, чтобы Claude подключал навык сам в момент, когда собирается объявить задачу выполненной.

Вызвать вручную: /verify web. Проверить, что навык виден, можно через /help или просто набрав / в строке ввода.

Навык-ревьюер в отдельном контексте

Второй полезный навык — независимая проверка результата свежими глазами. Идея из документации: проверяющий не должен быть тем, кто писал код. С context: fork навык запускается в субагенте, который видит только диф и критерии, а не ход рассуждений.

---
name: review-diff
description: Независимо проверить текущий диф на соответствие задаче и найти пропущенные случаи.
context: fork
agent: general-purpose
background: false
disable-model-invocation: true
---

Проверь незакоммиченные изменения в рабочем дереве относительно задачи: $ARGUMENTS

1. Прочитай `git diff` и затронутые файлы целиком.
2. Для каждого требования из задачи найди, где оно реализовано, и есть ли тест.
3. Найди изменения вне рамок задачи.
4. Сообщи только пробелы, влияющие на корректность или на требования. Стилевые замечания не нужны.

Вызов: /review-diff перевести формы на токены темы, не менять публичный API компонентов. Ключевая фраза здесь последняя: ревьюер, которого попросили найти проблемы, найдёт их всегда. Ограничение «только корректность и требования» спасает от переусложнения.

Для стандартной проверки на баги есть встроенный /code-review: он делает то же самое в фоновом субагенте и при флаге --fix сразу применяет исправления.

Как это встраивается в длинную сессию

Схема для миграции компонентов на новую дизайн-систему выглядит так. План в режиме плана. Реализация партиями по три-пять компонентов. После каждой партии — /verify web. В конце — /review-diff с исходной формулировкой задачи. Коммит только после того, как оба отчёта чистые.

Заметьте, что навык проверки не гарантирует запуск: Claude может подключить его сам, но может и не подключить. Если проверка должна быть обязательной для каждого хода, её нужно перенести в хук на событие Stop — об этом следующий урок после режимов прав. Навык — это способ описать, как проверять; хук — способ гарантировать, что проверка случится.