Polecenia, umiejętności, subagenty, reguły: czego nauczyłem się organizując 139 rozszerzeń

Po zbudowaniu 95 hooków, 44 umiejętności, 85 poleceń i 11 plików reguł dla Claude Code nauczyłem się, że wybór niewłaściwej abstrakcji marnuje więcej czasu niż zbudowanie niewłaściwej funkcji. Umiejętność, która powinna była być regułą, rozdęła mój kontekst o 40%. Polecenie, które powinno było być umiejętnością, wymagało ode mnie pamiętania, by wpisywać /fastapi za każdym razem, gdy pracowałem z endpointem API.¹

Podsumowanie

Claude Code oferuje cztery sposoby rozszerzania zachowania: polecenia (prompty wywoływane przez użytkownika), umiejętności (automatycznie wstrzykiwany kontekst), subagenty (delegowane jednostki wykonujące zadania) oraz reguły (stale aktywne ograniczenia). Po uporządkowaniu 139 rozszerzeń odkryłem, że schemat decyzyjny jest prosty: reguły dla niezmienników, umiejętności dla wiedzy domenowej, polecenia dla przepływów pracy, subagenty dla izolacji. Najtrudniejsze jest rozpoznanie, że dokonało się złego wyboru, i przeprowadzenie migracji.

Cztery abstrakcje (z prawdziwymi przykładami)

Polecenia: „/commit” i 84 inne

Polecenia aktywują się, gdy wpisuję /nazwa-polecenia. Każde rozwija się w szablon promptu.²

Moje 85 poleceń obejmuje /commit (inteligentny commit Git), /review (uruchomienie agentów przeglądu kodu), /deploy (lista kontrolna wdrożenia), /publish-check (walidacja przed publikacją bloga) oraz /deliberate (wieloagentowe badania).

Błąd, który popełniłem: Zbudowałem /fastapi jako polecenie wstrzykujące wzorce FastAPI na żądanie. Problem: w połowie przypadków zapominałem je wpisać. Każde pominięte wywołanie oznaczało, że agent pomijał wzorce, których chciałem przestrzegać. Rozwiązaniem była migracja /fastapi do umiejętności z automatyczną aktywacją.

Umiejętności: 44 automatycznie aktywowane moduły wiedzy

Umiejętności aktywują się automatycznie, gdy rozmowa pasuje do opisu danej umiejętności. Nie wpisuję żadnego polecenia — system wstrzykuje odpowiednią wiedzę ekspercką na podstawie kontekstu.³

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

Moje 44 umiejętności obejmują: - Wiedza domenowa (8): FastAPI, SwiftUI, HTMX/Alpine, bazy danych, testowanie, debugowanie, architektura, bezpieczeństwo - Infrastruktura bloga (7): blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - Filozofia/jakość (5): Shokunin (Jiro), No Shortcuts, esencja Rubina, zasady projektowania - Wieloagentowe (3): deliberacja, przegląd, tworzenie treści - Specyficzne dla projektu (4): treści strony osobistej, blog ResumeGeni, przechwytywanie Obsidian

Incydent z 40% rozdęciem kontekstu: Na początku umieściłem pełny przewodnik po wzorcach FastAPI (800 linii) w pliku reguł. Reguły ładują się w każdej sesji. Gdy pracowałem nad aplikacjami iOS, CSS lub treściami bloga, 800 linii nieistotnych wzorców FastAPI pochłaniało tokeny kontekstu. Przeniesienie treści do umiejętności z opisem „FastAPI backend development” rozwiązało problem — umiejętność ładowała się wyłącznie podczas pracy z API.⁴

Subagenty: izolowani recenzenci

Subagenty działają we własnym oknie kontekstowym z ograniczonym dostępem do narzędzi i niezależnymi uprawnieniami.⁵

Moje subagenty obejmują security-reviewer (dostęp tylko do odczytu, skanowanie podatności OWASP), test-runner (uruchamianie testów, analiza błędów) oraz conventions-reviewer (sprawdzanie standardów projektu).

Dlaczego izolacja ma znaczenie: Podczas przeglądu kodu recenzent nie powinien mieć możliwości edycji plików. Umiejętność może wstrzyknąć wiedzę o przeglądach, ale sam przegląd nadal odbywa się w głównym kontekście z pełnymi uprawnieniami do zapisu. Subagent wymusza dostęp tylko do odczytu na poziomie architektonicznym.

Reguły: 11 stale aktywnych plików ograniczeń

Reguły ładują się automatycznie w każdej rozmowie. Moje 11 plików reguł obejmuje:⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

Lekcja o rozmiarze: Moje reguły to łącznie około 180 linii w 11 plikach. Każda linia ładuje się w każdej sesji. Pierwotnie miałem ponad 400 linii, zanim przeniosłem treści specyficzne dla danego tematu do umiejętności. Zestaw 180 linii reguł obejmuje prawdziwe niezmienniki (ograniczenia bezpieczeństwa, przepływ pracy Git, korekty). Wszystko inne należy do umiejętności.

Schemat decyzyjny

Wzorzec migracji

Moja struktura .claude/ ewoluowała przez trzy fazy:

Faza 1 (miesiąc 1-2): Wszystko w regułach. Ponad 400 linii stale ładowanego kontekstu. Wzorce iOS, wzorce FastAPI, wytyczne projektowe, standardy testowania. Kontekst był rozdęty w każdej sesji.

Faza 2 (miesiąc 3-4): Migracja treści specyficznych dla tematu do umiejętności. Reguły zmniejszyły się do 200 linii. Umiejętności rozrosły się do ponad 20 katalogów. Rozdęcie kontekstu spadło o 40%.

Faza 3 (miesiąc 5+): Dodanie subagentów dla zadań wymagających izolacji (przegląd kodu, audyt bezpieczeństwa). Polecenia ustabilizowały się na 85 dla jawnych przepływów pracy. Umiejętności wzrosły do 44 w miarę dodawania wiedzy domenowej.⁷

Wniosek: zacznij od reguł (tanie, zawsze dostępne), odkryj co jest specyficzne dla tematu (przenieś do umiejętności) i dodawaj subagenty tylko wtedy, gdy potrzebujesz izolacji.

Umiejętności zasilające subagenty

Potężny wzorzec: wstrzykiwanie umiejętności do kontekstu subagenta za pomocą pola skills w nagłówku frontmatter:

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

Umiejętności security i testing-philosophy wstrzykują swoją treść do promptu systemowego subagenta. Recenzent otrzymuje specjalistyczną wiedzę w swoim izolowanym kontekście z dostępem tylko do odczytu.⁸

Mój pipeline przeglądów wykorzystuje ten wzorzec: trzy subagenty (correctness-reviewer, security-reviewer, conventions-reviewer), z których każdy otrzymuje inne wstrzyknięcia umiejętności. Recenzent poprawności otrzymuje debugging-philosophy. Recenzent bezpieczeństwa otrzymuje zestaw reguł bezpieczeństwa. Recenzent konwencji otrzymuje standardy kodowania projektu.

Moja architektura produkcyjna

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

Kluczowe wnioski

Dla indywidualnych deweloperów: - Zacznij od reguł dla standardów specyficznych dla projektu (łącznie poniżej 200 linii) - Dodaj umiejętności dla najczęściej używanych stosów technologicznych — automatyczna aktywacja eliminuje problem „zapomniałem wywołać” - Najpierw stwórz polecenia dla trzech najczęstszych przepływów pracy - Dodawaj subagenty tylko wtedy, gdy potrzebujesz ograniczenia narzędzi lub izolacji kontekstu

Dla zespołów: - Standaryzuj reguły na poziomie projektu dla spójności w całym zespole - Udostępniaj umiejętności przez wspólne repozytorium — przenośność umiejętności między projektami jest ich główną przewagą nad konfiguracją na poziomie projektu

Źródła