Slash Commands продвинутый уровень: субагенты и оркестрация инструментов

Первые две статьи рассказали, что такое slash command (Markdown-файл) и как префиксом ! внедрять вывод shell в контекст. Эта идёт дальше: как заставить одну команду оркестрировать самые мощные возможности Claude Code — ссылки на файлы, субагенты, MCP-инструменты — и при этом держать права под контролем.

На этом уровне команда перестаёт быть просто «ярлыком для промпта» и становится переиспользуемым маленьким воркфлоу.

Ссылки `@file`: статическое внедрение лучше, чем `!cat`

!cat file.md тоже умеет пропихнуть содержимое файла в контекст, но делает это через shell, и у подхода куча недостатков: каждый запуск поднимает подпроцесс; пробелы и спецсимволы в пути надо экранировать; и Claude Code видит результат не как «файл», а как просто кусок текста.

Ссылка @ — нативная:

---
description: Ревью изменений по правилам проекта
---

Опирайся на следующие правила:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

Теперь просмотри изменения в git diff и укажи все нарушения правил.

!`git diff HEAD`

@путь говорит Claude Code: «прикрепи этот файл к разговору как вложение». Отличие:

Сценарий	С `!cat`	С `@`
Путь из аргумента (`$ARGUMENTS`)	✅ только `!cat`	❌ `@` не разворачивает переменные
Фиксированные правила и шаблоны проекта	⚠️ можно, но тяжело	✅ нативно, экономит вызов shell
Динамический контент (diff, логи, результаты тестов)	✅ только `!`	❌ нельзя

Правило: статические файлы — через @, динамический вывод — через !, путь из аргумента — !cat $ARGUMENTS.

`allowed-tools`: ставить команде границы прав

По умолчанию во время выполнения команды модель может использовать все инструменты сессии. Это не всегда то, чего хочешь — например, /review — это ревью в режиме только-чтение, и ты не хочешь, чтобы оно «заодно» правило строку кода.

Если добавить в frontmatter allowed-tools, на время работы команды разрешены только перечисленные инструменты:

---
description: Код-ревью только для чтения
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

Сравни текущую ветку с master, только читай, ничего не меняй.

!`git diff master...HEAD`

Пара важных деталей:

Bash(git diff:*) — это точечное разрешение: можно только bash-вызовы, начинающиеся с git diff; git push будет заблокирован
Read / Grep / Glob явно открывают только инструменты чтения
Edit / Write не перечислены — даже если модель захочет поправить код, у неё просто нет такого инструмента

Наоборот, команду с высокими правами вроде /deploy можно авторизовать явно:

---
description: Задеплоить текущую ветку
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

Жёстко зафиксировать «что эта команда имеет право делать» надёжнее, чем каждый раз вручную одобрять bash-промпт во время запуска.

Вызов субагента: вынести наружу то, что съедает контекст

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

Правильный способ — отдать такую работу subagent: субагент крутится в своём отдельном контексте и возвращает в основной разговор только вывод. В команде достаточно явно это указать:

---
description: Глубокое исследование всех использований символа
allowed-tools: Task
---

Используй субагент Explore, чтобы глубоко исследовать все использования символа: $ARGUMENTS

Субагент должен покрыть:
- Все точки вызова (включая тестовые файлы)
- Затронутые бизнес-сценарии
- Наличие эквивалентных альтернативных реализаций

Когда субагент вернётся, дай только саммари ≤300 слов, без вставки сырых фрагментов кода.

Запуск /trace SomeClass#some_method поднимает в Claude Code субагент Explore, который параллельно сканирует кодовую базу; в основной разговор прилетает только выжимка. Никакого вывода grep, никаких фрагментов файлов, контекст чистый.

Дальше круче:

---
description: Параллельное исследование трёх кандидатов
allowed-tools: Task
---

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

1. Использовать существующий ActiveJob + Sidekiq
2. Использовать Solid Queue
3. Собрать свою легковесную очередь

Каждый агент отвечает: объём работы, риски, степень вторжения в существующий код. Когда все три вывода вернутся, сравнение сделаю я.

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

Вызов MCP-инструментов: дать команде дотянуться до внешних систем

Если к сессии подключены MCP-серверы (Linear, GitHub, Sentry, собственный прокси к БД и т.п.), команда может прямо попросить модель их использовать:

---
description: Сгенерировать todo по реализации из Linear-issue
allowed-tools: mcp__linear__*, Read, Grep
---

Прочитай полное описание и комментарии Linear-issue $ARGUMENTS.

Сопоставь со состоянием кодовой базы (релевантные файлы найди сам через Grep/Read) и составь todo на реализацию:
- Какие файлы надо менять
- Каждый ли шаг отдельный коммит или делаем вместе
- Есть ли неясные моменты, которые надо сначала уточнить с PM

Не начинай писать код, только план.

mcp__linear__* разрешает все Linear MCP-инструменты — модель может вытащить детали issue, комментарии, статус. Вся команда превращается в точку входа в воркфлоу «от тикета к плану реализации».

Ключевой момент: в allowed-tools имя MCP-инструмента надо писать с полным префиксом (mcp__<server>__<tool>), иначе разрешение не сработает.

Ловушка композиции: slash не раскрываются рекурсивно

Очень распространённое заблуждение: написать /test в файле /review и думать, что это запустит команду test. Не запустит. Slash command раскрывается один раз, на верхнем уровне пользовательского ввода. Внутри команды /xxx — это просто обычный текст: модель его читает, но Claude Code его не выполняет.

Чтобы скомпоновать несколько команд, есть несколько правильных подходов:

Подход A: вынести общую логику в файл контекста, и пусть разные команды подтягивают его через @ или !cat

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

Подход Б: прямо в команде написать «сделай как /review» + повторить ключевые инструкции

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

Подход В: одна команда через инструмент Task поднимает субагента, и в промпте субагента повторно используются те же файлы контекста

Настоящая оркестрация воркфлоу идёт именно этой дорогой. Родительская команда дирижирует и собирает итог, субагент выполняет конкретные шаги.

Антипаттерн, которого надо избегать: писать команду на несколько сотен строк, пытаясь сделать всё одним указанием. Гранулярность рушится, стоимость поддержки взлетает, и бюджет токенов одного запуска съедается одной командой.

Когда что использовать

К этому моменту в Claude Code уже собран почти весь набор механизмов для внедрения «внешних возможностей» в команду. Как выбирать:

Потребность	Предпочтительный механизм
Фиксированные правила, шаблоны, документы контекста	Ссылка `@file`
Живое состояние (diff, логи, результаты тестов, запросы к БД)	Инъекция `!shell`
Параметризованное содержимое файла	`!cat $ARGUMENTS`
Затратное по контексту исследование, поиск по многим файлам	subagent через Task
Внешние системы (трекер, мониторинг, прод)	MCP-инструменты + `allowed-tools`
Многошаговые последовательные/параллельные воркфлоу	Родительская команда дирижирует субагентами

Границы прав объявляй явно через allowed-tools, особенно для команд, которыми пользуется вся команда разработчиков — жёстко зафиксировать, что команда умеет, надёжнее, чем рассчитывать на ручное одобрение при каждом запуске.

Пример, близкий к продакшену

Собираем всё вместе — вот команда «исследовать путь реализации по Linear-тикету»:

---
description: Составить план реализации на основе Linear-тикета
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## Контекст

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## Текущее состояние кодовой базы

!`git log --oneline -10`

## Задача

Вытащи описание, комментарии и связанные тикеты Linear-тикета $ARGUMENTS.

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

Когда оба вернутся, выдай:
- Шаги реализации (упорядоченные по зависимостям)
- Список рисков
- Рекомендуемую гранулярность коммитов

Код пока не пиши.

Запуск /plan ENG-4213, и одна команда прогоняет всю цепочку: вытащить тикет → параллельное исследование кодовой базы → оценка рисков → сведение плана. Пользователю остаётся только прочитать итог и решить, стоит ли начинать.

Это полная дуга первых трёх статей серии про slash command: определить переиспользуемые промпты (intro) → динамически внедрять контекст (context) → оркестрировать инструменты и субагенты (эта статья). На этом уровне .claude/commands/ — это уже не папка ярлыков, а маленькая библиотека воркфлоу команды разработчиков.