Tworzenie poleceń niestandardowych

Każdy zespół ma tego jednego starszego programistę, który zawsze zadaje właściwe pytania podczas przeglądu kodu. Sprawdza przypadki brzegowe obsługi błędów, weryfikuje, że zapytania do bazy danych używają indeksów, i wychwytuje zapytanie N+1, zanim trafi na produkcję. Polecenia niestandardowe pozwalają zapisać osąd tego programisty w wielokrotnego użytku polecenie /review, które może uruchomić każdy członek zespołu.

Co zdobędziesz

• Jak tworzyć niestandardowe polecenia slash — od prostych szablonów promptów po pełne przepływy pracy agentów
• Wzorce konfiguracji subagentów do przeglądu kodu, audytu bezpieczeństwa i testowania
• Techniki dzielenia się poleceniami w zespole przez kontrolę wersji
• Strategie budowania biblioteki poleceń specyficznych dla domeny

Tworzenie niestandardowych poleceń slash

Polecenia niestandardowe w Claude Code to pliki markdown, które znajdują się w określonych katalogach. Gdy wpiszesz / w REPL, pojawiają się obok poleceń wbudowanych.

Struktura plików

Polecenia to pliki .md w tych lokalizacjach:

Lokalizacja	Zakres	Dostępne jako
.claude/commands/review.md	Projekt, współdzielone z zespołem	/review
~/.claude/commands/standup.md	Osobiste, wszystkie projekty	/standup

Nazwa pliku staje się nazwą polecenia — bez prefiksu project: ani user:. Podkatalogi tworzą przestrzeń nazw w nazwie polecenia za pomocą dwukropka: .claude/commands/test/integration.md wywołuje się jako /test:integration, a nie samo /integration.

Notatka

Niestandardowe polecenia slash zostały połączone ze skillami. Plik .claude/commands/review.md i skill .claude/skills/review/SKILL.md oba tworzą /review i działają tak samo. Twoje istniejące pliki w .claude/commands/ nadal działają, więc wszystko poniżej wciąż obowiązuje. Skille są zalecaną formą na przyszłość, ponieważ dodają katalog na pliki pomocnicze oraz frontmatter, który pozwala Claude wczytywać je automatycznie, gdy są istotne.

Proste polecenie przeglądu

Utwórz .claude/commands/review.md:

Przejrzyj zmiany w aktualnym git diff. Dla każdego pliku:

1. Sprawdź obsługę błędów: Czy wszystkie operacje async są opakowane w try/catch? Czy odpowiedzi błędów zawierają znaczące komunikaty?
2. Sprawdź wydajność: Czy są zapytania N+1? Niepotrzebne re-renderowania? Brakujące indeksy dla nowych zapytań?
3. Sprawdź bezpieczeństwo: Czy dane wejściowe użytkownika są walidowane? Czy zapytania SQL są sparametryzowane? Czy sekrety są prawidłowo obsługiwane?
4. Sprawdź testy: Czy zmiany mają odpowiednie pokrycie testami? Czy przypadki brzegowe są przetestowane?

Format wyjścia:
- Zacznij od podsumowania jednoliniowego: PASS, NEEDS CHANGES lub BLOCKING
- Wypisz ustalenia pogrupowane według pliku
- Dla każdego ustalenia wyjaśnij DLACZEGO to ważne i zasugeruj konkretną poprawkę

Teraz każdy członek zespołu może uruchomić /review i otrzymać spójny, dokładny przegląd kodu.

Wskazówka

Kopiuj-wklej prompt, aby wywołać polecenie po przygotowaniu swojej pracy:

/review

Najpierw umieść w staging zmiany, które chcesz poddać przeglądowi (git add -p), a następnie uruchom /review w REPL. Polecenie czyta diff ze staging i zwraca werdykt PASS / NEEDS CHANGES / BLOCKING pogrupowany według pliku.

Wskazówka

Kopiuj-wklej polecenie dla przeglądu skupionego na bezpieczeństwie:

Utwórz .claude/commands/security-audit.md:

Przeprowadź audyt bezpieczeństwa aktualnych zmian w bazie kodu (git diff HEAD).

Sprawdź:
- Luki injection (SQL, XSS, command injection)
- Ominięcia uwierzytelniania/autoryzacji
- Ujawnienie wrażliwych danych (klucze API, tokeny, PII w logach)
- Niezabezpieczone zależności (sprawdź zmiany package.json)
- Brakującą walidację wejścia na endpointach API
- Hardcoded credentials lub sekrety

Dla każdego znaleziska oceń priorytet jako CRITICAL, HIGH, MEDIUM lub LOW.
Podaj dokładny plik i numer linii, lukę oraz konkretną poprawkę.

Dynamiczne polecenia ze zmiennymi

Polecenia mogą zawierać $ARGUMENTS, aby przyjmować dane wejściowe podczas wywoływania:

.claude/commands/explain.md

Wyjaśnij następujący kod lub koncept w kontekście tego projektu: $ARGUMENTS

Skup się na:
- Co robi i dlaczego istnieje
- Jak łączy się z otaczającym kodem
- Wszelkich nieoczywistych decyzjach projektowych
- Potencjalnych pułapkach dla przyszłych maintainerów

Użycie: /explain logika ponownego połączenia WebSocket w src/realtime/

Budowanie subagentów

Subagenty to wyspecjalizowane instancje Claude Code z własnym oknem kontekstu, narzędziami i instrukcjami. Są idealne do zadań wymagających skoncentrowanej analizy bez zanieczyszczania kontekstu głównej sesji.

Format pliku subagenta

Utwórz .claude/agents/reviewer.md:

---
name: reviewer
description: "Ekspertowy recenzent kodu. Wyzwala się automatycznie po zmianach w kodzie lub gdy wymagany jest przegląd."
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
---

Jesteś starszym recenzentem kodu z ekspertyzą w TypeScript i Node.js.

Podczas przeglądania kodu:
1. Najpierw przeczytaj git diff, aby zrozumieć zakres zmian
2. Sprawdź każdy zmodyfikowany plik pod kątem:
   - Problemów z bezpieczeństwem typów (typy any, brakujące sprawdzenia null)
   - Luk w obsłudze błędów
   - Problemów wydajnościowych (niepotrzebne iteracje, brakująca memoizacja)
   - Pokrycia testami
3. Bądź konkretny: odwołuj się do dokładnych ścieżek plików i zakresów linii
4. Sugeruj konkretne poprawki, nie niejasne ulepszenia
5. Doceniaj dobre wzorce, gdy je widzisz

Wyprodukuj strukturalizowany przegląd z werdyktem APPROVE, REQUEST_CHANGES lub COMMENT.

Opcje konfiguracji subagenta

To są pola, które ustawiasz w YAML frontmatter pliku subagenta. Wymagane są tylko name i description; prompt systemowy to treść markdown pliku.

Pole	Wymagane	Opis
name	Tak	Unikalny identyfikator z małych liter i myślników
description	Tak	Kiedy agent powinien być wyzwalany (Claude czyta to, aby zdecydować)
tools	Nie	Lista dozwolonych narzędzi, których agent może używać. Domyślnie dziedziczy wszystkie narzędzia
disallowedTools	Nie	Narzędzia do jawnego zablokowania, usuwane z listy dziedziczonej lub dozwolonej
model	Nie	sonnet, opus, haiku, fable lub inherit (domyślnie inherit)
permissionMode	Nie	default, acceptEdits, dontAsk, bypassPermissions lub plan
skills	Nie	Skille do wstępnego załadowania do kontekstu agenta przy starcie
hooks	Nie	Hooki cyklu życia ograniczone do tego subagenta
memory	Nie	Zakres trwałej pamięci: user, project lub local

Pola prompt i maxTurns nie są kluczami frontmatter pliku — istnieją tylko w inline’owej formie JSON --agents pokazanej poniżej, gdzie prompt niesie prompt systemowy (ponieważ nie ma tam treści markdown).

Wskazówka

Kopiuj-wklej subagent dla automatycznego generowania testów:

Utwórz .claude/agents/test-writer.md:

---
description: "Generuje kompleksowe zestawy testów. Użyj, gdy nowy kod potrzebuje testów lub istniejące testy wymagają rozszerzenia."
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
model: sonnet
---

Jesteś specjalistą od testowania. Gdy poproszono o napisanie testów:

1. Przeczytaj plik źródłowy i zrozum jego publiczne API
2. Sprawdź istniejące testy pod kątem wzorców (framework testowy, styl asercji, podejście do mockowania)
3. Wygeneruj testy pokrywające:
   - Ścieżkę happy path dla każdej publicznej funkcji/metody
   - Przypadki brzegowe (puste wejścia, wartości null, warunki graniczne)
   - Przypadki błędów (nieprawidłowe wejścia, awarie sieci, timeouty)
   - Punkty integracji (wywołania bazy danych, wywołania API)
4. Przestrzegaj istniejących konwencji testowych w tym projekcie
5. Uruchom testy po ich napisaniu, aby zweryfikować, że przechodzą

Nigdy nie mockuj tego, co możesz przetestować bezpośrednio. Preferuj testy integracyjne nad testami jednostkowymi dla operacji bazodanowych.

Wyzwalanie subagentów

Subagenty wyzwalają się na dwa sposoby:

1. Automatycznie: Claude czyta pole description i decyduje, kiedy subagent byłby pomocny. Dobre opisy poprawiają automatyczne wyzwalanie.
2. Jawnie: Poproś Claude, aby „uruchomił agenta reviewer” lub „użył test-writer do dodania testów dla auth.ts”.

Wskazówka

Kopiuj-wklej prompt, aby jawnie wysłać subagenta:

Use the test-writer agent to add edge-case tests for src/auth/session.ts. Mirror the existing Vitest patterns in tests/auth/, cover token expiry and refresh-race conditions, and run the suite when you're done.

Nazwanie agenta i dokładnego pliku usuwa niejednoznaczność, więc Claude deleguje zamiast próbować wykonać pracę w głównej sesji.

Subagenty zdefiniowane w CLI

Dla tymczasowych lub eksperymentalnych agentów zdefiniuj je w linii poleceń:

claude --agents '{
  "performance": {
    "description": "Analyzes code for performance bottlenecks",
    "prompt": "You are a performance engineer. Profile and analyze code for bottlenecks. Focus on algorithmic complexity, memory allocation, and I/O patterns.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Budowanie biblioteki poleceń zespołowych

Organizowanie poleceń według przepływu pracy

.claude/
  commands/
    review.md            # /review        -- Ogólny przegląd kodu
    security-audit.md    # /security-audit -- Przegląd skupiony na bezpieczeństwie
    explain.md           # /explain        -- Wyjaśnienie kodu z kontekstem
    refactor.md          # /refactor       -- Przepływ pracy refaktoryzacji z przewodnikiem
    test/
      unit.md            # /test:unit        -- Generuj testy jednostkowe
      integration.md     # /test:integration -- Generuj testy integracyjne
      e2e.md             # /test:e2e         -- Generuj testy end-to-end
    deploy/
      checklist.md       # /deploy:checklist -- Weryfikacja przed wdrożeniem
      rollback.md        # /deploy:rollback  -- Asystent wycofania
  agents/
    reviewer.md          # Subagent przeglądu kodu
    test-writer.md       # Subagent generowania testów
    debugger.md          # Specjalista od debugowania

Podkatalog staje się prefiksem w przestrzeni nazw oddzielonym dwukropkiem, więc commands/test/unit.md wywołuje się jako /test:unit. Równoważny układ ze skillami umieszcza każdy przepływ pracy we własnym katalogu — .claude/skills/test-unit/SKILL.md — co daje pliki pomocnicze i automatyczne wywoływanie.

Dzielenie poleceń przez Git

Ponieważ .claude/commands/ i .claude/agents/ to zwykłe pliki w twoim repozytorium, są automatycznie współdzielone, gdy je commitujesz:

git add .claude/commands/ .claude/agents/
git commit -m "Add team review and test-writing commands"

Nowi członkowie zespołu otrzymują całą bibliotekę poleceń, gdy klonują repo.

Notatka

Polecenia osobiste w ~/.claude/commands/ nie są współdzielone. Używaj tego do osobistych skrótów produktywności, które odzwierciedlają twoje indywidualne preferencje przepływu pracy, a nie standardy zespołowe.

Gdy to się psuje

Subagent nie wyzwala się automatycznie: Popraw pole description. Claude potrzebuje jasnych wskazówek, kiedy używać każdego agenta. Dodaj frazy jak „Use proactively after code changes” lub „Triggers when testing is discussed”.

Polecenie jest za długie i zostaje obcięte: Claude Code ładuje pełny plik polecenia do kontekstu. Bardzo długie polecenia (więcej niż 500 linii) mogą wyprzeć inny ważny kontekst. Utrzymuj polecenia skoncentrowane i deleguj złożoną logikę do subagentów.

Agent dziedziczy zbyt wiele narzędzi: Domyślnie subagenty dziedziczą wszystkie narzędzia z sesji nadrzędnej. Jeśli twój agent nie powinien modyfikować plików, jawnie ogranicz jego narzędzia do ["Read", "Grep", "Glob", "Bash"].

Polecenia zespołowe kolidują z poleceniami osobistymi: Polecenia wywołuje się samą nazwą (/review), więc polecenie projektowe i polecenie osobiste o tej samej nazwie kolidują ze sobą. Wygrywa zakres o wyższym priorytecie: polecenie projektowe w .claude/commands/ nadpisuje osobiste w ~/.claude/commands/. Zwróć uwagę, że skille i polecenia dzielą tę samą przestrzeń nazw — jeśli skill i polecenie mają tę samą nazwę, pierwszeństwo ma skill, więc unikaj ponownego użycia nazwy skilla dla polecenia. Ta sama zasada pierwszeństwa projektu nad użytkownikiem dotyczy subagentów zdefiniowanych zarówno w .claude/agents/, jak i w ~/.claude/agents/.

Co dalej

• Hooks i automatyzacja — Połącz hooks z poleceniami dla w pełni zautomatyzowanych przepływów pracy
• System pamięci — Spraw, aby twoje polecenia były świadome kontekstu dzięki pamięci projektu
• Inżynieria promptów — Pisz lepsze prompty wewnątrz swoich niestandardowych poleceń