Niestandardowe Subagenty

Twoja główna sesja jest w 80 procentach zapełniona wyjściem testów, szumem z grepa i logami migracji, zanim napiszesz choć jedną linię właściwej poprawki. Przegląd, o który poprosiłeś, rywalizuje teraz o kontekst z błędem, który ścigasz, a Claude zaczyna zapominać ograniczenia, które ustaliłeś dziesięć minut temu. Niestandardowe subagenty rozwiązują to: każdy działa we własnym oknie kontekstu ze skoncentrowanym promptem systemowym i dokładnie tymi narzędziami, których potrzebuje, więc przegląd kodu, przebieg pisania testów czy audyt bezpieczeństwa nigdy nie zanieczyszczają rozmowy, w której robisz właściwą pracę.

Co zdobędziesz

• Działającego subagenta code-reviewer, test-writer i security-auditor, którego możesz wrzucić do dowolnego repozytorium
• Dokładne pola frontmatter, które kontrolują model subagenta, narzędzia i izolację
• Kopiuj-wklej prompty do jawnego wysyłania subagentów, gdy automatyczna delegacja nie zadziała
• Plan naprawczy dla trybów awarii, które naprawdę dają się we znaki w praktyce

Dlaczego używać niestandardowych subagentów?

Czysty kontekst

Każdy subagent ma własne okno kontekstu, zapobiegając zanieczyszczeniu głównej rozmowy

Specjalistyczna ekspertyza

Dostrojone prompty systemowe tworzą ekspertów domenowych dla konkretnych zadań

Automatyczna delegacja

Claude inteligentnie deleguje zadania na podstawie opisów i kontekstu

Izolacja bezpieczeństwa

Ogranicz dostęp do narzędzi per subagent dla zwiększonego bezpieczeństwa

Rozpoczęcie pracy

Tworzenie pierwszego subagenta

Uruchom komendę /agents w Claude Code, aby rozpocząć:

> /agents

Claude poprowadzi Cię przez tworzenie wyspecjalizowanych subagentów dostosowanych do Twoich potrzeb. Popularne sugestie to:

• Code Reviewer (Recenzent kodu)
• Test Writer (Twórca testów)
• Security Auditor (Audytor bezpieczeństwa)
• Documentation Generator (Generator dokumentacji)
• Performance Optimizer (Optymalizator wydajności)

Struktura katalogów

Subagenty są przechowywane jako pliki Markdown z metadanymi YAML:

• Folder.claude/

  • Folderagents/ # Subagenty specyficzne dla projektu

    • code-reviewer.md
    • test-writer.md
    • security-auditor.md
• Folder~/.claude/

  • Folderagents/ # Subagenty użytkownika (wszystkie projekty)

    • debugger.md
    • refactoring-expert.md

Wskazówka

Subagenty na poziomie projektu (.claude/agents/) mają pierwszeństwo przed tymi na poziomie użytkownika, gdy nazwy się konfliktują. Pozwala to zespołom nadpisywać osobiste subagenty wersjami specyficznymi dla projektu.

Subagenty w Agent View

Od Claude Code v2.1.139 możesz uruchomić subagent jako głównego agenta sesji w tle i zarządzać nim z dashboardu claude agents:

# Z shella — uruchom code-reviewer jako sesję w tle
claude --agent code-reviewer --bg "address review comments on PR 1234"

Z wnętrza agent view możesz uruchamiać w ten sam sposób bez opuszczania dashboardu:

Input w prompcie dispatcha	Co się dzieje
code-reviewer <prompt>	Dopasowanie pierwszego słowa — uruchamia code-reviewer jako głównego agenta sesji
@agent-code-reviewer <prompt>	Forma wzmianki — wpisz @ i wybierz z podpowiedzi (typowa droga) lub wpisz @agent-<name> ręcznie
@<repo> <prompt>	Wzmianka o repo siostrzanym, aby uruchomić sesję tam
/<command> <prompt>	Podpowiada skille i polecenia do uruchomienia jako prompt

Pole frontmatter do izolacji worktree. Subagent może wymusić uruchamianie zawsze we własnym git worktree, niezależnie od sposobu dispatcha:

---
name: large-refactor
description: Multi-file refactors that should never share a working tree
isolation: worktree
---

Jest to szczególnie wartościowe, gdy rozprowadzasz ten sam subagent na wiele równoległych sesji — każda dostaje własny checkout pod .claude/worktrees/, więc nie mogą deptać sobie po edycjach.

Konfiguracja subagenta

Struktura pliku

Każdy subagent jest zdefiniowany w pliku Markdown z metadanymi YAML:

---
name: code-reviewer
description: Expert code review specialist. Reviews code for quality, security, and maintainability. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

Jesteś ekspertem w recenzowaniu kodu z 15-letnim doświadczeniem w wielu językach i frameworkach.

## Twoje obowiązki:
1. Recenzuj kod pod kątem błędów, luk bezpieczeństwa i problemów z wydajnością
2. Upewnij się, że kod przestrzega ustalonych wzorców i konwencji
3. Sugeruj ulepszenia dla czytelności i utrzymywalności
4. Weryfikuj pokrycie testami dla nowej funkcjonalności

## Proces recenzji:
- Najpierw zrozum kontekst i cel zmian
- Sprawdź typowe problemy (sprawdzanie null, obsługa błędów, przypadki brzegowe)
- Oceń strukturę kodu i wzorce projektowe
- Oceń implikacje bezpieczeństwa
- Zasugeruj konkretne, wykonalne ulepszenia

Zawsze udzielaj konstruktywnej informacji zwrotnej z przykładami kodu, gdy to możliwe.

Opcje konfiguracji

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 Claude powinien delegować do tego subagenta
tools	Nie	Lista dozwolonych narzędzi oddzielona przecinkami (dziedziczy wszystkie jeśli pominięte)
disallowedTools	Nie	Narzędzia do 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 subagenta przy starcie
hooks	Nie	Hooki cyklu życia ograniczone do tego subagenta
memory	Nie	Zakres trwałej pamięci: user, project lub local

Przykłady z rzeczywistego świata

Specjalista od recenzji kodu

---
name: code-reviewer
description: Comprehensive code review for quality, security, and best practices. MUST BE USED after implementing features.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer focused on maintaining high code quality.

## Review Checklist:
- **Security**: Check for SQL injection, XSS, authentication bypasses
- **Performance**: Identify N+1 queries, unnecessary loops, memory leaks
- **Error Handling**: Verify all edge cases are covered
- **Code Style**: Ensure consistency with project conventions
- **Testing**: Confirm adequate test coverage exists

When reviewing, always:
1. Start with a high-level assessment
2. Identify critical issues first
3. Provide specific fix suggestions with code examples
4. Acknowledge what was done well

Format your review as:
## Summary
Brief overview of changes and overall quality

## Critical Issues
Must-fix problems before merging

## Suggestions
Nice-to-have improvements

## Commendations
What was done particularly well

Ekspert generowania testów

---
name: test-writer
description: Specialized in writing comprehensive test suites. Use when implementing new features or fixing bugs.
tools: Read, Write, Edit, Bash, Grep
---

You are a test automation expert who writes thorough, maintainable test suites.

## Testing Philosophy:
- Test behavior, not implementation
- Each test should have a single clear purpose
- Use descriptive test names that explain the scenario
- Follow AAA pattern: Arrange, Act, Assert

## Coverage Requirements:
1. Happy path scenarios
2. Edge cases and boundary conditions
3. Error handling and failure modes
4. Integration points
5. Performance considerations

## Best Practices:
- Use appropriate test doubles (mocks, stubs, spies)
- Keep tests independent and idempotent
- Minimize test data setup
- Use data-driven tests for multiple scenarios
- Include both unit and integration tests

Always check existing test patterns in the codebase before writing new tests.

Audytor bezpieczeństwa

---
name: security-auditor
description: Security vulnerability scanner and remediation expert. Use PROACTIVELY on authentication, authorization, and data handling code.
tools: Read, Grep, Glob
---

You are a security specialist conducting thorough vulnerability assessments.

## Security Checklist:

### Authentication & Authorization
- Verify proper authentication checks
- Validate authorization for all endpoints
- Check for privilege escalation paths
- Review session management

### Input Validation
- SQL injection prevention
- XSS protection
- Command injection safeguards
- Path traversal prevention
- File upload validation

### Data Protection
- Sensitive data encryption
- Secure password storage
- PII handling compliance
- Secure communication (HTTPS/TLS)

### Security Headers & Configuration
- CORS configuration
- CSP headers
- Rate limiting
- Security headers (HSTS, X-Frame-Options, etc.)

For each issue found:
1. Explain the vulnerability
2. Demonstrate potential exploit (safely)
3. Provide specific remediation code
4. Reference OWASP guidelines where applicable

Specjalista migracji baz danych

---
name: db-migration-expert
description: Database schema migration and optimization specialist. Use for schema changes, migrations, and query optimization.
tools: Read, Write, Bash, Grep
---

You are a database expert specializing in migrations and schema design.

## Migration Principles:
- All migrations must be reversible
- Never destructive operations without backups
- Test migrations on copy of production data
- Consider zero-downtime deployment requirements

## Migration Process:
1. Analyze current schema and requirements
2. Design migration with rollback plan
3. Consider data volume and performance impact
4. Write up and down migrations
5. Include data transformation if needed
6. Add appropriate indexes

## Optimization Focus:
- Query performance analysis
- Index strategy
- Denormalization decisions
- Partitioning strategies
- Connection pooling configuration

Always consider:
- Database-specific features and limitations
- Impact on existing queries
- Application deployment coordination
- Data integrity constraints

Zaawansowane wzorce

Strategie delegacji

Spraw, aby Twoje subagenty były częściej używane dzięki strategicznym opisom:

---
name: performance-optimizer
description: Performance optimization expert. MUST BE USED when users mention slow, performance, optimization, or speed issues.
---

Kluczowe frazy zachęcające do automatycznej delegacji:

• "Use PROACTIVELY"
• "MUST BE USED"
• "ALWAYS USE when"
• Konkretne słowa wyzwalające w opisie

Wzorce ograniczania narzędzi

Ogranicz możliwości subagenta dla bezpieczeństwa:

Read-Only Analyst

---
name: code-analyst
description: Analyzes codebase structure and patterns
tools: Read, Grep, Glob  # No write access
---

Test Runner

---
name: test-runner
description: Executes tests and reports results
tools: Bash, Read  # Can run tests but not modify code
---

Documentation Writer

---
name: doc-writer
description: Creates and updates documentation
tools: Read, Write, Edit  # No execution capabilities
---

Kompozycja subagentów

Twórz wyspecjalizowane zespoły subagentów współpracujących ze sobą:

# Faza planowania
> Use the architect subagent to design the authentication system

# Faza implementacji
> Use the backend-developer subagent to implement the design

# Faza recenzji
> Use the code-reviewer subagent to review the implementation

# Faza testowania
> Use the test-writer subagent to create comprehensive tests

# Faza bezpieczeństwa
> Use the security-auditor subagent to check for vulnerabilities

Kopiuj-wklej prompty

Automatyczna delegacja jest wygodna, ale w momencie, gdy najbardziej się liczy — tuż przed scaleniem — chcesz uruchomić subagenta jawnie, aby właściwy specjalista zadziałał na właściwych plikach. Nazwij subagenta i dokładne ścieżki; niejasne prośby zostaną obsłużone w głównej sesji zamiast oddelegowane.

Wskazówka

Uruchom code-reviewer na ostatnich zmianach i zablokuj na sekretach:

Use the code-reviewer subagent to review my last 3 commits (git diff HEAD~3). Block the review with REQUEST_CHANGES if you find any exposed secret, hardcoded credential, or unparameterized SQL. Reference exact file paths and line ranges for every finding.

Wskazówka

Uruchom test-writer na konkretnym module:

Use the test-writer subagent to add edge-case tests for src/payments/refund.ts. Mirror the existing Vitest patterns in tests/payments/, cover partial refunds, double-refund attempts, and currency-mismatch errors, then run the suite and report failures.

Wskazówka

Uruchom security-auditor przed wysłaniem zmiany w uwierzytelnianiu:

Use the security-auditor subagent on src/auth/ and src/middleware/session.ts. Focus on authorization bypasses, privilege escalation, and session fixation. For each issue, give the vulnerability, an exploit sketch, and a concrete patch with the OWASP reference.

Najlepsze praktyki

1. Zacznij od agentów generowanych przez Claude Pozwól Claude stworzyć początkowe subagenty używając /agents, następnie dostosuj je do swoich konkretnych potrzeb.

2. Utrzymuj subagenty skoncentrowane Każdy subagent powinien doskonale wykonywać jeden konkretny typ zadania. Unikaj tworzenia subagentów „szwajcarskich scyzoryków”.

3. Używaj opisowych nazw i opisów Jasne nazewnictwo pomaga Claude automatycznie wybrać właściwego subagenta dla każdego zadania.

4. Kontrola wersji subagentów projektu Dodaj .claude/agents/ do Git, aby dzielić się subagentami z zespołem.

5. Iteruj na podstawie wydajności Monitoruj jak działają subagenty i udoskonalaj ich prompty na podstawie wyników.

6. Dokumentuj możliwości subagenta Uwzględnij jasną dokumentację w prompcie systemowym o tym, co subagent może i czego nie może robić.

Jak zespoły używają subagentów

Wyspecjalizowane subagenty zwykle zarabiają na siebie w kilku powracających miejscach:

• Dedykowany subagent przeglądu, który uruchamia się przed każdym scaleniem, tak aby świeży kontekst sprawdzał diff pod kątem ujawnionych sekretów i niesparametryzowanego SQL, zamiast tej sesji, która właśnie napisała kod.
• Security-auditor podpięty do ścieżek uwierzytelniania i obsługi danych przez „Use PROACTIVELY”, wychwytujący luki autoryzacji, które ogólny przegląd przemyka.
• Test-writer, który najpierw czyta istniejące konwencje testów, tak aby nowe zestawy pasowały do frameworka i stylu asercji projektu, zamiast wymyślać własne.

Przykład integracji przepływu pracy

Typowy przepływ pracy deweloperskiej z subagentami:

# 1. Zacznij od wymagań
> Create a user authentication system with OAuth support

# 2. Claude automatycznie używa subagenta architect do projektowania

# 3. Implementacja ze specjalistycznymi subagentami
> Implement the authentication endpoints

# 4. Automatyczna recenzja kodu
# (subagent code-reviewer wyzwolony przez "MUST BE USED after implementing features")

# 5. Generowanie testów
> Create comprehensive tests for the auth system

# 6. Audyt bezpieczeństwa
# (security-auditor wyzwolony przez "PROACTIVELY on authentication")

Znajdowanie i udostępnianie subagentów

Nie musisz tworzyć każdego subagenta od zera. Pluginy dostarczają gotowe subagenty, które po zainstalowaniu pojawiają się w /agents obok Twoich własnych. Przeglądaj je i instaluj z marketplace pluginów, a następnie dostosuj prompty systemowe do konwencji Twojego projektu.

Notatka

Aby dzielić się własnymi subagentami z kolegami z zespołu, nie potrzebujesz osobnego repozytorium — zacommituj .claude/agents/ do repozytorium Git swojego projektu i każdy, kto je sklonuje, dostanie tych samych specjalistów. Aby dystrybuować szerzej, spakuj je jako plugin (zobacz repozytorium Claude Code).

Gdy to się psuje

Subagent nigdy nie jest wybierany automatycznie. Claude deleguje na podstawie pola description, więc niejasny opis oznacza, że pozostaje w głównej sesji. Dodaj jednoznaczne frazy wyzwalające („Use PROACTIVELY after code changes”, „MUST BE USED”), nazwij warunki, a — gdy nadal nie zadziała — uruchom ręcznie: Use the code-reviewer subagent to .... Jawne wywołanie zawsze wygrywa z automatyczną delegacją.

Subagent nie może wykonać swojej pracy. Jeśli zgłasza, że brakuje mu narzędzia Edit lub Bash, Twoja lista tools jest zbyt ciasna. Albo rozszerz listę dozwolonych, albo przełącz się na disallowedTools, aby zablokować tylko to, co niebezpieczne (na przykład zablokuj Bash u analityka tylko do odczytu, ale zachowaj resztę). Recenzent z narzędziami tylko do odczytu z założenia nie może wprowadzać poprawek — tak ma być, to nie błąd.

Równoległe subagenty depczą sobie po edycjach. Gdy rozprowadzasz ten sam subagent na kilka sesji, domyślnie dzielą jedno working tree. Dodaj isolation: worktree do frontmatter, aby każde uruchomienie dostało własny checkout pod .claude/worktrees/, a potem pogódź gałęzie.

Opóźnienie i koszt tokenów skaczą. Każdy subagent na nowo zbiera kontekst (często 2-3 sekundy, zanim zacznie), a każde uruchomienie zużywa świeże okno kontekstu. Kieruj tanią, wysokowolumenową pracę (sprawdzenia formatowania, triage lintera) do model: haiku, a opus rezerwuj na przeglądy i refaktoryzacje, gdzie liczy się osąd. Jeśli budżet jest mniej istotny niż tempo i jakość wyników, model: fable jest wart rozważenia przy najtrudniejszych refaktoryzacjach, budowaniu od zera i długich zadaniach — subagenty do rutynowej pracy mogą nadal używać inherit (Opus 4.8) lub haiku, więc koszty pozostają pod kontrolą. Szczegóły cenowe znajdziesz w porównaniu modeli.

Uwaga

Subagent otrzymuje tylko własny prompt systemowy plus podstawowe szczegóły środowiska — nie dziedziczy kontekstu, pamięci ani załadowanych skilli z Twojej głównej rozmowy. Jeśli subagent potrzebuje konwencji projektu, podaj je w jego prompcie systemowym lub wczytaj wstępnie przez pole skills we frontmatter. Nie zakładaj, że „pamięta” to, co powiedziałeś głównej sesji.

Następne kroki

Niestandardowe subagenty przekształcają Claude Code z pojedynczego asystenta w zespół specjalistów, każdego z własnym kontekstem i narzędziami. Stąd:

• Agent View — uruchamiaj subagenty jako sesje w tle i zarządzaj nimi z dashboardu claude agents
• Tworzenie poleceń niestandardowych — połącz subagenty z poleceniami slash, tak aby pojedyncze /review wyzwalało cały przepływ pracy
• Hooks i automatyzacja — uruchamiaj subagenty automatycznie przy zdarzeniach cyklu życia, zamiast czekać na delegację