Po czterdziestu godzinach budowy serwera MCP, który służył prośbom o przegląd kodu, kolega opuścił plik markdown 10 minut w stosunku do czterdziestu godzin. – Ten sam wynik. .claude/skills/ To doświadczenie nauczyło mnie czegoś, czego żadna dokumentacja nie wyjaśnia wystarczająco wyraźnie. Claude Code ma trzy odrębne mechanizmy rozszerzalności, a one mają zerowe pokrycie, gdy zrozumiesz, co każdy z nich naprawdę robi. Te trzy mechanizmy ujawniają świadomą filozofię architektoniczną, którą warto zrozumieć, zanim napiszesz jedną linię konfiguracji. Decyzje projektowe Architektura za trzema mechanizmami Każde rozszerzenie do Claude Code wchodzi w jedną z trzech kategorii. Istnieją jako odrębne mechanizmy, ponieważ działają na zasadniczo różnych warstwach systemu. Odpowiedź: "Jak Claude uzyskuje dostęp do systemów poza jego granicami procesowymi?" Są to oddzielne programy, które komunikują się z Claude za pośrednictwem JSON-RPC. Protokoł Modelowy Kontekst definiuje format drutu (rozmowy narzędzi, odczyty zasobów, szablony prośb), ale sam serwer jest tylko programem, który mówi JSON za pośrednictwem stdio lub HTTP. Utrzymuje własne połączenia, własny stan, własny cykl życia. Claude wysyła żądanie, serwer wykonuje pracę i wysyła odpowiedź. MCP servers Odpowiedź: "Jak uruchomić Claude'a z różnymi zachowaniami dla różnych zadań?" Podagent jest odosobnioną sesją Claude'a z własnym poleceniem systemu, własnym wyborem modelu, własnym dostępem do narzędzi i krytycznie własnym oknem kontekstowym. Subagents Odpowiedź: „Jak wstrzykiwać wiedzę wielokrotnego wykorzystania do konwersacji?” Umiejętność to plik oznaczający, który staje się poleceniem slash. Po nawołaniu jego zawartość jest wstrzykiwana bezpośrednio do bieżącej konwersacji jako instrukcje. Brak nowego procesu. Brak izolacji. Brak oddzielnego kontekstu. Tylko tekst, który kształtuje zachowanie Claude’a w ramach istniejącej sesji. Skills Jak serwery MCP rzeczywiście działają pod kapturem Model Context Protocol jest protokołem JSON-RPC 2.0. Kiedy Claude Code uruchamia, uruchamia każdy skonfigurowany serwer MCP jako proces dziecka i ustanawia dwukierunkowy kanał komunikacji za pośrednictwem stdio. Kiedy Claude decyduje się na użycie narzędzia MCP, sekwencja jest następująca: Claude generuje połączenie narzędzia z nazwą i argumentami JSON Claude Code wysyła to jako żądanie JSON-RPC do odpowiedniego procesu serwera Serwer wykonuje żądanie (zapyta o bazę danych, wywołuje API, czyta system plików) Serwer zwraca wynik jako odpowiedź JSON-RPC Claude Code wprowadza odpowiedź do kontekstu Claude'a Jest to prawdziwa komunikacja między procesami. Serwer może być napisany w dowolnym języku. Może utrzymywać trwałe połączenia z bazami danych, wyniki pamięci podręcznej, wdrażać ograniczenia prędkości, egzekwować kontrolę dostępu. { "mcpServers": { "analytics": { "command": "node", "args": ["./mcp-servers/analytics.js"], "env": { "DATABASE_URL": "postgresql://localhost/analytics", "MAX_ROWS": "1000", "QUERY_TIMEOUT_MS": "5000" } }, "deploy": { "command": "./mcp-servers/deploy-server", "args": ["--environment", "staging", "--read-only"], "env": { "API_TOKEN": "${DEPLOY_TOKEN}" } } } } o i Powyższe zmienne środowiska nie są funkcjami protokołu MCP. Są to granice bezpieczeństwa na poziomie aplikacji, które serwer analityczny egzekwuje wewnętrznie. Jest to ważny punkt architektoniczny: protokół MCP obsługuje komunikację, ale twój serwer obsługuje politykę. Jeśli Claude prosi o każdy wiersz w tabeli z dziesięcioma milionami kolejek, protokół z przyjemnością przekazuje to żądanie. Twój serwer musi powiedzieć nie. MAX_ROWS QUERY_TIMEOUT_MS W przypadku integracji krytycznych dla wydajności, w których serwer obsługuje tysiące żądań lub utrzymuje puli połączeń, Rust jest warte inwestycji. Obejmuje cały proces od obsługi protokołu po wdrożenie produkcji, w tym łączenie połączeń i urocze wyłączenie. Przewodnik po budowaniu serwerów MCP w Rust Remote MCP servers over HTTP with SSE follow the same protocol but replace stdio with HTTP transport.This matters for shared team infrastructure where a single MCP server instance serves multiple developers, but it adds network latency and requires authentication. Jak podwykonawcy pracują pod kapturem Subagenty nie są oddzielną technologią. Są to sesje Claude Code z ograniczonymi parametrami. Gdy wzywasz subagent, Claude Code rozpoczyna nową rozmowę z modelem określonym w konfiguracji agenta. Zaproszenie systemowe pochodzi z korpusu markdown pliku agenta. Lista narzędzi jest filtrowana tylko do tego, co pozwala konfiguracja agenta. I krytycznie, okno kontekstu jest puste z wyjątkiem zaproszenia systemowego i zadania, które dałeś subagentowi. Ta izolacja ma głębokie implikacje zarówno dla kosztów, jak i jakości. Zastanów się nad sesją debugowania, w której od dwudziestu minut badałeś bazę kodów. Twoje główne okno kontekstu zawiera dziesiątki odczytów plików, wyników uchwytu, śladów stosów i konwersacji. Jeśli teraz poprosisz o przegląd kodu w tej samej sesji, przegląd odbywa się w kontekście całego tego hałasu debugowania. Podagent zaczyna być czysty. jego kontekst zawiera tylko polecenie systemu (jego kryteria przeglądu) i pliki, które poprosiłeś go o przegląd. Brak hałasu. Brak zgromadzonego stanu. niż oceny sesji głównej, ponieważ model koncentruje się całkowicie na zadaniu. Lepiej --- name: code-reviewer description: Reviews code for quality, security, and style model: haiku tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit mcpServers: - github maxTurns: 15 --- You are a code review specialist. You have read-only access to the codebase and the GitHub API. Review criteria: - No unwrap() in production code paths (use proper error handling) - All public functions have doc comments - Error types implement std::fmt::Display - No println! in library code (use tracing macros) - Integration tests exist for new API endpoints - No TODO without a linked issue number For each file, provide a pass/fail checklist and specific line references for any failures. Do not provide general advice — only specific findings. o Dyrektywa kieruje tego podagent do najtańszego poziomu modelu. Dla pracy zgodnej z wzorem, takiej jak kontrola stylu i egzekwowanie konwencji, Haiku wykonuje się porównywalnie z Opusem. model: haiku o dyrektywa tworzy twardą granicę. Nawet jeśli wskaźnik systemu mówi: „napraw wszelkie problemy, które znajdziesz”, podagent nie może modyfikować plików. disallowedTools: Write, Edit o zapobiega ucieczce sesji podagentów. Bez tego podagent analizujący dużą bazę kodów może powtarzać przez pięćdziesiąt obrotów, gromadząc koszty. maxTurns: 15 Matematyka rzeczywistych kosztów routingu modelu To tam subagenci płacą za siebie, a potem za niektóre. Rozważ zespół pięciu deweloperów, z których każdy prowadzi około dziesięciu przeglądów kodu dziennie za pośrednictwem Claude Code. Bez podagentów, każdy przegląd działa w głównej sesji Opus. Dzięki gromadzeniu kontekstu z innych prac, typowy przegląd może zużyć 15 000-25.000 tokenów wejściowych i wygenerować 2000-4000 tokenów wyjściowych. Z podagentem Haiku, ta sama recenzja działa w czystym oknie kontekstu. Tokeny wejściowe spadają do 3000-8,000 (przywołanie systemowe plus kod poddany przeglądowi, bez nagromadzonego kontekstu).I koszt na token Haiku jest znacznie niższy niż w Opus. Ale istnieje subtelniejsza korzyść kosztów. Ponieważ okna kontekstu subagent są izolowane i czyste, recenzje są szybsze. Mniej kontekstu wejścia oznacza mniej czasu na przetwarzanie. Recenzja subagent Haiku zwykle zwraca się w ciągu 2-5 sekund. Ta sama recenzja w napełnionej sesji Opus może trwać 10-20 sekund. Ponad pięćdziesiąt dziennych recenzji, co jest znaczącą oszczędnością czasu. Decyzja o kierowaniu modelem nie zawsze jest oczywista. Niektóre zadania naprawdę wymagają rozumowania na poziomie Opus. Sesje debugowania głębokiego, w których model musi utrzymywać złożony stan w wielu plikach. Analiza architektoniczna, w której model musi rozumieć o implikacjach w całym systemie. Zadania refaktorujące, w których model musi zrozumieć subtelne relacje semantyczne. Te powinny pozostać na Opus, ale w odizolowanych podagentach, aby kontekst pozostał czysty. W odniesieniu do szerokiego zakresu strategii kosztów, nasze Obejmuje routing modelu wraz z innymi podejściami, takimi jak zarządzanie kontekstem i prośba o świadomość tokenów. Claude Code - Przewodnik po optymalizacji kosztów Jak umiejętności działają na prompt layer Umiejętności są architektonicznie najprostszym mechanizmem, a ta prostota jest cechą. Nazwa katalogu staje się poleceniem slash. reż. Claude Code Raeds i wstrzykuje jej zawartość do bieżącej konwersacji. .claude/skills/ /review .claude/skills/review/SKILL.md Nie ma procesu. Brak izolacji. Brak oddzielnego okna kontekstu. Tekst umiejętności dołącza do istniejącej konwersacji tak, jakbyś ją sam napisał. Oznacza to, że umiejętności korzystają z istniejącego kontekstu konwersacji (Claude już wie, na jakich plikach pracowałeś), ale także dziedziczą nagromadzony hałas konwersacji. # SQL Migration Standards Review the migration files for compliance with team standards. ## Naming Conventions - Tables: plural snake_case (user_sessions, not UserSession or user_session) - Columns: singular snake_case (created_at, not CreatedAt) - Indexes: idx_{table}_{columns} (idx_user_sessions_user_id) - Foreign keys: fk_{table}_{referenced_table} (fk_orders_users) ## Safety Requirements - All CREATE INDEX must use CONCURRENTLY - ALTER TABLE ADD COLUMN must include a DEFAULT for non-nullable columns - No DROP COLUMN without a preceding release that stops reading the column - All migrations must be reversible (provide both up and down) ## Query Patterns - Use EXISTS instead of IN for subqueries - Use COALESCE instead of CASE WHEN ... IS NULL - Avoid SELECT * in application code - Always specify column lists in INSERT statements Current schema for reference: $(cat db/schema.sql) Migration to review: $ARGUMENTS o Syntax wykonuje polecenie shell w czasie nawoływania i wstrzykuje wyjście. To daje umiejętności ograniczoną zdolność dynamiczną. Mogą one obejmować zawartość pliku, zmienne środowiska lub wyjście polecenia, ale nie mogą utrzymywać połączeń ani wykonywać operacji zewnętrznych wielostopniowych. polecenie shell działa raz, jego wyjście jest przechwycone, a ten statyczny tekst staje się częścią polecenia. $(cat db/schema.sql) o Umiarkowana przechwytuje wszystko po poleceniu slash. Postawiłby do ścieżki pliku, pozwalając na skierowanie umiejętności do określonych plików. $ARGUMENTS /migration db/migrations/20260311_add_sessions.sql $ARGUMENTS Umiejętności są potężne właśnie dlatego, że są proste.Każdy może je napisać.Dla zespołów, w których osoby niebędące programistami muszą kodować swoją wiedzę, Obejmuje to, w jaki sposób inżynierowie QA, menedżerowie produktów i pisarze techniczni tworzą skuteczne umiejętności bez dotykania kodu. Umiejętności dla zespołów nietechnicznych Kiedy nie stosować każdego mechanizmu (anty-patrony) Zrozumienie, co każdy mechanizm robi dobrze, to tylko połowa obrazu.Wiedząc, kiedy unikać każdego, zapobiega błędom, które popełniłem na początku. Antypatrony serwera MCP Jeśli informacje nie zmieniają się między nawołaniami i nie pochodzą z systemu zewnętrznego, jest to umiejętność. Widziałem, że zespoły budują serwery MCP, które zwracają standardy kodowania firmy, dokumentację API, a nawet przewodniki stylowe. Do not build an MCP server to serve static content. Claude Code ma już narzędzie Bash. Jeśli twoja „integracja” polega na uruchamianiu polecenia CLI i analizowaniu wyjścia, nie potrzebujesz serwera MCP. Umiejętność, która nakazuje Claudeowi używać Bash przy użyciu określonych poleceń, jest prostsza. Nie wszystko zewnętrzne potrzebuje serwera MCP. Jeśli Claude może uruchomić polecenie CLI za pośrednictwem Bash, jest to prostsze niż budowanie i utrzymywanie serwera MCP. CLI (za pośrednictwem narzędzia Bash) są świetne dla lokalnych przepływów pracy pojedynczego agenta. Do not build an MCP server when a Bash tool call would suffice. Serwery MCP są niezbędne, gdy potrzebujesz zdalnego wykonywania, rozszerzania uprawnień, trwałych połączeń lub operacji statycznych. lub biegać Nie potrzebuje do tego serwera MCP. Są to polecenia CLI, które Claude może uruchomić bezpośrednio. serwery MCP osiągają swoją złożoność, gdy wielu agentów lub użytkowników potrzebuje udostępnionego dostępu, gdy potrzebne są kontrolki uprawnień lub gdy integracja wymaga utrzymania stanu na wielu żądań. git log cargo test Serwer MCP, który wykonuje arbitralny SQL przeciwko produkcji, jest załadowaną bronią. Każdy serwer powinien egzekwować terminy zapytania, limity wierszy, dostęp tylko do odczytu w stosownych przypadkach i walidację wprowadzania. Do not build an MCP server without safety boundaries. Subagent antypatronów Subagenty świeci na powtarzalną, wyspecjalizowaną pracę. Jeśli musisz coś zrobić raz, po prostu zrób to w sesji głównej. Nadwaga tworzenia i utrzymywania pliku konfiguracji agenta nie jest warta pracy ad-hoc. Do not create a subagent for a one-off task. Niektóre zadania naprawdę wymagają silniejszego rozumowania. Raz próbowałem przeprowadzić analizę architektoniczną na Haiku. Zidentyfikował problemy na poziomie powierzchni, ale pominął okrągłą zależność, którą Opus natychmiast złapał. Haiku jest świetny dla dopasowania wzorców i egzekwowania list kontrolnych. Walczy z zadaniami wymagającymi wielostopniowego rozumowania w wielu plikach. Do not route everything to Haiku to save money. Podagent, który nawołuje innego podagenta, który nawołuje trzeciego, jest antymaternikiem. Każda warstwa dodaje opóźnienia i zasłania rzeczywistą pracę. Jeśli potrzebujesz tak dużo orkiestracji, restrukturyzuj swoje podejście. Zazwyczaj odpowiedź to jeden podagent z dostępem do wielu serwerów i umiejętności MCP, a nie łańcuch podagentów. Do not create deeply nested subagent chains. Umiejętności antypatrzynowe Jeśli zadanie wymaga danych z zewnątrz sesji Claude, potrzebujesz serwera MCP (lub podagent z dostępem do MCP). Do not write skills that require external data. Zawartość umiejętności jest wstrzykiwana w oknie kontekstowym. Umiejętność 5000 słów zużywa tokeny na każdym wezwaniu. Utrzymuj umiejętności skoncentrowane. Aby zaszczepić je warunkowo, zamiast osadzać je bezpośrednio w umiejętności. Do not write skills that are too long. $(cat reference.md) Umiejętność działa w bieżącym kontekście.Jeśli bieżący kontekst jest zanieczyszczony niepowiązaną pracą, skuteczność umiejętności spada.Zadania, które wymagają czystej płyty (recenzje, analizy, generowanie dokumentacji) są lepiej obsługiwane przez podagentów, które zaczynają się od świeżego okna kontekstu. Do not use skills for tasks that need isolation. Model kompozycji w produkcji Trzy mechanizmy nie są alternatywami. są warstwami, które tworzą.Zrozumienie wzorców kompozycji jest tym, co oddziela ustawienie robocze od eleganckiego. Podagent może mieć do niego przydzielone serwery MCP. W ten sposób tworzy się obszarowy dostęp. Podagent przeglądarki kodu może uzyskać dostęp do API GitHub za pośrednictwem serwera MCP GitHub, ale nie może dotknąć Twojej bazy danych ani rurociągu wdrażania. Podagent bazy danych-analityk podagent ładuje umiejętności SQL-standardów, więc każda analiza podąża za konwencjami nazwisk i wzorcami zapytań zespołu bez podagent analityk potrzebuje tych konwencji w swoim systemie. Możesz dać podagentowi dostęp do serwera MCP GitHub (aby mógł czytać relacje publiczne i komentarze), a jednocześnie wyłączyć pisanie i edytowanie (aby nie mogło ono modyfikować plików lokalnych). W naszej konfiguracji produkcyjnej w 8 wtyczkach rynkowych warstwa wygląda tak: Layer 3: Skills (Team Knowledge) /review — code review checklist /migration — database migration standards /deploy-check — pre-deployment verification steps /sql-standards — SQL naming and query conventions /api-design — REST endpoint design patterns Layer 2: Subagents (Specialised Behaviour) code-reviewer (Haiku, read-only, GitHub MCP, review skill) debugger (Opus, full access, all MCP servers) database-analyst (Sonnet, read-only, PostgreSQL MCP, sql-standards skill) deploy-checker (Sonnet, read-only, deploy + analytics MCP, deploy-check skill) doc-writer (Haiku, read-only, no MCP, style-guide skill) Layer 1: MCP Servers (External Connections) analytics-db — PostgreSQL metrics database deploy-pipeline — deployment API wrapper github — GitHub API for PRs and issues content-api — CMS for documentation publishing postgresql — application database (read-only) Każdy podagent komponuje dokładnie serwery MCP i umiejętności, których potrzebuje, na poziomie modelu odpowiadającym złożoności zadania. Wdrożenie-kontroler wykorzystuje Sonnet, ponieważ musi rozumieć gotowość do wdrożenia w wielu źródłach danych. Wdrożenie dokumentów wykorzystuje Haiku, ponieważ pisanie techniczne jest przede wszystkim zgodne z wzorem z przewodnikiem stylowym. Aby uzyskać pełny szczegół o tym, jak te warstwy współpracują ze sobą, nasz przewodnik przechodzi przez kompletny model kompozycji, a w szczególności konfigurację podagentów, nasze Obejmuje każde pole frontmatter z przykładami. wtyczki, serwery MCP i umiejętności jako architektura warstw Claude Agent - Przewodnik po budowie Funkcja decyzji Po roku budowania wtyczek produkcyjnych decyzja jest czystą funkcją tego, czego potrzebujesz: def choose_mechanism(need): if need.requires_external_data or need.has_side_effects: return "MCP Server" if need.requires_different_model or need.requires_tool_restrictions or need.benefits_from_isolation: return "Subagent" if need.is_reusable_knowledge or need.is_workflow_template: return "Skill" if need.is_complex: return "Subagent + MCP Server + Skill" # compose all three Jeśli znajdujesz się budując serwer MCP, który zwraca statyczny tekst, zatrzymaj się. To jest umiejętność. Jeśli piszesz umiejętność, która mówi "zapytaj bazę danych", zatrzymaj się. To jest serwer MCP. Jeśli uruchamiasz drogie sesje Opus do rutynowych kontroli, zatrzymaj się. Co się zmieniło dla nas Zanim zrozumieliśmy trójkąt, mieliśmy serwery MCP wykonujące pracę umiejętności, umiejętności próbujące wykonać pracę serwerów MCP i w ogóle nie ma podagentów. Po restrukturyzacji: 34+ umiejętności kodują konwencje naszego zespołu w zakresie przeglądu kodu, pracy w bazie danych, wdrażania, dokumentacji i projektowania API. Pięciu podagentów obsługuje wyspecjalizowane zadania w odpowiednim punkcie cenowym z odpowiednimi kontrolami dostępu. Cztery serwery MCP łączą się dokładnie z zewnętrznymi systemami, które muszą być podłączone, z odpowiednimi granicami bezpieczeństwa. Koszty miesięczne znacząco spadły. Jakość przeglądu poprawiła się, ponieważ subagenci zaczynają od czystego kontekstu. Konwencje zespołowe stały się spójne, ponieważ umiejętności egzekwują je identycznie dla każdego dewelopera. Trójkąt rozszerzalności nie jest ramą teoretyczną. Jest to praktyczne narzędzie, które uniemożliwia zbudowanie niewłaściwej rzeczy. co, biorąc pod uwagę, że zbudowałem niewłaściwą rzecz trzy razy przed ustaleniem tego, warto o tym wiedzieć.
