Tworzenie poleceń niestandardowych

Polecenia niestandardowe są kamieniem węgielnym automatyzacji przepływów pracy w Claude Code. Poprzez enkapsulację skomplikowanych zadań w wielokrotnego użytku polecenia, przekształcasz powtarzalną pracę w instrukcje jednoliniowe, które każdy członek zespołu może wykonać.

Dlaczego polecenia niestandardowe?

Spójność

Zapewnij, że wszyscy postępują zgodnie z tymi samymi przepływami pracy i najlepszymi praktykami

Efektywność

Przekształć wieloetapowe procesy w natychmiastowe polecenia

Dzielenie się wiedzą

Uchwycić ekspertyzę w poleceń można udostępnić i wersjonować

Wdrażanie

Nowi członkowie zespołu stają się produktywni natychmiast

Podstawy poleceń

Struktura katalogów

Polecenia znajdują się w określonych katalogach w zależności od ich zakresu:

• Folder.claude/

  • Foldercommands/ # Specyficzne dla projektu (udostępniane przez Git)

    • deploy.md # /deploy lub /project:deploy
    • test.md # /test lub /project:test
    • Folderbackend/

      • migrate.md # /backend:migrate
• Folder~/.claude/

  • Foldercommands/ # Osobiste (wszystkie projekty)

    • review.md # /review lub /user:review
    • format.md # /format lub /user:format

Anatomia polecenia

Każde polecenie to plik Markdown z opcjonalnym frontmatter YAML:

---
# Opcjonalny frontmatter
allowed-tools: Edit, Bash(npm:*), Read
description: Wdróż aplikację na staging
argument-hint: [environment] [--skip-tests]
---

# Tytuł polecenia

Twoja treść promptu tutaj, z placeholderem $ARGUMENTS
dla dynamicznego wprowadzania.

## Opcjonalne sekcje
- Wymagania
- Kroki
- Kontekst

Tworzenie pierwszego polecenia

1. Zidentyfikuj powtarzalne zadanie Pomyśl o tym, co robisz kilka razy dziennie

2. Utwórz plik polecenia

   mkdir -p .claude/commands
   touch .claude/commands/pr-review.md

3. Napisz polecenie

   # Przejrzyj PR dla: $ARGUMENTS
   
   Proszę przejrzyj zmiany i podaj opinię na temat:
   1. Jakości kodu i najlepszych praktyk
   2. Potencjalnych błędów lub przypadków skrajnych
   3. Implikacji wydajnościowych
   4. Problemów bezpieczeństwa
   5. Pokrycia testami
   
   Skup się na konstruktywnej opinii, nie na kwestiach stylistycznych.

4. Przetestuj polecenie

   /pr-review moduł uwierzytelniania

Zaawansowane wzorce poleceń

Dynamiczne ładowanie kontekstu

Ładuj kontekst dynamicznie używając wykonywania bash:

---
allowed-tools: Bash(git:*), Read, Edit
description: Inteligentny commit z kontekstem
---

# Utwórz commit

## Aktualny status
- Gałąź: !`git branch --show-current`
- Zmienione pliki: !`git status --short`
- Ostatni commit: !`git log -1 --oneline`

## Zmiany w stage
!`git diff --cached`

## Zadanie
Utwórz opisową wiadomość commit dla tych zmian.
Rozważ: $ARGUMENTS

Postępuj zgodnie z formatem conventional commit:
- feat: nowa funkcja
- fix: naprawa błędu
- docs: dokumentacja
- refactor: restrukturyzacja kodu
- test: dodawanie testów
- chore: utrzymanie

Przepływy pracy wieloetapowe

Utwórz polecenia organizujące złożone procesy:

---
allowed-tools: Bash(npm:*), Edit, MultiEdit, Task
description: Kompletny przepływ pracy implementacji funkcji
argument-hint: nazwa-funkcji
---

# Zaimplementuj funkcję: $ARGUMENTS

Wykonaj ten kompletny przepływ pracy:

## 1. Konfiguracja
- Utwórz gałąź funkcji: `feature/$ARGUMENTS`
- Zaktualizuj zależności jeśli potrzeba

## 2. Implementacja
- Przejrzyj wymagania w @docs/features/$ARGUMENTS.md
- Implementuj zgodnie z naszymi wzorcami w @src/patterns.md
- Upewnij się, że typy TypeScript są właściwie zdefiniowane

## 3. Testowanie
- Napisz testy jednostkowe osiągając >80% pokrycia
- Dodaj testy integracyjne dla endpointów API
- Uwzględnij przypadki skrajne i scenariusze błędów

## 4. Dokumentacja
- Zaktualizuj dokumentację API
- Dodaj komentarze JSDoc
- Utwórz przykłady użycia

## 5. Finalizacja
- Uruchom pełny zestaw testów
- Upewnij się, że linting przechodzi
- Utwórz PR ze szczegółowym opisem

Zatrzymaj się i powiadom mnie, jeśli którykolwiek krok się nie powiedzie.

Logika warunkowa

Buduj inteligentne polecenia dostosowujące się do kontekstu:

Wykrywanie języka

---
allowed-tools: Read, Edit
description: Dodaj komentarze nagłówkowe na podstawie typu pliku
---

# Dodaj nagłówki plików

## Wykryj typ pliku
Plik: $ARGUMENTS
Rozszerzenie: !`echo "$ARGUMENTS" | rev | cut -d'.' -f1 | rev`

## Zastosuj odpowiedni nagłówek

Na podstawie rozszerzenia powyżej:
- Jeśli .js/.ts: Dodaj nagłówek JSDoc z @module
- Jeśli .py: Dodaj docstring z opisem modułu
- Jeśli .sh: Dodaj shebang i dokumentację użycia
- Jeśli .md: Dodaj frontmatter z tytułem i datą
- W przeciwnym razie: Dodaj odpowiedni styl komentarza

Uwzględnij:
- Opis przeznaczenia
- Autor: !`git config user.name`
- Data: !`date +%Y-%m-%d`
- Licencja: MIT

Świadomy środowiska

---
allowed-tools: Bash(echo:*), Bash(kubectl:*), Bash(docker:*)
description: Wdróż do wykrytego środowiska
---

# Inteligentne wdrożenie

## Wykryj środowisko
- Gałąź Git: !`git branch --show-current`
- Kontekst K8s: !`kubectl config current-context 2>/dev/null || echo "brak"`
- Status Docker: !`docker info &>/dev/null && echo "działa" || echo "nie działa"`

## Strategia wdrożenia

Na podstawie wykrywania:
- Jeśli gałąź zawiera "prod": Potwierdź przed wdrożeniem produkcyjnym
- Jeśli k8s dostępne: Użyj wdrożenia kubectl
- Jeśli tylko docker: Użyj docker-compose
- W przeciwnym razie: Użyj lokalnego serwera deweloperskiego

Cel: ${ARGUMENTS:-automatyczne wykrywanie}

Kontynuuj z odpowiednią strategią wdrożenia.

Generatory szablonów

Utwórz polecenia generujące kod boilerplate:

---
allowed-tools: Write, MultiEdit
description: Generuj komponent React z testami
argument-hint: NazwaKomponentu [--hooks] [--typescript]
---

# Generuj komponent React: $ARGUMENTS

Przetwórz argumenty aby wydobyć:
- Nazwę komponentu (PascalCase)
- Czy używać hooks (flaga --hooks)
- Czy używać TypeScript (flaga --typescript)

Wygeneruj:

1. Plik komponentu w `src/components/{NazwaKomponentu}/index.{tsx|jsx}`
2. Plik testowy w `src/components/{NazwaKomponentu}/__tests__/index.test.{tsx|jsx}`
3. Plik Storybook w `src/components/{NazwaKomponentu}/index.stories.{tsx|jsx}`
4. Style w `src/components/{NazwaKomponentu}/styles.module.css`

Postępuj zgodnie z wzorcami z istniejących komponentów w @src/components/Button

Najlepsze praktyki rozwoju poleceń

Konwencje nazewnictwa

Jasne i wykonalne

✅ /deploy-staging ✅ /fix-formatting ❌ /process ❌ /handle

Spójne wzorce

• Akcje: czasownik-rzeczownik
• Zapytania: get-rzeczownik
• Generatory: create-rzeczownik
• Przepływy pracy: nazwa-przepływu

Obsługa argumentów

# Solidne parsowanie argumentów

Przetwórz argumenty: $ARGUMENTS

Oczekiwany format: [akcja] [cel] [--flagi]
- Akcja: ${1:-domyślna-akcja}
- Cel: ${2:-wszystkie}
- Flagi: Wydobądź wszelkie wzorce --flaga

Waliduj:
- Akcja musi być: create|update|delete
- Cel musi istnieć w projekcie
- Flagi są opcjonalne

Obsługa błędów

Buduj odporne polecenia:

---
allowed-tools: Bash(test:*), Task
---

# Bezpieczne wdrożenie

## Kontrole przedstartowe
- Testy przechodzą: !`npm test &>/dev/null && echo "✓" || echo "✗"`
- Brak niezacommitowanych zmian: !`[[ -z $(git status --porcelain) ]] && echo "✓" || echo "✗"`
- Prawidłowe środowisko: !`[[ -f .env.$ARGUMENTS ]] && echo "✓" || echo "✗"`

## Decyzja
Jeśli którakolwiek kontrola pokazuje ✗:
- Zgłoś które kontrole nie powiodły się
- Zasugeruj poprawki
- NIE kontynuuj z wdrożeniem

W przeciwnym razie, kontynuuj z wdrożeniem do $ARGUMENTS

Techniki dla zaawansowanych użytkowników

Kompozycja poleceń

Łącz polecenia dla złożonych przepływów pracy:

# Organizuj wiele poleceń

Proszę wykonaj te polecenia w sekwencji:

1. Uruchom testy: `/test:unit --coverage`
2. Jeśli przechodzą, zaktualizuj dokumenty: `/generate:docs`
3. Utwórz wydanie: `/release:prepare $ARGUMENTS`
4. Wdróż: `/deploy:staging`

Przerwij przy każdym błędzie.

Dynamiczne generowanie poleceń

---
allowed-tools: Write
description: Generuj niestandardowe polecenie z opisu
---

# Generator poleceń

Na podstawie tego opisu: $ARGUMENTS

1. Przeanalizuj co polecenie powinno robić
2. Określ wymagane narzędzia
3. Utwórz plik polecenia z:
   - Odpowiednim frontmatter
   - Jasnym opisem
   - Solidną implementacją
   - Obsługą błędów

Zapisz do: .claude/commands/generated/[odpowiednia-nazwa].md

Polecenia międzyrepozytoriowe

---
allowed-tools: Bash(git:*), Task
description: Zastosuj zmiany w wielu repozytoriach
---

# Aktualizacja wielu repozytoriów: $ARGUMENTS

## Repozytoria
!`cat ~/.claude/team-repos.txt`

Dla każdego repozytorium powyżej:
1. Sklonuj jeśli nie istnieje
2. Utwórz gałąź: `chore/$ARGUMENTS`
3. Zastosuj określoną zmianę
4. Commituj ze standardową wiadomością
5. Wypchnij i utwórz PR

Użyj Task dla równoległego wykonywania gdzie to możliwe.

Przykłady biblioteki poleceń

Polecenia przepływu pracy deweloperskiej

• Folder.claude/commands/

  • Folderdev/

    • start.md # Uruchom środowisko dev
    • stop.md # Eleganckie zamknięcie
    • reset.md # Reset do czystego stanu
    • seed.md # Wypełnij danymi testowymi

Polecenia testowe

.claude/commands/test/smart.md

---
allowed-tools: Bash(npm:*), Read
description: Inteligentnie uruchom odpowiednie testy
---

# Inteligentny runner testów

## Przeanalizuj zmiany
- Zmodyfikowane pliki: !`git diff --name-only`
- Typy plików: !`git diff --name-only | sed 's/.*\.//' | sort -u`

## Strategia testowa

Na podstawie zmian:
- Jeśli *.test.* zmodyfikowane: Uruchom te konkretne testy
- Jeśli pliki źródłowe: Znajdź i uruchom odpowiadające testy
- Jeśli pliki konfiguracyjne: Uruchom wszystkie testy
- Jeśli brak zmian: Uruchom testy dla $ARGUMENTS

Uwzględnij:
- Raport pokrycia
- Metryki wydajności
- Analizę błędów z sugestiami napraw

Polecenia dokumentacji

.claude/commands/docs/api.md

---
allowed-tools: Read, Write, Bash(npm:*)
description: Generuj dokumentację API
---

# Generuj dokumentację API

Cel: ${ARGUMENTS:-wszystkie endpointy}

1. Przeskanuj endpointy API w @src/api/
2. Wydobądź:
   - Definicje ścieżek
   - Typy request/response
   - Wymagania uwierzytelniania
   - Limity szybkości

3. Wygeneruj specyfikację OpenAPI
4. Utwórz dokumentację Markdown
5. Zaktualizuj kolekcję Postman
6. Zweryfikuj działanie przykładów

Wyjście do: docs/api/

Udostępnianie poleceń

Współpraca zespołowa

Wskazówka

Sprawdź swoje .claude/commands/ w kontroli wersji, aby natychmiast udostępnić przepływy pracy całemu zespołowi.

# Udostępnij polecenia zespołowe
git add .claude/commands/
git commit -m "Dodaj polecenia przepływu pracy zespołu"
git push

# Członkowie zespołu otrzymują je automatycznie
git pull
/help  # Nowe polecenia się pojawiają!

Dokumentacja poleceń

Utwórz indeks poleceń:

.claude/commands/README.md

# Polecenia Claude zespołu

## Rozwój
- `/dev:start` - Uruchom środowisko deweloperskie
- `/dev:reset` - Reset bazy danych i cache

## Testowanie
- `/test:smart` - Uruchom odpowiednie testy
- `/test:e2e` - Uruchom zestaw end-to-end

## Wdrożenie
- `/deploy:staging` - Wdróż na staging
- `/deploy:rollback` - Cofnij ostatnie wdrożenie

## Narzędzia
- `/lint:fix` - Napraw wszystkie problemy lintingu
- `/deps:update` - Bezpiecznie zaktualizuj zależności

Względy bezpieczeństwa

Uwaga

Polecenia mają dostęp do wszystkich dozwolonych narzędzi. Przejrzyj polecenia z zewnętrznych źródeł przed ich uruchomieniem.

Bezpieczne praktyki poleceń

1. Ogranicz uprawnienia narzędzi w frontmatter
2. Waliduj dane wejściowe przed użyciem w poleceniach
3. Unikaj wykonywania arbitralnych danych użytkownika
4. Używaj narzędzi tylko do odczytu gdy to możliwe
5. Dokumentuj ryzyko w opisie polecenia

Przykład: Bezpieczne polecenie

---
# Jawnie ogranicz narzędzia
allowed-tools: Read, Bash(ls:*), Bash(grep:*)
description: Szukaj wzorców (tylko odczyt)
---

# Bezpieczne wyszukiwanie: $ARGUMENTS

Szukaj wzorca tylko w dozwolonych katalogach:
- src/
- docs/
- tests/

NIE szukaj w:
- plikach .env
- .git/
- node_modules/
- Żadnym pliku zawierającym 'secret' lub 'key'

Użyj grep z wzorcami --exclude dla bezpieczeństwa.

Następne kroki

Wzbogać swoje polecenia niestandardowe o:

1. Integracja hooks - Wyzwalaj polecenia automatycznie
2. Zarządzanie pamięcią - Spraw, by polecenia były świadome kontekstu
3. Serwery MCP - Rozszerz polecenia o zewnętrzne narzędzia

Porada profesjonalisty

Zacznij od prostych poleceń dla najczęstszych zadań. W miarę identyfikowania wzorców, refaktoryzuj je w bardziej zaawansowane polecenia. Najlepsze polecenia wyłaniają się z rzeczywistych potrzeb przepływu pracy.