Slash Commands zaawansowane: podagenty i orkiestracja narzędzi

Pierwsze dwa artykuły pokazały, czym jest slash command (plikiem Markdown) i jak używać prefiksu !, żeby wstrzykiwać wyjście shella do kontekstu. Ten idzie dalej: jak sprawić, żeby pojedyncza komenda orkiestrowała najmocniejsze możliwości Claude Code — referencje do plików, podagenty, narzędzia MCP — zachowując uprawnienia pod kontrolą.

Na tym poziomie komenda przestaje być „skrótem do promptu" — staje się małym, wielokrotnego użytku workflowem.

Referencje `@file`: statyczne wstrzykiwanie lepsze niż `!cat`

!cat file.md umie wepchnąć zawartość pliku do kontekstu, ale idzie przez shell i ma kilka wad: każde uruchomienie odpala podproces; spacje albo znaki specjalne w ścieżce trzeba escapować; a Claude Code nie widzi tego jako „pliku", tylko jako kawałek tekstu.

Referencja @ jest natywna:

---
description: Przegląd zmian według konwencji projektu
---

Oprzyj się na tych konwencjach:

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

Teraz przejrzyj zmiany w git diff i wskaż wszystkie naruszenia reguł.

!`git diff HEAD`

@ścieżka mówi Claude Code: „dołącz ten plik do rozmowy jako załącznik". Różnica:

Sytuacja	`!cat`	`@`
Ścieżka z argumentu (`$ARGUMENTS`)	✅ tylko `!cat` zadziała	❌ `@` nie rozwija zmiennych
Stałe konwencje i szablony projektu	⚠️ można, ale ciężko	✅ natywnie, oszczędza wywołanie shella
Treść dynamiczna (diff, logi, wyniki testów)	✅ tylko `!`	❌ niemożliwe

Reguła: pliki statyczne przez @, wyjście dynamiczne przez !, ścieżka z argumentu przez !cat $ARGUMENTS.

`allowed-tools`: nałożyć komendzie granice uprawnień

Domyślnie podczas wykonywania komendy model może korzystać ze wszystkich narzędzi sesji. To nie zawsze jest to, czego chcesz — np. /review to przegląd tylko do odczytu, i nie chcesz, żeby „przy okazji" zmienił linijkę kodu.

Dodając allowed-tools we frontmatterze, na czas trwania komendy dozwolone są tylko wymienione narzędzia:

---
description: Przegląd kodu tylko do odczytu
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

Porównaj bieżący branch z master, tylko czytaj, niczego nie zmieniaj.

!`git diff master...HEAD`

Kilka istotnych rzeczy:

Bash(git diff:*) to uprawnienie punktowe — dozwolone są tylko wywołania bashowe zaczynające się od git diff; git push zostanie zablokowany
Read / Grep / Glob wystawia jawnie tylko narzędzia do odczytu
Edit / Write nie są wymienione — nawet gdyby model chciał poprawić kod, nie ma po prostu takiego narzędzia

Analogicznie, komendę z wysokimi uprawnieniami jak /deploy można autoryzować jawnie:

---
description: Zdeployuj bieżący branch
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

Zapisać na sztywno, „co ta komenda ma prawo robić", jest pewniejsze niż ręczne zatwierdzanie promptu bashowego przy każdym uruchomieniu.

Wywołanie podagenta: wynieść na zewnątrz to, co zjada kontekst

Część zadań rozwala kontekst głównej rozmowy — przeszukać dziesiątki plików w poszukiwaniu wszystkich wywołań funkcji, zrobić statystyki po kodzie, przeanalizować duży blok logów. Zrobione na wprost, tysiące linii wyjścia zostają w kontekście, a dalsza rozmowa staje się wolna i głupsza.

Właściwe podejście: oddać taką robotę do subagent. Podagent działa w swoim oddzielnym kontekście i zwraca do głównej rozmowy tylko wniosek. W komendzie wystarczy wskazać to jawnie:

---
description: Głębokie rozpoznanie wszystkich użyć symbolu
allowed-tools: Task
---

Użyj podagenta Explore, żeby głęboko prześledzić wszystkie użycia symbolu: $ARGUMENTS

Podagent ma pokryć:
- Wszystkie miejsca wywołania (w tym pliki testowe)
- Scenariusze biznesowe, których to dotyczy
- Czy istnieją równoważne alternatywne implementacje

Gdy podagent wróci, daj mi tylko streszczenie ≤300 słów, bez wklejania surowych fragmentów kodu.

Uruchomienie /trace SomeClass#some_method odpala w Claude Code podagenta Explore, który równolegle skanuje bazę kodu; do głównej rozmowy wraca tylko destylat. Żadnego wyjścia z grepa, żadnych fragmentów plików, czysty kontekst.

Dalej mocniej:

---
description: Równoległe rozpoznanie trzech kandydatów
allowed-tools: Task
---

Odpal jednocześnie 3 podagentów, niech każdy przebada jedną z dróg implementacji:

1. Wykorzystać istniejące ActiveJob + Sidekiq
2. Wykorzystać Solid Queue
3. Zbudować własną lekką kolejkę

Każdy agent odpowiada na: nakład pracy, ryzyka, stopień ingerencji w istniejący kod. Kiedy wszystkie trzy wnioski wrócą, porównanie zrobię ja.

Trzej podagenci pracują równolegle, główna rozmowa czeka raz. To jedna z największych dźwigni, jakie daje komenda: zamienić zadanie badawcze, które kosztowałoby kupę tokenów, w workflow uruchamiany jednym kliknięciem.

Wywoływanie narzędzi MCP: pozwolić komendzie dotknąć systemów zewnętrznych

Jeśli do sesji podpięte są serwery MCP (Linear, GitHub, Sentry, własne proxy do bazy itp.), komenda może wprost poprosić model o użycie tych narzędzi:

---
description: Wygeneruj todo implementacyjne z issue Linear
allowed-tools: mcp__linear__*, Read, Grep
---

Przeczytaj pełen opis i komentarze issue Linear $ARGUMENTS.

Zestaw to z aktualnym stanem bazy kodu (pliki znajdź sam przez Grep/Read) i przygotuj todo implementacyjne:
- Jakie pliki trzeba zmienić
- Czy każdy krok to osobny commit, czy robimy razem
- Czy są niejasności, które trzeba najpierw ustalić z PM-em

Nie zaczynaj pisać kodu, tylko plan.

mcp__linear__* autoryzuje wszystkie narzędzia Linear MCP — model może wyciągnąć szczegóły issue, komentarze, status. Cała komenda staje się punktem wejścia do workflowu „od tiketa do planu implementacji".

Ważny punkt: pisząc nazwę narzędzia MCP w allowed-tools musisz użyć pełnego prefiksu (mcp__<server>__<tool>), inaczej uprawnienie nie zadziała.

Pułapka kompozycji: slash commands nie rozwijają się rekurencyjnie

Bardzo częste nieporozumienie: wpisać /test do pliku /review licząc na to, że odpali komendę test. Nie odpali. Slash command jest rozwijany raz, na najwyższym poziomie wejścia użytkownika. Wewnątrz komendy /xxx to zwykły tekst — model go czyta, ale Claude Code go nie wykonuje.

Żeby skomponować kilka komend, są dobre drogi:

Droga A: wyciągnąć wspólną logikę do pliku kontekstu, który różne komendy ciągną przez @ lub !cat

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

Droga B: w komendzie jawnie napisać „zrób jak /review" + powtórzyć kluczowe instrukcje

Nieelegancko, ale działa. Dopóki prompt jest wystarczająco jasny, model pójdzie tą samą drogą.

Droga C: jedna komenda przez narzędzie Task odpala podagenta, a prompt podagenta ponownie wykorzystuje te same pliki kontekstu

Prawdziwa orkiestracja workflowów idzie właśnie tędy. Komenda-rodzic koordynuje i zbiera wynik, podagent wykonuje konkretne kroki.

Antywzorzec, którego należy unikać: pisać komendę na kilkaset linii, próbując załatwić wszystko jedną instrukcją. Granulacja się sypie, koszt utrzymania leci w górę, a budżet tokenów pojedynczego uruchomienia zjada jedna komenda.

Kiedy czego używać

W tym momencie mamy w Claude Code prawie komplet mechanizmów na wstrzykiwanie komendzie „zewnętrznych możliwości". Jak wybierać:

Potrzeba	Preferowany mechanizm
Stałe konwencje, szablony, dokumenty kontekstu	referencja `@file`
Stan na żywo (diff, logi, wyniki testów, zapytania do bazy)	wstrzykiwanie `!shell`
Parametryzowana zawartość pliku	`!cat $ARGUMENTS`
Kontekstożerne rozpoznanie, szukanie po wielu plikach	subagent przez Task
Systemy zewnętrzne (tracker, monitoring, produkcja)	narzędzia MCP + `allowed-tools`
Wielokrokowe workflowy sekwencyjne/równoległe	komenda-rodzic koordynująca podagentów

Granice uprawnień deklaruj jawnie przez allowed-tools, zwłaszcza w komendach współdzielonych w zespole — zapisanie na sztywno, co komenda może, jest pewniejsze niż poleganie na ręcznym zatwierdzaniu przy każdym uruchomieniu.

Przykład zbliżony do produkcji

Sklejamy to wszystko i mamy komendę „zbadaj ścieżkę implementacji na podstawie tiketa Linear":

---
description: Wygeneruj plan wdrożenia na podstawie ticketa Linear
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## Kontekst

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

## Aktualny stan bazy kodu

!`git log --oneline -10`

## Zadanie

Wyciągnij opis, komentarze i powiązane tikety tiketa Linear $ARGUMENTS.

Następnie odpal dwóch podagentów równolegle:
1. Pierwszy: znajdź w bazie kodu wszystkie powiązane istniejące implementacje i moduły do ponownego użycia
2. Drugi: oceń ryzyka — jakich ścieżek kodu o dużym ruchu dotknie ta zmiana, czy są luki w pokryciu testami

Gdy obaj wrócą, wypisz:
- Kroki implementacji (uporządkowane według zależności)
- Listę ryzyk
- Sugerowaną granulację commitów

Nie zaczynaj pisać kodu.

Uruchamiasz /plan ENG-4213 i jedna instrukcja przebiega cały łańcuch: wyciągnąć tiket → równolegle rozpoznać bazę kodu → ocenić ryzyka → zebrać plan. Użytkownikowi zostaje tylko przeczytać wnioski i zdecydować, czy rusza.

To pełny łuk trzech pierwszych artykułów serii o slash commands: zdefiniować wielokrotnego użytku prompty (intro) → dynamicznie wstrzykiwać kontekst (context) → orkiestrować narzędzia i podagenty (ten artykuł). Na tym poziomie .claude/commands/ to już nie folder skrótów, tylko mała biblioteka workflowów zespołu.