Гайд · 13 мин чтения

Как эффективно использовать Claude Code: CLAUDE.md, скиллы, hooks и субагенты

Разбор практик Claude Code, которые работают в продакшене: CLAUDE.md, AGENTS.md, hooks, субагенты, скиллы, MCP и четыре места, где агент ломается незаметно.

4 просмотров
Как эффективно использовать Claude Code: CLAUDE.md, скиллы, hooks и субагенты

Почему эта статья

За год в Claude Code появилось столько всего, что легко утонуть: какой CLAUDE.md писать, когда AGENTS.md, зачем hooks, как делегировать работу субагентам, где подключать MCP, а где нет. Многое звучит как маркетинг — а в рабочем проекте полезна только часть.

Этот материал собирает семь блоков по основным темам: как устроен CLAUDE.md и чем от него отличается AGENTS.md, когда hooks лучше инструкций, как субагенты экономят токены, какой минимум скиллов нужен на каждый день, зачем MCP и когда без него лучше. В конце — четыре места где Claude ошибается незаметно, даже когда результат выглядит рабочим.

Цитаты и примеры — из статей и open-source репозиториев практиков: по ходу будут имена и ссылки, чтобы можно было пойти читать первоисточник.

1. CLAUDE.md — это не мануал, это ограничения

CLAUDE.md — не документация проекта для агента. Это список того, чего Claude не должен делать, и короткие указатели куда смотреть в сложных случаях.

Shrivu Shankar формулирует это так:

«Treat your CLAUDE.md as a high-level, curated set of guardrails and pointers.» («Относись к CLAUDE.md как к высокоуровневому, тщательно отобранному набору ограничений и указателей».)

Четыре правила

1. Пиши по мере ошибок Claude. Пустой CLAUDE.md — нормально. Каждая ошибка → одна строка, чтобы она не повторилась. Boris Cherny (создатель Claude Code) рассказывал: вся команда шарит один CLAUDE.md в git, дописывает несколько раз в неделю — Claude ошибся у одного, поправили для всех.

2. Не встраивай файлы через @. Соблазн написать @docs/architecture.md — не надо. Это съедает токены. Лучше указатель с контекстом: «For complex usage or FooBarError, see path/to/docs.md». Claude сам прочитает файл, если задача требует.

3. Всегда альтернатива. Плохо: Never use --foo-bar. Хорошо: Never use --foo-bar, prefer --baz (it handles edge case X). Первая формулировка блокирует Claude без пути дальше — он начинает искать обходные решения ещё хуже.

4. CLAUDE.md как forcing function. Если инструкция разрастается — проблема не в CLAUDE.md, проблема в инструменте. Если новому разработчику нужно объяснять 10 правил запуска тестов — пусть скрипт bin/test их скроет, в CLAUDE.md остаётся одна строка Run tests: bin/test.

Пример минимального CLAUDE.md

# Monorepo

## Python
- Always use type hints
- Test with `uv run pytest`

## Internal CLI tool (./cli/)
- Usage example: `./cli/tool --help`
- Always validate input with schema X
- Never use --foo-bar, prefer --baz (handles edge case Y)

For complex tool usage, see ./cli/docs.md

10-15 строк по делу, с указателями наружу. Не 1000-строчный мануал.

Альтернатива для больших команд: модульная структура

Nick Saraev в крупных проектах разбивает CLAUDE.md на отдельные файлы-правила (workflow, technical, style). Корневой CLAUDE.md становится одностраничным индексом. Имеет смысл когда над проектом работают 5+ разработчиков и одного файла становится мало.

2. CLAUDE.md или AGENTS.md?

В 2025-2026 появился AGENTS.md — универсальный формат, работает с Claude Code, Cursor, Aider, Codex и будущими агентами. Крупные OSS мигрируют на него.

Примеры из живых репо

OpenAI — в openai/openai-agents-python/CLAUDE.md стоит одна строка: AGENTS.md. Весь контекст вынесен в AGENTS.md, а CLAUDE.md стал простым указателем.

AGENTS.md в репозитории Cloudflare workers-sdk на GitHub AGENTS.md в cloudflare/workers-sdk — реальный файл в проде

Cloudflare — cloudflare/workers-sdk/AGENTS.md: - Таблица «WHERE TO LOOK» (задача → где искать → заметки) — карта кодовой базы - Явная секция Anti-Patterns с перечнем запретов - В каждом подпакете packages/*/AGENTS.md — свой локальный контекст

Sentry — getsentry/sentry/AGENTS.md: - Иерархия: корневой + src/AGENTS.md + tests/AGENTS.md - Жёсткое правило «Never include customer info» - Скиллы в .agents/skills/

Нужно ли переходить

Привязка к одному инструменту — технический долг. Год назад все писали .cursorrules. Сейчас Cursor читает AGENTS.md. AGENTS.md — попытка не повторить историю с vendor lock-in.

3. Hooks — там, где CLAUDE.md не справляется

CLAUDE.md — совет. Claude может его проигнорировать, особенно когда контекст переполнен. Для критичного (секреты не коммитить, тесты зелёные, линтер чистый) нужны hooks — они срабатывают гарантированно.

Suna идея: CLAUDE.md — вероятностный, hook — детерминированный. Simon Willison в обзоре Claude Skills продвигает эту же логику: механические ограничения работают надёжнее, чем инструкции о поведении.

Валидировать на финальном этапе, не в процессе

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

Matcher в Claude Code пишется как "matcher": "Bash", а фильтрация по конкретной команде (git commit) делается уже в bash-скрипте через jq на tool input. Shankar использует файл-маркер: /tmp/agent-pre-commit-pass создаётся когда тесты прошли. Commit-hook проверяет наличие файла — если нет, блок.

Паттерн защиты секретов

Один из самых полезных hooks — блокировка коммита с потенциальными секретами:

#!/usr/bin/env bash
# .claude/hooks/pre-commit-secrets
if git diff --cached --no-color | \
   grep -E '(api_key|secret|password|BEGIN RSA|BEGIN OPENSSH)'; then
  echo "🚫 Secret-like pattern found in staged changes"
  exit 1
fi

С этим Claude работает автономно: попробует закоммитить API-ключ — получит ошибку, уберёт секрет, попробует снова. До успеха без участия человека.

Минимум что ставить hook'ом

Когда НЕ использовать hooks

Для стилистики и предпочтений — именования, комментарии, архитектурные паттерны — hooks не работают. Это слишком субъективно. Это территория CLAUDE.md.

Правило: если нарушение можно проверить автоматически без эвристики — hook. Если требуется суждение — CLAUDE.md.

4. Субагенты для разведки — главный выигрыш по токенам

Контекст — самое дорогое в Claude Code. 200 тысяч токенов окна в Sonnet заполняются быстрее чем кажется. Только MCP-инструменты и системные tool definitions занимают 16-17 тысяч постоянно — Nick Saraev показал это на своём /context.

Grep по репо, чтение документации, разведка кода съедает половину остатка ещё до начала реальной работы. Решение: делегировать разведку субагенту.

В треде r/ClaudeAI «My full Claude Code setup after months of daily use» этот паттерн называют «biggest single quota win». Boris Cherny подтверждает — команда разработки Claude Code использует тот же подход.

Как это работает

Главный агент просит встроенного субагента (Explore, general-purpose) выполнить разведку: «use the Explore agent to find all API endpoints and return a short summary». Субагент уходит со своим контекстом, читает 50 файлов, возвращает сжатое summary в ~500 токенов. Главное окно остаётся чистым.

Субагенты управляются через /agents или вызываются естественным языком в промпте.

Grep в главном агенте съедает 50k токенов, через субагента — 500 токенов Тот же grep: напрямую в главном контексте vs через делегирование субагенту

Когда применять

Когда НЕ применять

Нюанс: Master-Clone вместо жёстких ролей

Ошибка — создавать субагентов с фиксированными ролями («reviewer», «writer», «tester»). Это антипаттерн: главный агент теряет видение картины, жёсткая делегация ограничивает гибкость.

Правильно по Shankar — Master-Clone: в CLAUDE.md описан общий контекст, главный агент сам решает когда и для чего спавнить субагента. Динамически, не по статичному шаблону.

5. Скиллы, команды, режимы: минимальный набор

Встроенных возможностей Claude Code хватает для 80% задач. Свои скиллы писать есть смысл только под повторяющийся workflow.

Batsov в статье о скиллах признаётся:

«I mostly ignored the built-in skills. Everyone online was saying "go make your own skills," so that's what I did.» («Я долго игнорировал встроенные скиллы. В интернете все говорили "пиши свои" — я и писал. Оказалось — зря.»)

Три разные механики

В Claude Code три похожих на вид, но разных по устройству вещей:

Нюанс: Shift+Tab в Normal Mode сначала включает Auto-Accept, повторный — Plan Mode. Три состояния по кругу.

Минимальный набор на каждый день

Что Когда использовать
Plan Mode (Shift+Tab) Перед крупной фичей — Claude пишет план, согласовываем, затем имплементит
/review Перед коммитом — ищет баги, edge cases, архитектурные проблемы
/simplify После батча AI-кода — убирает unused imports, redundant переменные, чистит дубли
/batch Параллельные однотипные правки на 5-30 файлах (через git worktrees)
/compact Сжать историю между фазами работы, проактивно
/clear + короткий catch-up При смене задачи. Чище чем /compact
/context Проверить что занимает контекст. Раз в сессию минимум

Правило Batsov: /review для корректности, /simplify для чистоты. Сначала баги, потом мусор. Не наоборот — иначе можешь «убрать» нужный код.

Как писать свои скиллы

Минимальный SKILL.md (пример Batsov):


name: deploy
description: Deploy current branch to staging
disable-model-invocation: true
allowed-tools: Bash

Deploy steps:
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `./scripts/deploy.sh staging`

Поле disable-model-invocation: true означает: скилл запускается только человеком, Claude его не вызовет автоматически. Нужно для операций с side effects — деплои, удаление данных, отправка писем.

Refinement loop до 98% точности (Nick Saraev)

Для скилла, который должен работать надёжно (не только у тебя):

  1. Написать наивный прототип.
  2. Запустить на чистой сессии Claude Code — без контекста твоего проекта.
  3. Посмотреть где Claude недопонял или сделал не так.
  4. Дописать скилл, учтя проблемы.
  5. Повторять, пока на чистой сессии не срабатывает с первой попытки.

3-4 цикла — и скилл работает с точностью ~98% (формулировка Nick Saraev). Медленно, но единственный способ сделать то, что работает «в дикой природе», а не только у автора.

6. MCP — только как шлюз, не как API

Ошибка с MCP (Model Context Protocol) — подключать для всего подряд. MCP должен быть secure gateway с 2-3 высокоуровневыми операциями, а не набором из 40 мелких read_a / read_b / update_c.

Shankar:

MCP manages auth/security, then gets out of the way.

Цена MCP по токенам

Каждый подключённый MCP съедает контекст постоянно, даже когда не вызывается — его описание висит в системном промпте. Nick Saraev показывает на /context: у него на активных MCP-тулзах регулярно уходит ~17 тысяч токенов из 200. Это 8% окна, исчезающих ещё до начала работы.

Меньше MCP → больше контекста для задачи.

Три операции — достаточно

Shankar приводит идеальный минимум MCP-интерфейса:

- download_raw_data(filters…)
- take_sensitive_gated_action(args…)
- execute_code_in_environment_with_state(code…)

Вытащить данные. Сделать одно действие с side effects под контролем. Выполнить код в sandbox. Всё остальное (обработка, промежуточные шаги) — агент скриптит сам поверх этих примитивов и CLI.

Что НЕ надо через MCP

Когда MCP действительно нужен

  1. Работа с auth/токенами/секретами — MCP хранит credentials, агент их не видит
  2. Sandbox для действий с side effects — тип «execute_code» с ограничениями
  3. Интеграция с закрытыми системами без CLI — Playwright MCP для браузера

MCP как этап прототипирования (Nick Saraev)

Практичный workflow решения между MCP и skill:

MCP использую, чтобы быстро проверить — возможна ли интеграция. «Можем ли мы сделать X, Y, Z?» Если с первого раза получилось — конвертирую в skill и нахожу API-эндпоинты напрямую.

MCP — инструмент быстрого эскиза. Когда интеграция валидирована — часто выгоднее перенести в skill: работает через прямые API-вызовы и не съедает токены постоянно.

Ориентир для стека

У Shankar подключён один MCP — Playwright для браузера. Всё остальное (Jira, AWS, GitHub) — простые CLI через Bash. Если твой MCP-стек вырос до 10+ серверов, стоит пересмотреть.

7. Где Claude Code ломается

Armin Ronacher (создатель Flask) написал 40 тысяч строк инфраструктурного сервиса на Go с Claude Code. Его вывод в статье «90%»:

«I still treat every line as my responsibility, judged as if I wrote it myself.» («Я по-прежнему отвечаю за каждую строку — как если бы сам её написал.»)

AI пишет большую часть кода. Ответственность остаётся на разработчике. Четыре типа поломок, где Claude ошибается незаметно — результат выглядит рабочим, проблема проявляется в проде.

1. Архитектурная слепота

«They can't keep the whole picture in scope. They will recreate things that already exist.» («Они не удерживают всю картину в поле зрения. Они воссоздают то, что уже существует.»)

Если в репо уже есть утилита http_client.rb, Claude может написать новую в api_helper.rb и не упомянуть существующую. Дубликаты, рассинхронизация, техдолг.

Защита: архитектуру рисует человек. Claude получает готовую схему с явными указателями «используй существующий X, не пиши новый Y».

2. Опасные defaults

Три регулярные ловушки по Ronacher:

Конкретный пример Ronacher: реализовал rate limiter. Функционально работал — но без jitter и с плохим storage. Выглядело нормально до нагрузки.

Защита: прописать в CLAUDE.md / AGENTS.md: - «Всегда актуальная версия library (проверять на pypi/npm)» - «Все exceptions логируются, не подавляются тихо» - «Для новых endpoints обязательны log + metric»

3. Конкурентность и состояние

«Claude не схватывает goroutines и threading достаточно хорошо для надёжного кода.»

State machines, race conditions, threading, distributed locks — здесь Claude ломается чаще всего. Не потому что не знает концепций, а потому что не удерживает инварианты достаточно долго.

Защита: эти куски пишет человек. Claude помогает только с unit-тестами и ревью.

4. Ложное «готово»

Самая коварная проблема. Claude говорит «all done» без фактического запуска тестов. На вопрос «прогнал тесты?» отвечает «yes» — но вывода не показывает.

Решение — правило, которое физически мешает заявить готовность без доказательства. Вариант копипасты в CLAUDE.md:

Before claiming "done":
1. Run the verify command (bin/test or equivalent)
2. Show its output in the response
3. Never claim complete without showing passing output

Shankar усиливает это hook'ом с файл-маркером (см. блок 3).

Цифры из того же HN-треда

В обсуждении best practices на Hacker News (тред id=43735550) пользователи сравнили режимы работы:

Разница не в умении — в наличии явных правил и автоматических проверок.

TL;DR — чек-лист

  1. CLAUDE.md = ограничения, не мануал. «Never X, prefer Y». Дописывай по ошибкам.
  2. Для новых проектов — сразу AGENTS.md. CLAUDE.md делается указателем на него. Не будет lock-in.
  3. Hooks на commit, не на edit. PreToolUse с matcher Bash блокирует секреты, непрошедшие тесты, лишний console.log. CLAUDE.md для советов, hooks для законов.
  4. Exploration — субагентам. Explore / general-purpose для grep, документации, разведки. Главный контекст остаётся чистым.
  5. Минимум на каждый день: Plan Mode, /review, /simplify, /compact. Свои скиллы — через refinement loop на чистой сессии.
  6. MCP только как gateway. 2-3 высокоуровневых операции, не 40 мелких. CLI (git, gh, aws) для всего остального.
  7. Архитектура, конкурентность, observability, «готово» — всегда на человеке. AI пишет большую часть кода, ответственность остаётся на тебе.

Собираешь первый реальный проект с Claude Code?

Посмотреть квест