Упражнение — Skill проверки — Claude Code: с нуля до уверенной работы

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

MCP-сервер базы уже даёт агенту доступ к настоящим данным. Осталось зафиксировать процедуру проверки, чтобы она не зависела от сегодняшней формулировки просьбы. Ровно для этого нужен скилл. Соберём его целиком — от frontmatter до формата отчёта — и прогоним на живой базе.

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

Вы умеете писать скиллы: файл .claude/skills/<имя>/SKILL.md, frontmatter с name и description, тело с инструкцией. Умеете подключать MCP-серверы, читать статусы в /mcp и ограничивать права сервера на его стороне.

Теперь соединим две главы в одном рабочем артефакте: скилл задаёт процедуру, MCP даёт данные, allowed-tools не пускает скилл за пределы чтения базы.

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

Почему просьба «проверь базу» даёт разный результат от запуска к запуску
Как записать MCP-инструменты в allowed-tools и где узнать их точные имена
Как устроен скилл проверки: процедура по шагам и фиксированный формат отчёта
Как выглядит успешный прогон и как выглядит найденное расхождение
Что делать, если вывод инструмента упирается в лимиты по токенам

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

Скилл — папка .claude/skills/<имя>/ с файлом SKILL.md: frontmatter плюс инструкция на markdown, которую Claude подгружает, когда задача подходит под описание.
description — поле frontmatter, по которому модель решает, применять скилл или нет. В нём должно быть не только что скилл делает, но и когда он нужен.
allowed-tools — список инструментов, которыми скиллу разрешено пользоваться.
Полное имя MCP-инструмента — mcp__<сервер>__<инструмент>, например mcp__github__search_repositories. В этом виде инструмент указывается в правилах разрешений, в allowed-tools скилла, в поле tools подагента и в матчере хука.
Фиксированный формат отчёта — заданная в скилле структура вывода, одинаковая при каждом прогоне, поэтому её можно сравнивать.

Почему «проверь базу» — ненадёжная инструкция

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

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

Что должно быть готово до старта

Сервер базы должен быть подключён. Проверьте /mcp: сервер db должен показываться как connected, рядом будет количество инструментов и их список.

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@db.internal:5432/app"

Или записью в .mcp.json, если сервер нужен всей команде:

{
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "@bytebase/dbhub",
        "--dsn", "postgresql://readonly:pass@db.internal:5432/app"
      ]
    }
  }
}

Обратите внимание на пользователя readonly. Это требование из урока 9.2: права ограничиваются на стороне сервера, чтобы запросы Claude физически не могли изменить данные. Для проверочного скилла оно особенно к месту — он только читает.

Второй шаг — узнать точные имена инструментов. Все инструменты сервера db называются по схеме mcp__db__<инструмент>: серверная часть фиксирована, конкретная берётся из списка в /mcp. Эти полные имена и пойдут в allowed-tools.

Зачем ограничивать. Скилл проверки смотрит в базу и пишет отчёт в чат. Write и Edit ему не нужны: он не чинит миграции и не правит модели. Оставите набор открытым — агент, найдя расхождение, попробует его исправить, и вместо диагностики вы получите правки поверх своей работы.

Собираем SKILL.md

Создайте .claude/skills/db-check/SKILL.md.

---
name: db-check
description: Проверяет таблицу в базе через MCP-сервер db — схему, набор колонок, количество строк и заполненность обязательных полей. Применяйте после миграции, после изменения модели или перед релизом, когда нужно убедиться, что реальная база соответствует ожиданиям.
allowed-tools: mcp__db__get_schema, mcp__db__run_query
---

# Проверка таблицы в базе

Вы проверяете состояние одной таблицы. Вы не изменяете данные и не правите
код. Если таблица не названа, спросите её имя и остановитесь.

Порядок работы:

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

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

Таблица: <имя>
Схема: OK | РАСХОЖДЕНИЕ — <что именно>
Строк: <число>
Обязательные поля: <колонка> — <N> пустых, ...
Итог: PASS | FAIL

Итог — FAIL, если есть расхождение по колонкам, таблица пуста или в
обязательном поле найдено хотя бы одно пустое значение. Иначе — PASS.
Не смягчайте формулировки и не предлагайте исправления: ваша работа
заканчивается отчётом.

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

Прогон и результат

Вызывается скилл обычной просьбой:

Проверь таблицу orders: ожидаю колонки id, customer_id, status,
total, created_at.

В выводе вы увидите вызовы инструментов, помеченные именем сервера db и названием действия, а затем отчёт. Успешный прогон:

Таблица: orders
Схема: OK
Строк: 128431
Обязательные поля: customer_id — 0 пустых, status — 0 пустых
Итог: PASS

Найденное расхождение:

Таблица: orders
Схема: РАСХОЖДЕНИЕ — нет колонки status
Строк: 128431
Обязательные поля: customer_id — 0 пустых
Итог: FAIL

Второй вариант читается за секунду: миграция не доехала до этой базы. Ценность не в изяществе вывода, а в том, что оба прогона выглядят одинаково.

Доводка после первого прогона

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

export MAX_MCP_OUTPUT_TOKENS=50000

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

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

Неверный формат имени инструмента в allowed-tools. Записи вида db.get_schema или mcp:db:get_schema не распознаются. Формат один: mcp__<сервер>__<инструмент>, с двойными подчёркиваниями, имена — из /mcp.
description без указания, когда применять скилл. Описание «проверяет базу данных» не даёт модели повода взять скилл именно после миграции. Добавляйте условия вызова.
Не зафиксировать формат отчёта. Без явной структуры каждый прогон выглядит по-новому, и сравнивать нечего.
Запрашивать схему всей базы. Вывод упирается в лимиты, а нужная таблица тонет среди сотни чужих. Сужайте запрос в скилле.

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

Почему скилл не подхватился и Claude проверяет базу по-своему? — Скорее всего, дело в description: модель не связала формулировку с назначением скилла. Опишите условия применения или вызовите скилл явно.
Инструменты в allowed-tools есть, а вызовов нет. Почему? — Проверьте /mcp: если сервер не connected, вызывать нечего. Заодно сверьте имена со списком оттуда.
Нужно ли писать в скилле «ничего не меняй в базе»? — Написать полезно, но полагаться на это нельзя. Гарантия — пользователь только для чтения в строке подключения.
Можно ли проверять несколько таблиц? — Да, процедура применяется к каждой по очереди. Но схему выгоднее запрашивать по одной таблице, а не всю базу разом.
Почему в allowed-tools не добавили Bash? — Скиллу он не нужен: все данные приходят через MCP-сервер. Лишний инструмент — лишняя возможность сделать не то.

Итоги

Вы собрали артефакт, соединяющий две большие темы курса: скилл держит процедуру, MCP приносит реальные данные, allowed-tools очерчивает границы. Это и есть типовое применение MCP — не «спросить агента о базе», а закрепить повторяемую проверку, которая одинаково работает у вас и у коллеги, склонировавшего репозиторий.

На этом глава 9 закончена. Вы знаете, как устроен MCP и почему Claude Code выступает клиентом, умеете оценивать доверие к серверу и ограничивать его права, подключили базу и браузер, увидели, как сервер становится частью рабочей процедуры. Заодно у вас накопилось хозяйство: CLAUDE.md, правила, скиллы, подагенты, хуки, записи серверов. Дальше поговорим о том, как всё это упаковать и передать другим, не пересобирая вручную в каждом проекте.