Claude Code изнутри: хаки агентной экосистемы, о которых не говорят

Месяц назад написал «Skills, Agents и Commands в Claude Code: когда что юзать». Разложил по полочкам, получил лайки. Думал, разобрался.

Потом полез в доки Anthropic, в чужие конфиги, в собственный .claude/ и понял, что тот пост был верхушкой айсберга. А под поверхностью хаки, паттерны и архитектурные решения, о которых нигде толком не пишут.

Дальше всё, что накопал за месяц экспериментов.

В том посте я дал простую схему: Commands для повторяемых задач, Skills для автоматического подхвата, Subagents для изоляции контекста. Звучит логично. Работает.

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

• «Поэтапное раскрытие» – скиллы загружаются не целиком, а по частям: сначала только название и описание, потом полный файл, потом вспомогательные ссылки. Экономит токены на порядок.

• Context engineering – управление тем, что именно попадает в контекстное окно модели, в каком порядке и в какой момент.

• Hooks – автоматические shell-скрипты, которые срабатывают на события в сессии Claude (сохранение файла, завершение задачи, старт сессии).

• Степени свободы – насколько подробно расписывать инструкции: дать модели общую цель и отпустить или прибить каждый шаг гвоздями.

Это штуки, которые влияют на счёт за токены и на то, насколько адекватно агент выполняет задачи.

Когда только начинал со Skills, думал: пишешь SKILL.md, и готово. Оказалось, Anthropic сделали трёхуровневую систему загрузки. Работает как принцип «загружай только когда нужно, а не всё заранее».

Уровень 1: метаданные. При старте сессии Claude загружает только name и description из YAML-шапки каждого скилла. Это ~50 токенов на скилл. Можно иметь сотню скиллов, и они почти не отъедают контекст.

Уровень 2: SKILL.md. Если Claude решает, что скилл релевантен задаче, читает полный SKILL.md. Это ~500 токенов. Anthropic рекомендуют держать его до 500 строк.

Уровень 3: reference-файлы. SKILL.md ссылается на отдельные файлы (FORMS.md, API-справочник, примеры), и подгружаются только по необходимости. Это уже 2000+ токенов, но только когда действительно нужны.

Anthropic прямо говорят: challenge every token. Каждый параграф в SKILL.md должен оправдывать своё присутствие. Claude и так умный, не надо объяснять ему, что такое PDF или как работают библиотеки Python.

Ещё нюанс, который я не сразу понял: именование скиллов в форме герундия (глагол+ing), вроде processing-pdfs или analyzing-spreadsheets, не стилистическая прихоть. Такой формат помогает Claude быстрее понять, к какой активности относится скилл, и точнее выбирать его при автоматическом подхвате. А описание (description) обязательно от третьего лица, потому что оно инжектится в системный промпт и первое лицо ломает механизм обнаружения.

И важное ограничение: ссылки из SKILL.md на внешние файлы должны быть не глубже одного уровня. Если SKILL.md ссылается на advanced.md, а тот на details.md, Claude может прочитать details.md не полностью (например, только первые 100 строк через head). Вся критически важная информация должна быть доступна в один клик от корня.

Ранее я описал Subagents как «отдельных AI-специалистов с собственным контекстом». Это правда, но неполная.

Вот что я упустил: разные субагенты по-разному работают с контекстом. Explore-агент стартует с чистого листа, и это осознанное решение. Поисковые задачи обычно независимы от текущего разговора, а промежуточные результаты поиска (кучи файлов, grep-выводы) только засоряют основной контекст. А вот general-purpose и plan агенты наследуют полный контекст родительской сессии, потому что им нужно понимать, о чём вы уже договорились.

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

Допустим, вы строите систему ревью кода. Можно сделать code-reviewer на sonnet, он дешевле, для стандартных проверок хватает. Отдельно security-auditor, тоже на sonnet, но с другим промптом и изолированным контекстом, чтобы его выводы не смешивались с обычным ревью. А главный агент на opus координирует обоих и принимает финальное решение.

В своих проектах в основном пробую стандартные паттерны:

Verifier – скептик, который проверяет, что заявленная работа действительно сделана. Ставишь на model: haiku, он пробегает тесты и ищет дыры. Решает проблему, когда AI отчитывается «готово», а на деле половина не работает.

Orchestrator – цепочка Planner → Implementer → Verifier, где каждый агент специализируется на своём этапе. Планировщик разбирает задачу и создаёт техплан, исполнитель пишет код строго по плану, верификатор проверяет результат. Между ними структурированный output как эстафетная палочка: каждый передаёт следующему итоговый артефакт работы.

Debugger – специалист по root cause analysis: ловит стектрейс, воспроизводит, находит минимальный фикс, проверяет.

Конфиг субагента: markdown-файл с YAML-шапкой. Вот гипотетический пример:

---name:code-reviewerdescription:Reviewscodeforbugsandstyleviolations.UsewhenimplementingPRrevieworaftercompletingfeatures.model:sonnet--- Youareacodereviewerspecializinginfindingbugsandstyleviolations.Focus on:1.Logicerrorsandedgecases2.Securityvulnerabilities3.PerformanceissuesReport findings by severity:Critical/High/Medium.

Обратите внимание: промпт короткий и конкретный. Один из главных anti-patterns, который описывают и Anthropic, и Cursor: промпты на 2000+ слов делают субагент не умнее, а медленнее. Плюс каждый субагент это отдельное контекстное окно, отдельные токены, отдельные деньги. Пять параллельных субагентов ≈ пятикратные затраты. Так что «а давайте сделаем 20 агентов на все случаи жизни» это путь к разорению и медленной работе. Начинайте с 2-3 сфокусированных агентов. Добавляйте новых, только когда есть чёткий, отличающийся use case.

Hooks – это самая недооценённая фича Claude Code. Кастомные shell-команды, которые автоматически срабатывают на события в сессии. PreToolUse, PostToolUse, SessionStart, Stop, SubagentStop, UserPromptSubmit, PreCompact, PermissionRequest и ещё несколько, порядка десятка типов, и некоторые из них открывают безумные возможности.

Хак #1: «Do more» через Stop hook. Claude завершил задачу, вернул ответ. А Stop hook возвращает JSON с "continue": true, и Claude продолжает работать. Можно сделать prompt-хук, который проверяет, все ли пункты чеклиста выполнены, и если нет, гонит Claude дальше. По сути, бесконечный рабочий цикл.

{"hooks":{"Stop":[{"hooks":[{"type":"prompt","prompt":"Review whether the task is complete. If all requirements are met, respond with 'complete'. If work remains, respond with 'continue' and specify what still needs to be done."}]}]}}

Хак #2: Auto-format после каждой записи. PostToolUse хук с матчером "Write|Edit", и Prettier (или Black, или gofmt) автоматически форматирует каждый файл, который Claude пишет. Больше никаких ручных npx prettier --write.

{"hooks":{"PostToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"command","command":"prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""}]}]}}

Хак #3: Контекст при старте сессии. SessionStart хук инжектит git status и содержимое TODO.md. Claude сразу знает, на какой ветке вы, какие файлы изменены, что в бэклоге. Без вашего участия.

{"hooks":{"SessionStart":[{"hooks":[{"type":"command","command":"git status --short && echo '---' && cat TODO.md 2>/dev/null || true"}]}]}}

Хак #4: Звуковое уведомление. Stop хук с afplay /System/Library/Sounds/Glass.aiff, и Mac играет звук, когда Claude закончил. Мелочь, но если у вас сессия на 10+ минут, не приходится постоянно переключаться и проверять.

Отдельно про матчеры. "Write|Edit" это pipe-синтаксис для нескольких инструментов, "Bash(npm test*)" матчит по аргументам конкретной команды. Матчеры регистрозависимые: "bash" не поймает инструмент Bash.

Хуки могут возвращать структурированный JSON с полями decision (approve/block/allow/deny), reason (объяснение для Claude), continue (для Stop-хуков) и updatedInput (модификация входных параметров инструмента до выполнения). Это необычный для меня механизм: можно блокировать опасные команды, автоматически одобрять безопасные, модифицировать параметры на лету.

Context engineering. Наткнулся на этот термин в блоге Anthropic. Это не промптинг. Это шире. Информационная архитектура вокруг модели: что именно попадает в контекстное окно, в каком порядке, в какой момент.

Почему это важно: каждый новый токен в контексте немного ухудшает способность модели «видеть» старые токены. Это называют context rot – буквально «гниение контекста»: чем длиннее контекст, тем хуже модель удерживает внимание на ранних частях. Исследования Chroma показали, что производительность падает с длиной контекста, а не со сложностью задачи. На практике, особенно для сложных многошаговых задач, безопаснее считать эффективным 60-70% контекстного окна.

Отсюда практическое правило: не начинайте сложную задачу, когда контекст уже больше чем наполовину заполнен. Лучше /compact или /clear и свежая сессия.

Claude Code использует system reminders, теги , которые автоматически вставляются в разных местах контекста. Они напоминают модели о текущих целях, доступных инструментах и ограничениях. То же самое делают todo-списки: когда Claude обновляет todo.md между шагами, он, по сути, перезаписывает свои цели в конец контекста, где «внимание» сильнее всего. По сути, хак против «потери в середине», когда модель хуже «видит» информацию из середины длинного контекста.

Полезный паттерн – handoff: перед тем как сделать /clear, попросите Claude написать саммари текущей сессии. Что сделано, что осталось, какие решения приняты, какие файлы затронуты. Сохраните в файл. Начните новую сессию и дайте этот файл как контекст. По сути, ручная передача смены между «двумя Claude».

Я бы хотел ещё поделиться с вами вот таким проектом awesome-claude-code, там собраны интересные готовые команды: сформировать changelog, создать hook, провести анализ кода и так далее.

Было бы нечестно рассказать только про хаки и не упомянуть грабли.

Каждый скилл, каждый субагент это токены, а токены – деньги. «Поэтапное раскрытие» помогает, но если у вас 50 скиллов и 10 агентов, даже метаданные начинают весить. А каждый вызов субагента это полноценный отдельный разговор с моделью. Пять параллельных субагентов = пятикратный расход. Узнал это на практике: запустил кучу Explore-агентов для документирования проекта, счётчик токенов полетел вверх. Работает быстро, но вопрос толщины кошелька.

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

Hook timeout по умолчанию 60 секунд. Сложную логику в хук не засунешь. Если валидатор работает дольше, придётся выносить в отдельный процесс.

Eval-driven development звучит отлично в теории. Anthropic рекомендуют: сначала создай evaluation (тестовые сценарии), потом пиши скилл. На практике строить evals до того, как ты вообще понял, что скилл должен делать, тяжело. Я честно пытался, но чаще получается итеративно: написал → попробовал → поправил → повторил.

Deny не так надёжен, как кажется. Про это я писал в посте про песочницу для AI: когда Claude не смог получить доступ к файлу напрямую, он пошёл написал shell-скрипт. Не сработало, написал Python-скрипт и через него добрался. Находчивость модели иногда работает против ваших ограничений.

Граница между Skill, Command и Subagent до сих пор размытая. Когда command, а когда skill? Если задача одноразовая и не нужна изоляция, command. Если Claude должен сам понимать, когда запускать, skill. Если нужен отдельный контекст, subagent. Но на практике бывают серые зоны, когда подходит и то, и другое.

Если после всего этого хочется что-то поменять в своём workflow, вот порядок, который мне кажется разумным:

Начните с commands. Если ловите себя на повторяющихся промптах, превращайте их в команды. /handoff для передачи контекста между сессиями, /review для стандартного ревью. Это самый низкий порог входа.

Потом – skills. Когда commands освоены, выносите в skills то, что Claude должен запускать автоматически. Не забывайте про «поэтапное раскрытие»: держите SKILL.md компактным, детали — в отдельные файлы.

Субагенты – в последнюю очередь. Первый субагент на дешёвой модели (sonnet или haiku) с одной конкретной ответственностью. Например, «Верификатор», который проверяет тесты после каждого изменения. Хороший первый кандидат.

Один SessionStart hook, который инжектит git status, уже заметно улучшит каждую сессию. Просто начните с малого.

И регулярно проверяйте /context. Это покажет, сколько контекстного окна уже использовано. Если больше 60%, время делать compact или начинать свежую сессию.

А как у вас? Сколько скиллов в .claude/? Hooks пробовали или пока страшно давать Claude такую свободу? Делитесь, реально интересно посмотреть на чужие конфиги.