Jak elementy Claude Code współpracują ze sobą: Skills, Subagenty, MCP, Hooki, Pluginy

Czym jest Claude Code pod względem architektury

Claude Code funkcjonuje najlepiej, gdy jest postrzegany jako system orkiestracji inżynierii oprogramowania oparty na agencjach, a nie generator kodu, do którego się zwracamy. Zbiera kontekst projektu, określa, co jest potrzebne, wykorzystuje narzędzia, przekazuje zadania specjalistycznym podagentom, komunikuje się z zewnętrznymi systemami, wykonuje działania, sprawdza wyniki i powtarza proces, jeśli coś idzie nie tak.

Mówiąc krótko, jego działanie polega na pętli zbierania kontekstu, podejmowania działań i weryfikacji wyników. Model językowy jest tylko jednym z komponentów – otaczają go zarządzanie kontekstem, wielokrotnie używalne procesy pracy, specjalistyczne elementy, narzędzia, integracje, deterministyczna automatyzacja oraz mechanizmy weryfikacji.

Porównaj te dwa podejścia. Tradycyjny asystent do kodowania otrzymuje zapytanie, generuje kod i zwraca odpowiedź. System oparty na agentach przechodzi przez etapy: identyfikacja wymagań, zrozumienie kontekstu, wybór odpowiednich funkcji, wykonanie zadań, weryfikacja wyników, iteracja oraz dostarczenie rezultatu. Weźmy przykład prośby o plik testowy – w modelu opartym na agentach system mógłby przejrzeć repozytorium, zidentyfikować istniejące konwencje testowe, znaleźć odpowiedni API, napisać testy, je uruchomić, przeanalizować, co się nie udało, zmienić implementację, ponownie sprawdzić wyniki i zakończyć pracę podsumowaniem. Główna zmiana polega na przejściu od tworzenia kodu do wykonywania i weryfikowania zadań.

CLAUDE.md: trwały kontekst projektu

CLAUDE.md stanowi trwałą warstwę kontekstową projektu. Zawiera takie elementy jak konwencje programistyczne, decyzje architektoniczne, strukturę repozytorium, polecenia budowania i testowania, standardy testowe, zasady bezpieczeństwa oraz kryteria określające, co stanowi ukończenie pracy. Krótki fragment tego pliku może wyglądać następująco:

• Framework: Playwright z TypeScript
• Testy interfejsu użytkownika są wykonywane za pomocą npm run test:e2e, a testy API za pomocą npm run test:api
• Dane uwierzytelniające nigdy nie są zapisywane w sposób sztywny
• Każdy nowy punkt końcowy API wymaga testów negatywnych

Dzięki temu inżynierowie nie muszą ciągle tłumaczyć tych samych zasad. Można traktować ten plik jako odpowiedź na pytanie „jak działa ten projekt?”

Plik powinien zawierać stabilną wiedzę, której Claude potrzebuje wielokrotnie: konwencje repozytorium, wymagania dotyczące testowania, zasady architektury, polecenia budowania, zasady nazewnictwa, wymagania bezpieczeństwa oraz nawyki zespołu. Nie powinien przerodzić się w rozbudowany podręcznik z instrukcjami krok po kroku dla każdego możliwego zadania. Praktyczną granicą jest to, że CLAUDE.md określa, co Claude powinien wiedzieć o projekcie, natomiast „Umiejętności” opisują, jak wykonać określony rodzaj pracy. Oddzielenie ich ułatwia utrzymanie i zapewnia bardziej precyzyjny kontekst.

Umiejętności: wielokrotnie wykorzystywana wiedza specjalistyczna

Umiejętność reprezentuje użyteczną wiedzę w formie procesu pracy. Może zawierać instrukcje, skrypty oraz dodatkowe zasoby niezbędne do wykonywania specjalistycznych zadań: testowania API, przeglądania kodu, sprawdzania bezpieczeństwa, refaktoryzacji, tworzenia dokumentacji czy testowania regresyjnego. Jednorazowe sformułowanie tego procesu pozwala uniknąć konieczności ciągłego wyjaśniania tego samego zadania Claude’owi. Umiejętność pokazuje, w jaki sposób realizuje się tego typu prace.

Na przykład umiejętność do testowania API mogłaby krok po kroku przejść przez następujące etapy:

1. Identyfikacja umowy API.
2. Przegląd istniejących testów.
3. Tworzenie scenariuszy pozytywnych.
4. Tworzenie scenariuszy negatywnych.
5. Tworzenie przypadków granicznych.
6. Wykonywanie testów.
7. Analiza niepowodzeń.
8. Tworzenie raportu.

Gdy otrzymuje się prośbę typu „dodaj pokrycie regresyjne dla API płatności”, umiejętność ta nie przechodzi od razu do pisania kodu testowego. Zastosowuje standardową metodologię testowania, dzięki czemu każde API jest testowane zgodnie z tym samym standardem organizacyjnym.

CLAUDE.md versus umiejętności

Różnica polega na kontekście w porównaniu z procedurą. CLAUDE.md opisuje projekt: testy API wykorzystują Playwright, każdy endpoint wymaga testów negatywnych, a dane uwierzytelniające pochodzą z zmiennych środowiskowych. Umiejętność testowania API opisuje procedurę: sprawdza umowę, generuje testy pozytywne, negatywne i graniczne, je uruchamia i klasyfikuje błędy. Jedno opisuje to, co agent musi wiedzieć, a drugie to, w jaki sposób powinien wykonywać zadania.

Podagenty: delegowanie skoncentrowanej pracy

Podagenty to specjalistyczni pracownicy, którzy realizują określone zadanie w ramach swojego kontekstu i przesyłają wyniki z powrotem do głównego agenta. Główny agent może delegować zadania podagentom odpowiedzialnym za testowanie interfejsu użytkownika, testowanie API oraz bezpieczeństwo. Każdy z nich bada swoją dziedzinę niezależnie, a główny agent łączy ich wyniki w ostateczny rezultat.

Dlaczego nie jeden duży agent?

Złożone prace inżynieryjne często obejmują kilka niezależnych aspektów. Nowa funkcja płatności może wymagać weryfikacji interfejsu, testów regresyjnych API, analizy bezpieczeństwa oraz weryfikacji bazy danych. Jeden agent mógłby próbować zająć się tym wszystkim, ale wtedy kontekst staje się zbyt rozbudowany, a niespowiązane elementy się mieszają. Podagenty oferują cztery zalety:

• Izolacja kontekstu: każdy z nich otrzymuje tylko te informacje, które są dla niego istotne.
• Specjalizacja: każdy może wykonywać różne instrukcje.
• Badanie równoległe: niezależne zadania mogą być analizowane osobno.
• Czystszy główny kontekst: logi pośrednie nie muszą pozostawać w głównym kontekście orkiestratora.

Umiejętność versus podagent

Umiejętność opisuje jak powinna być wykonywana praca, natomiast podagent to osoba, która zajmuje się określoną częścią tego zadania. Umiejętność testowania API określa metodologię organizacji. Podagent testujący API otrzymuje konkretny interfejs API i analizuje go przy użyciu odpowiednich instrukcji oraz narzędzi.

Podagenci i okno kontekstowe

Zadania agenta wytwarzają dużą ilość wyników pośrednich. Przegląd bezpieczeństwa może przynieść analizę zależności, ustalenia dotyczące autoryzacji i uwierzytelniania, logi bezpieczeństwa, wyniki wyszukiwań w kodzie oraz wyniki testów. Podawanie wszystkich tych danych do głównego agenta z czasem utrudnia orkiestrację. Podagent bezpieczeństwa może sam przeprowadzić badania i zwrócić zwięzły wynik, np. dwa krytyczne ustalenia, cztery średnie, zalecane zmiany oraz wymagane testy. Główny agent otrzymuje ostateczny rezultat, a nie każdy krok realizacji zadania. Izolacja kontekstu jest zatem zarówno korzyścią architektoniczną, jak i udogodnieniem.

MCP i narzędzia

Czym jest MCP

MCP to skrót od Model Context Protocol. Jest to mechanizm integracji, za pomocą którego agent komunikuje się z zewnętrznymi systemami i źródłami danych. Po jednej stronie znajduje się Claude Code, a po drugiej – GitHub, Jira, bazy danych, API, przeglądarki oraz systemy monitoringu. Dzięki temu agent może pracować nie tylko w lokalnym środowisku programistycznym, ale także w systemach wykorzystywanych w całym cyklu życia rozwoju oprogramowania.

Inżynieria oprogramowania rzadko odbywa się wyłącznie w edytorze. Programista może potrzebować Jira do zarządzania wymaganiami, GitHuba do przechowywania kodu źródłowego i zgłaszania pull requestów, baz danych do weryfikacji, systemów monitoringu do wykrywania błędów w produkcji oraz API do kontrolowania zachowania aplikacji. Dzięki MCP proces pracy może obejmować odczytanie zlecenia z Jira, sprawdzenie odpowiedniego repozytorium, zidentyfikowanie odpowiedniego API, utworzenie testów, ich uruchomienie oraz otwarcie pull requesta. Agent programistyczny staje się w ten sposób częścią szerszego procesu inżynieryjnego.

MCP kontra narzędzia

To nie to samo. MCP to protokół lub warstwa integracji, natomiast narzędzie to konkretna funkcja, którą agent może wywołać. Serwer Jira MCP może udostępniać funkcje get_issue(), search_issues() oraz create_comment(). Funkcje te są narzędziami, a MCP umożliwia ich dostęp. Krótko mówiąc, MCP to sposób, w jaki agent się łączy, a narzędzie to to, co może robić.

Jakie narzędzia daje agentowi

Narzędzia pozwalają agentowi podjąć działania. Bez nich model językowy głównie rozumuje i pisze tekst. Dzięki nim może on przeczytać plik, aby zrozumieć implementację, przeszukać repozytorium w poszukiwaniu odpowiedniego kodu, edytować plik, aby zmienić zachowanie, uruchomić polecenie w celu wykonania testu, przeczytać wyniki, aby zdiagnozować błąd, ponownie edytować plik, aby go naprawić, oraz ponownie przeprowadzić weryfikację, aby to potwierdzić. Narzędzia przekształcają generator odpowiedzi w aktywnego uczestnika pracy inżynierskiej.

Rodzaje narzędzi

Claude Code posiada wbudowane funkcje do czytania i edycji plików, wyszukiwania kodu, wykonywania poleceń, interakcji z zasobami oraz uruchamiania specjalistycznych procesów pracy podagentów. MCP może udostępnić więcej możliwości. Przydatne jest posortowanie ich według przeznaczenia:

• Narzędzia obserwacyjne służą do czytania, wyszukiwania i analizy.
• Narzędzia działania służą do zapisywania, edycji i wykonywania działań.
• Narzędzia integracyjne umożliwiają połączenie z zewnętrznymi platformami.
• Narzędzia delegacyjne pozwalają na wezwanie specjalistycznych agentów.

Wspólnie umożliwiają one systemowi obserwowanie otoczenia, podejmowanie decyzji, działanie oraz sprawdzanie wyników.

Haki, polecenia i wtyczki

Haki

Haki zapewniają deterministyczną, opartą na zdarzeniach automatyzację. Umiejętność może poinstruować Claude’a do przeprowadzenia testów regresji podczas testowania API. Haki działają inaczej: za każdym razem, gdy wystąpi określone zdarzenie, automatycznie uruchamia się weryfikacja. Po modyfikacji kodu hak może uruchomić narzędzie do formatowania, następnie sprawdzenie poprawności kodu, a potem specyficzne testy, i zwrócić wyniki weryfikacji. Jest to przydatne, gdy określone procedury inżynieryjne muszą być wykonywane za każdym razem.

Umiejętności to procesy, których model może używać, natomiast haki to automatyzacja uruchamiana przez zdarzenia. Umiejętność opisuje zalecany proces przeglądu kodu. Hak natomiast uruchamia weryfikację poprawności kodu zaraz po jakichkolwiek zmianach w pliku. Umiejętności pomagają modelowi zrozumieć, jak pracować, a haki zapewniają, że kluczowe działania są wykonywane, gdy występują określone zdarzenia.

Dlaczego haki są ważne w środowisku produkcyjnym

Sztuczna inteligencja generatywna ma charakter probabilistyczny, dlatego zespoły nie powinny polegać na modelu przy decydowaniu o uruchomieniu ważnych procedur kontrolnych. Jeśli każda zmiana musi przejść przez formatowanie, sprawdzanie błędów, skanowanie bezpieczeństwa oraz testy jednostkowe, te kroki mogą być powiązane z automatyzacją deterministyczną, a nie pozostawione ocenie modelu. Zasada polega na wykorzystaniu rozumowania sztucznej inteligencji do podejmowania elastycznych decyzji oraz automatyzacji deterministycznej do realizacji obowiązkowych procedur kontrolnych, przy czym to rozróżnienie ma największe znaczenie w środowiskach korporacyjnych.

Polecenia

Polecenia to wyraźnie uruchamiane przepływy pracy, takie jak /review, /test i /debug. Wpisanie /review celowo uruchamia z góry zdefiniowany przepływ pracy polegający na przeglądzie kodu. Polecenie oznacza „Wyraźnie chcę uruchomić ten przepływ pracy”.

Polecenia są inicjowane przez użytkownika, natomiast haki są inicjowane przez zdarzenie. Wpisanie /test to wyraźne polecenie. Zmiany w kodzie źródłowym oraz automatyczne wykonywanie testów w odpowiedzi to automatyzacja oparta na zdarzeniach. Zatem polecenie jest uruchamiane przez człowieka, a hak – przez zdarzenie.

Polecenia i umiejętności również się pokrywają, ponieważ ponownie używalna umiejętność może udostępniać proces pracy, który ludzie celowo uruchamiają. Funkcja przeglądu mogłaby znajdować się w umiejętności i być uruchamiana za pomocą /review. Umiejętność zawiera jednak znacznie więcej niż tylko prośbę: instrukcje, materiały pomocnicze, skrypty oraz konfigurację związane z ponownie używalną możliwością inżynieryjną.

Plugi

Pluginy pakują i dystrybuują rozszerzenia. Wyobraźmy sobie organizację zajmującą się testowaniem, która stworzyła narzędzie do testowania API, narzędzie do testowania bezpieczeństwa, podagenta do API, podagenta do bezpieczeństwa, elementy do walidacji oraz integracje MCP. Zamiast aby każdy programista tworzył to środowisko od nowa, wszystkie te komponenty są dostarczane razem jako jeden plik pluginu.

Dlatego plaginy są ważne dla przedsiębiorstw. Przenoszą one inżynierię opartą na agentach z zakresu osobistej produktywności na poziom zdolności organizacyjnych. Gdy nie ma wspólnego pakietowania, każdy inżynier konfiguruje środowisko AI inaczej. Standardowy plik pluginu może zawierać standardy inżynieryjne, metody testowania, specjalistyczne agenty, zasady automatyzacji oraz integracje, dzięki czemu każdy projekt ma identyczne możliwości. Z punktu widzenia architektury plaginy należą do warstwy zarządzania i standaryzacji.

Jak komponenty ze sobą współpracują

Jedno zwięzłe przedstawienie przypisuje każdemu komponentowi określoną rolę:

• CLAUDE.md zna projekt.
• Umiejętności wiedzą, jak pracować.
• Podagenty przejmują delegowane, specjalistyczne zadania.
• Narzędzia wykonywają określone działania.
• MCP łączy się z zewnętrznymi systemami.
• Hooks automatyzują wydarzenia związane z cyklem życia.
• Polecenia uruchamiają procesy według potrzeb.
• Plugi pakują i rozpowszechniają dostępne funkcje.

Claude Code znajduje się pośrodku i koordynuje je. Rozwiązują one różne problemy architektoniczne i nie są wymiennymi funkcjami.

Jeden proces od początku do końca

Weźmy wymaganie „dodanie pokrycia regresji dla nowej API płatności”. Prawdopodobny przebieg wygląda następująco:

1. Wymaganie. Claude Code otrzymuje prośbę.
2. Kontekst projektu. Plik CLAUDE.md określa standardy testowania, polecenia, zasady organizacji repozytorium oraz wymagania dotyczące bezpieczeństwa.
3. Wybór umiejętności. Umiejętność testowania API dostarcza metodologię organizacji.
4. Delegowanie zadań. Specjalizowani asystenci analizują funkcjonalność API, kwestie bezpieczeństwa oraz wpływ regresji.
5. Integracje. Systemy połączone przez MCP umożliwiają dostęp do odpowiednich zewnętrznych platform.
6. Narzędzia. Claude Code czyta kod, wyszukuje pliki, tworzy testy i uruchamia polecenia.
7. Walidacja. Hooki wykonują sprawdzanie kodu, formatowanie, specyficzne testy lub inne kontrole.
8. Weryfikacja. Claude ocenia wyniki i decyduje, czy potrzebne są dodatkowe działania.
9. Ostateczny wynik. Agent zwraca testy, ich wyniki, dokumentację oraz podsumowanie tego, co zostało zrobione.

To pełny przepływ pracy w inżynierii agentowej, daleki od prostego generowania kodu.

Pętla agentowa

Aby ponownie sformułować podstawowy model: zbierać kontekst, podejmować działania, weryfikować wyniki. Zbieranie obejmuje zrozumienie wymagań, repozytorium, architektury, konwencji, zależności oraz obecnej implementacji. Podejmowanie działań obejmuje używanie narzędzi do wyszukiwania, modyfikowania, uruchamiania, integracji lub delegowania zadań. Weryfikacja obejmuje uruchamianie testów, analizę wyników, wykrywanie błędów oraz ocenę, czy wymagania rzeczywiście zostały spełnione. Nieudana weryfikacja powoduje powrót systemu do etapu zbierania informacji lub podejmowania działań.

W praktyce proces wygląda bardziej jak sekwencja: kontekst, działanie, weryfikacja, korekta, ponowna weryfikacja, a na końcu zakończenie. To właśnie ta iteracja odróżnia niezawodnego agenta od generowania kodu jednorazowego.

Projektowanie środowiska inżynierii testów w AI

Skuteczna architektura SDET w Claude Code mogłaby łączyć:

• CLAUDE.md wraz z frameworkami testowymi, architekturą, konwencjami testowymi, zasadami bezpieczeństwa oraz definicją zakończenia pracy.
• Umiejętności testowania API, interfejsu użytkownika, testów regresyjnych oraz analizy błędów.
• Podagenty do pracy z interfejsem użytkownika, API, kwestiami bezpieczeństwa i testami regresyjnymi.
• Narzędzia do wyszukiwania w repozytorium, edycji plików, wykonywania poleceń oraz uruchamiania testów.
• Połączenia MCP z GitHubem, Jira, bazami danych, API oraz systemami monitoringu.
• Hooki, które po wprowadzeniu zmian uruchamiają formatowanie, sprawdzanie składni, testy i weryfikację.
• Polecenia takie jak /api-test, /regression, /security-review i /debug.
• Wtyczka, która pakuje całość, aby kilka zespołów inżynieryjnych mogło ją ponownie wykorzystać.

Orkiestrator koordynuje te elementy zgodnie z wymaganiami.

Wybór odpowiedniego mechanizmu

Pięć pytań pomaga w doborze odpowiedniego elementu budulcowego.

• Czy chodzi o wiedzę, którą można ponownie wykorzystać do wykonywania zadania? Użyj Umiejętności.
• Czy potrzebny jest specjalistyczny, niezależny pracownik? Użyj Podagenta.
• Czy agent musi wykonać określoną operację? Użyj Narzędzia.
• Czy działanie zależy od zewnętrznej platformy lub źródła danych? Rozważ MCP.
• Czy coś powinno uruchamiać się automatycznie za każdym razem, gdy wystąpi zdarzenie cyklu życia? Użyj Hooka.

Ostatnie pytanie dotyczy dystrybucji: jeśli funkcjonalność musi zostać zapakowana i udostępniona, należy użyć Plugin. Ten framework pokazuje zrozumienie obowiązków każdej warstwy, dlatego często pojawia się w dyskusjach o architekturze.

Główna lekcja

Skuteczna inżynieria agentów nie polega przede wszystkim na większym lub inteligentniejszym modelu LLM. Funkcjonalny system wymaga skoordynowanych kilku umiejętności:

• Context – aby agent rozumiał projekt.
• Skills – dla możliwości wykonywania zadań w sposób powtarzalny.
• Delegation – ponieważ złożone zadania mogą wymagać specjalistycznych pracowników.
• Tools – aby agent mógł działać.
• Integration – dla dostępu do zewnętrznych systemów inżynieryjnych.
• Automation – aby procesy obowiązkowe wykonywały się niezawodnie.

Weryfikacja – aby sprawdzić, czy działania rzeczywiście zadziałały.

Pakietowanie – aby umiejętności mogły być ponownie wykorzystywane w różnych zespołach.

Dalszy rozwój wygląda następująco: chatbot AI, asystent kodowania AI, agent AI, proces pracy inżynieryjnej oparty na agentach oraz w końcu platforma inżynierii oprogramowania oparta na agentach.