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 його не виконує.

Щоб скомпонувати кілька команд, є кілька правильних підходів:

Підхід А: винести спільну логіку у файл контексту, і хай різні команди тягнуть його через @ або !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/ — це вже не тека ярликів, а невелика бібліотека воркфлоу команди розробників.