Podagenty w praktyce: role, budżety, blokady i ciche błędy
Podagenty Claude Code, które pozostają aktywne: role, pliki przekazywania, stan działania, budżety, blokady oraz sprawdzanie cichych błędów, a także różnice pomiędzy umiejętnościami a podagentami w praktyce.
Umiejętności rozwiązują jeden rodzaj zapominania: użytkownik przestaje tracić orientację co do struktury swojego kodu. Istnieje jednak drugi rodzaj, związany z tożsamością. Przy każdej nowej sesji model pojawia się jako ten sam entuzjastyczny generalista, chętny do wyrażenia rozsądnej i niepozornej opinii na temat wszystkiego, co mu przedstawisz.
Wiedza to problem umiejętności. Rola to problem podagenta, i to właśnie omawia ten tekst.
Wersja skrócona, zanim długość tekstu cię odstraszy: umiejętność informuje model o tym, jak wygląda twój świat, natomiast podagent określa, jaką rolę ma odegrać. Posiadanie obu jest lepsze niż posiadanie tylko jednego z nich, a dla programisty pracującego samodzielnie i zajmującego się kilkoma nieukończonymi projektami jednocześnie ta kombinacja ma jeszcze większe znaczenie. Jesteś jedynym specjalistą w zespole i nie możesz zajmować pięciu stanowisk naraz.
Pierwsza połowa tekstu stanowi podstawy koncepcyjne: co to są te pliki, gdzie znajdują się na dysku, jak je stworzyć. Tę część można poznać z dokumentacji. Druga połowa wynika wyłącznie z uruchamiania przez miesiące dwóch podagentów w tuzinie repozytoriów i obserwowania, jak ponoszą one porażki w sposoby, o których nie ostrzegały żadne przewodniki dotyczące najlepszych praktyk. Oba agenty są otwartej kodu, a rzeczywiste pliki warto przeczytać, ponieważ instrukcja dopracowana poprzez rzeczywiste testy uczy więcej niż jakakolwiek rada.
Luka, którą wypełnia podagent
Agen kodujący dostarczany jest z jedną domyślną osobowością – pomocnym generalistą. Poprosiwszy o przegląd pull requesta, otrzymuje się informacje o charakterze ogólnym i rozsądnym. Gdy zapyta się, dlaczego aplikacja działa wolno, zaczyna się analizować ten plik, który ostatnio edytowano. Poprosiwszy o plan migracji bazy danych, wynik wydaje się sensowny, choć pomija trzy kwestie, które mogłyby spowodować problemy w produkcji.
Wszystko to nie oznacza, że model jest słaby. Brakuje mu raczej określonej roli. Osoba sprawdzająca zasady bezpieczeństwa myśli inaczej niż inżynier bezpieczeństwa, a osoba szukająca błędu bada inne dowody niż osoba, która trzy razy już zajmowała się tym konkretnym problemem. Inteligencja jest już obecna – brakuje jedynie odpowiedniego kontekstu.
„Rozdawaniem” jest ciągłe wpisywanie tego samego wstępu. Zanim pozwolisz Claude Code przejrzeć jakąś zmianę, możesz wkleić coś w stylu: przejrzyj to jak paranoiczny specjalista od bezpieczeństwa, najpierw sprawdź granice autoryzacji, powiedz mi, co przedostaje się do logów, pomijaj drobne uwagi dotyczące stylu. Gdy to się zdarzy po raz trzeci w ciągu dwóch tygodni, dociera do nas świadomość – ten wstęp to rola, a rola, którą ciągle wpisujemy, to podagent, którego nikt jeszcze nie stworzył.
Ciągłe wpisywanie to czynnik wyzwalający, o którym wspomina każdy przewodnik. To nie on stworzył dwa agenty, które przetrwały, ponieważ one powstały pod wpływem dwóch innych czynników.
- Ekonomia kontekstu. Badania są skomplikowane: dwadzieścia wyszukiwań, tuzin pobraanych stron, z których połowa jest bezużyteczna. Jeśli tak się dzieje podczas głównej sesji, wypełnia się ona zbędnymi informacjami, których wcale nie chciało się czytać. Praca musi odbywać się gdzie indziej i wracać w formie streszczenia. To właśnie jest główny powód istnienia agenta do wyszukiwania w sieci. Nie jest on sprytniejszy od głównego wątku – jego zadaniem jest po prostu usunięcie przeczytanych informacji z kontekstu użytkownika.
- Rozdzielenie ról. Podczas pracy nad projektem chce się pozostać w ramach dyskusji projektowej. Przerywanie tego procesu w celu zatwierdzenia jedenastej modyfikacji technicznej, która wynika bezpośrednio z już podjętej decyzji, jest stratą czasu. Dlatego decyzje pozostają w rękach człowieka, a zadania związane z ich realizacją przechodzą na agenta wykonawczego. Umiejętności nie mają żadnego znaczenia przy tym rozdzieleniu – decyduje to, kto powinien myśleć o czym.
Recenzent to przyjemny pierwszy subagent. Te dwa są różne: to one przekształcają daną funkcję z udogodnienia w sposób, w jaki faktycznie prowadzony jest projekt.
Umiejętności versus subagenty: wiedza kontra zachowanie
Umiejętność zawiera informacje, które agent musi wiedzieć: swoją unikalną wewnętrzną bibliotekę, specyficzne uwarunkowania środowiskowe, które psują procesy kompilacji, fakty z danej dziedziny, o których musi wiedzieć nowy pracownik, ponieważ nikt inny nie mógłby ich odgadnąć. Jest ładowana warunkowo, gdy jest to istotne.
Subagent zawiera informacje o tym, jak agent powinien działać: co ma optymalizować, co najpierw sprawdzać, jakie kompromisy wybiera domyślnie oraz w jakiej formie powinna przyjść odpowiedź. Nie uczy modelu niczego nowego. Skupia już istniejącą inteligencję na jednym zadaniu.
Praktycznym testem jest wyobrażenie sobie wezwania specjalistycznego kolegi. Jeśli to, co może przynieść, to głównie informacje, których brakuje (wiedza z danej dziedziny, kontekst, doświadczenie), potrzebujesz umiejętności. Jeśli natomiast przyniesie głównie sposób podejścia do problemu – to, na co najpierw zwraca uwagę, co szczegółowo analizuje, co odrzuca bez sprawdzenia i co odsyła – wtedy potrzebujesz podagenta.
Weźmy inżyniera bezpieczeństwa analizującego twój kod. On nie tylko wie więcej niż ty, ale też pracuje inaczej: najpierw ustala granice autoryzacji, priorytetem jest unikanie eskalacji uprawnień, nazwy zmiennych nie mają znaczenia, nie ma zatwierdzenia bez komentarza dotyczącego poufnych informacji, a ustalenia są przedstawiane w uporządkowanej liście. To właśnie taki układ priorytetów jest kodowany przez podagenta.
Wiedza należy do umiejętności. Metodyka należy do podagenta.
Czym jest podagent w Claude Code
Claude Code jest narzędziem referencyjnym, ponieważ jest używane codziennie. Inne narzędzia znajdują się w osobnych sekcjach niżej, wraz z opisem ich specyficznych cech.
Wewnątrz Claude Code subagent to nic bardziej egzotycznego niż dokument Markdown rozpoczynający się od krótkiego bloku YAML. Może on być przechowywany w dwóch katalogach:
~/.claude/agents/to osobista biblioteka dostępna we wszystkich projektach na komputerze. Traktuj ją jak środowisko testowe..claude/agents/znajdujący się w repozytorium jest dostępny tylko dla danego projektu i jest przenoszony razem z nim po zapisaniu zmian.
Frontmatter jest krótki. Oto kompletny przykład działający w praktyce:
---
name: migration-risk-reviewer
description: Reviews database migration plans and schema changes for rollback risk, lock contention, and data integrity problems. Use before running any migration against real data.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior database engineer reviewing a migration for production risk.
## What you look at first
- Can this be rolled back without losing data?
- Does it hold locks on a busy table during deploy?
- Is the ordering safe for a multi-step change?
- Will existing data violate any new constraint?
## Output shape
Findings in order of severity:
1. Blockers — deploy will fail or data will be lost
2. High risk — real production risk, needs a mitigation
3. Medium risk — should fix, won't necessarily block
4. Notes — worth tracking
For each finding: what it is, why it matters, what to do about it.
Warto znać kilka szczegółów dotyczących sposobu, w jaki Claude Code obsługuje taki plik.
- Treść pliku stanowi polecenie systemowe. Wszystko, co znajduje się poniżej frontmattera, staje się instrukcjami dla podagenta podczas jego uruchomienia. Nie jest to dokumentacja, którą model czyta, a następnie na podstawie niej działa. Model czyta ją i przyjmuje jako swoją tożsamość.
descriptionma duże znaczenie. Claude Code korzysta z niego, aby zdecydować, kiedy automatycznie przekazać zadanie innemu agentowi, dlatego należy go napisać w sposób przypominający API, który inna osoba musi odkryć na podstawie kontekstu. Można tam napisać „Należy użyć przed uruchomieniem jakiejkolwiek migracji”, ale nie „Pomaga przy pracach z bazą danych”. Należy uwzględnić również aspekt negatywny: oba omawiane tutaj agenty podają, do czego nie nadają się, ponieważ system routingu chętnie przekaże im zadanie, do którego nie mają prawa się zajmować.
tools to lista uprawnień. Jeśli ją pominąć, podagent odziedziczy wszystko. Jeśli ją zawęzić, otrzymamy osobę przeglądającą, która fizycznie nie będzie mogła edytować twoich plików, nawet jeśli pojawią się u niej pomysły. Dla agenta przeglądającego jest to zaleta, ponieważ opcja „po prostu powiedz mi, co jest nie tak” nie powinna zmieniać rzeczy według kaprysu.model to wybór związany z budżetem, a nie szczegół techniczny. Tani model nadaje się do pracy mechanicznej, natomiast drogi – do podejmowania decyzji. Późniejszy rozdział omawia to szczegółowo, ponieważ wyjaśnia, dlaczego delegowanie się opłaca./agents również nimi zarządza.Możesz wywołać subagenta, prosząc o niego, pozwalając Claude’owi skierować do niego zapytanie na podstawie opisu lub włączając go do większego procesu, w którym działa jako zdelegowany pracownik. Zachowanie jest w każdym przypadku takie samo.
Słowo „agent” pełni zbyt wiele funkcji
To określenie odnosi się do czterech różnych rzeczy, a ich mylne łączenie powoduje ciągłe zamieszanie. Rozróżnijmy je:
- Subagent (plik w katalogu
.claude/agents/lub plik.agent.mdw obszarze Copilot) to plik wielokrotnego użycia definiujący specjalistyczną rolę. Właśnie o tym jest ten artykuł. - Tryb agenta lub autonomiczne uruchomienie to przełącznik funkcji. Pozwala to narzędziu wykonywać polecenia i edytować pliki bez konieczności zatwierdzania każdej linii. Jest to ustawienie uprawnień i nie ma nic wspólnego ze specjalistami.
- Agent kodowania w tle lub w chmurze to usługa, która bierze zadanie, pracuje nad nim niewidocznie i zwraca gałąź lub prośbę o połączenie. Również nie jest to plik specjalisty.
- Plik z instrukcjami na poziomie repozytorium to stałe wskazówki, zasady obowiązujące każdego agenta w tym repozytorium. Można go porównać do podręcznika pracowniczego, a nie do kolegi, którego się po imieniu zwraca.
Każdy raz, gdy w dalszej części pojawi się termin „subagent”, oznacza to wielokrotnie używalnego specjalistę napisanego raz i celowo wywoływanego. Jasne rozróżnienie tych czterech pojęć rozwiązuje około połowy problemów.
Pisanie pierwszego
Zacznij od najprostszego narzędzia, które faktycznie realizuje zadanie. Pierwszy podagent ma dwa zadania: określić rolę oraz wyjaśnić, co ta rola oznacza w praktyce. Wspomniany wyżej recenzent migracji już to robi – ma jasno zdefiniowaną rolę, konkretne heurystyki oraz przewidywalny format wyniku, przy czym jest celowo ograniczony w zakresie funkcji. Dodaje się do niego kolejne elementy po tym, jak użyje się go do rzeczywistych zadań i sprawdzi, co pomija.
Pierwsze podagenty najczęściej zawodzą z powodu niejasno określonej roli. „Pomocnik ds. bezpieczeństwa” nie jest taką rolą, ponieważ nie podaje modelowi, co należy optymalizować ani co sprawdzić najpierw. Prawdziwa rola funkcjonuje jako umowa behawioralna obejmująca samą pracę, pierwsze elementy, które należy przeanalizować, oraz te, które nigdy nie mogą zostać zignorowane. Jeśli zadanie nie da się sformułować w jednym zdaniu, jest zbyt niejasne.
Konkretna wersja określa, na czym model powinien się skupić, a co zignorować. Ignorowanie to połowa wartości. Recenzent, który przywiązuje taką samą wagę do błędu pisarskiego jak do granicy uprawnień, jest po prostu maszyną do średnich wartości.
Co powinno znaleźć się w treści
Gdy rola jest już ustalona, przydatna treść obejmuje pięć elementów. Od pierwszego dnia nie są potrzebne wszystkie pięć.
- To, co optymalizuje. Jedyna rzecz, którą ta rola stara się najbardziej poprawnie realizować. Gdy pojawia się kompromis, to właśnie to jest celem negocjacji.
- To, co sprawdza najpierw. Sygnały o najwyższym priorytecie – to, co każdy prawdziwy specjalista czyta przed czymkolwiek innym.
- Warianty awarii. Konkretne sposoby, w jakie ta kategoria zadań może pójść nie tak. Tu tkwi prawdziwa ekspertyza, a większość z niej pojawia się tylko poprzez obserwację, jak agent popełnia błędy przy wykonywaniu rzeczywistych zadań.
Zacznij od roli, pierwszych sprawdzeń i kształtu wyniku, a błędy same dostarczą reszty.
Przykład: łowca błędów, który ignoruje najnowsze zmiany
Oto przykład wynikający z powtarzającego się problemu. Coś się psuje, błąd jest wklejany do Claude Code, a jego pierwszą reakcją jest spojrzenie na plik, który został ostatnio edytowany. Czasami to jest słuszne. Często ostatnia zmiana nie ma z tym nic wspólnego.
Doświadczony debugger nie zaczyna od kodu. Zaczyna od dowodów – to znaczy od tego, co faktycznie nie działa, co mówią logi i co zmieniło się w środowisku – i otwiera źródło kodu dopiero wtedy, gdy hipoteza jest warta sprawdzenia. To jest zachowanie, więc zostało zapisane jako agent:
---
name: bug-investigator
description: Investigates a bug or failure starting from evidence, not from recent code changes. Produces ranked hypotheses with the next diagnostic step for each. Use for "why is this broken" before touching the source.
tools: Read, Grep, Glob, Bash
---
You are a senior engineer investigating a failure. Your job is to find the most
likely cause, rule out the alternatives, and say what to check next.
## Investigation order
1. Start from the symptom — what is actually failing, and how does it show up?
2. Get the error output and any logs from around the time it broke — ask the caller for them if they weren't provided.
3. Only then look at recent changes, and only if the evidence points there.
4. Read source last, once there's a symptom-to-cause hypothesis worth testing.
## Output shape
**Symptoms:** what's failing and how it manifests.
**Likely causes (ranked):** for each — the hypothesis, the evidence for it, the next diagnostic step.
**Ruled out:** what you checked and why it isn't the cause.
**Next steps:** in priority order.
**Open questions:** what you still can't confirm.
## Failure modes to avoid
- Don't assume the last change is the cause without evidence.
- Don't propose a fix before you can name the mechanism.
Następuje krok, który ludzie pomijają: należy to przetestować na rzeczywistym błędzie, który został już rozwiązany, a nie na modelu symulacyjnym. Przekaż mu objawy oraz logi z tamtego czasu i obserwuj, czy ścieżka dochodzenia pokrywa się z tą, która faktycznie doprowadziła do znalezienia problemu. Gdziekolwiek dochodzi do odchylenia, staje się ono nowym akapitem w tekście.
W tym pliku kończą się większość raportów o subagentach. Wszystko, co następuje dalej, opisuje to, co dzieje się po miesiącach użytkowania, co właśnie wymagało wyjaśnienia.
Odwrotność tego, co się spodziewano: subagent zaczyna od zera
Wszyscy przedstawiają izolowane okno kontekstowe jako czysty sukces. Jest to jednak sprawa dwustronna.
Po trzech różnych awariach podczas przekazywania informacji, zdanie trafiło do agenta realizującego zadanie. Opisuje on agenta jako osobę dobrze znającą projekt, ale nie wiedzącą nic o rozmowach planistycznych, które poprzedzały to zadanie.
Zimny ton rozmowy oznacza, że nie odnotowano tych dwóch godzin, w których odrzuciłeś oczywiste podejście, przekonałeś samego siebie, by zrezygnować z abstrakcji, i wybrałeś dziwnie wyglądające rozwiązanie z ważnego powodu. Dla podagenta nic z tego się nie wydarzyło. Ciepły ton w odniesieniu do projektu oznacza, że posiada on plik CLAUDE.md oraz bazę kodu, więc już zna zasady i idiomaty bez konieczności informowania go o tym.
Błędna ocena którejkolwiek z tych kwestii prowadzi do przewidywalnego bałaganu. Załóż, że agent uczestniczy w twojej rozmowie – chętnie odbuduje projekt, który odrzuciłeś godzinę temu, ponieważ z jego punktu widzenia ten projekt wygląda doskonale. Załóż natomiast, że nic nie wie o projekcie – wtedy stracisz tysiąc tokenów na opisywanie repozytorium, które mogłoby przeczytać szybciej, niż ty jesteś w stanie je streścić.
Wniosek, którego nie podał żaden przewodnik dla podagentów: przekaz to plik, a tym plikiem jest umowa. Nie jest to akapit wpisany do instrukcji zadania. To dokument na dysku z ustalonymi sekcjami, ponieważ improwizowane instrukcje za każdym razem po cichu pomijają inną kluczową sekcję.
W tym ustawieniu przekazem jest plik TASKS.md znajdujący się w korzeniu repozytorium, utworzony przez umiejętność planowania. Aktywne zadanie ma tylko te sekcje, a żadne inne:
- Cel. To, co będzie prawdą po zakończeniu pracy.
- Dlaczego (wskazówka). Link do decyzji zapisanej w
PLAN.md, a nie nowy argument na jej rzecz. To wskazówka, a nie tekst opisowy. - Stan wykonywania. Agent utrzymuje go aktualny. Więcej na ten temat poniżej, ponieważ to właśnie ta sekcja może cię uratować.
[ ] oznacza nie rozpoczęte, [x] zakończone, a [!] zablokowane, przy czym zależności są podane bezpośrednio, na przykład zależy od #2.Kluczem do skutecznego funkcjonowania jest zasada: należy wypełnić każdą sekcję przed rozpoczęciem pracy i umieścić myślnik tylko wtedy, gdy dana sekcja rzeczywiście nie ma zastosowania. W niewypełnionej sekcji agent może działać według własnego uznania.
Następnie jest rozdźwięk, którego dostrzeżenie zajęło najdłużej: dwa dokumenty o różnej długości życia. Wiedza podstawowa na temat sposobu wykonywania pracy powinna znajdować się w definicji agenta, a nie być powtarzana przy każdym zadaniu. Plik agenta zawiera protokół, czyli informacje o tym, jak odczytać zadanie, jak radzić sobie z przeszkodami, które elementy nigdy nie są modyfikowane oraz co zawiera raport. Plik z zadaniem przechowuje aktualną pracę. Wklejanie jednej instrukcji do trzech zadań z rzędu jest oznaką, że nigdy nie była ona częścią treści zadania, i powinna zostać przeniesiona do agenta.
Stan działania, ponieważ sesje się kończą
Jedna zasada uratowała więcej rzeczywistej pracy niż jakakolwiek sprytna metoda projektowania zapytań. Zawsze, gdy agent się zatrzymuje – czy to z powodu ukończenia pracy, czy blokady – musi odnotować aktualny stan rzeczy: zaznaczać pole statusu każdego elementu w miarę postępów oraz aktualizować notatkę o stanie pracy, opisującą to, co zostało zrobione, co jest zablokowane i dlaczego, co pozostało oraz gdzie należy kontynuować. Edytowanie pliku TASKS.md w tym celu jest wyraźnie w zakresie zadań, ponieważ ten plik stanowi punkt odzyskiwania, jeśli sesja się zakończy.
Sesje rzeczywiście się kończą. Laptop się zamyka, połączenie zostaje przerwane, osiągany jest limit użytkowania lub po prostu się nudzimy i naciskamy Ctrl-C w przypadku pracy prawie ukończonej. Gdy to się przydarza podagentowi, wszystko, co wiedział, znika. Jeśli jedynym zapisem postępów jest jego pamięć, musimy teraz porównywać zawartość naszego repozytorium z naszą pamięcią, aby odgadnąć, jak daleko zaszło.
Dlatego agent zapisuje postępy na dysku w miarę pracy, bezpośrednio w tym samym pliku, który przydzielił zadanie. Późniejsza sesja otwiera ten plik i kontynuuje od zaznaczonego miejsca. Dodaje kilka wierszy do definicji agenta oraz przekształca zakończoną sesję z kategorii „utracone zadanie” na „sesja w przerwie”.
Druga reguła dotyczy przepustowości, a nie przywracania stanu. Zablokowany element nie zatrzymuje kolejki. Gdy element jest niewystarczająco opisany lub napotyka nie do rozwiązania zależność, agent oznacza go jako [!] wraz z jednowierszowym powodem i kontynuuje pracę z pozostałymi elementami, które od niego nie zależą, zatrzymując się dopiero wtedy, gdy nic więcej nie może być realizowane. Agent nigdy nie zgaduje co do projektu, a każdy zablokowany węzeł trafia do raportu, aby człowiek mógł go rozstrzygnąć.
Standardowym zachowaniem w przypadku problemu jest zatrzymanie się i zadanie pytania, więc kolejka ośmiu zadań daje jeden ząb do wykonania oraz jedno pytanie. Standardowe zachowanie bez żadnych ograniczeń jest jeszcze gorsze: agent zgaduje rozwiązanie i kontynuuje pracę, pozostawiając siedem elementów zbudowanych na pomysłach, których nikt nie zatwierdził. Przejdź dalej i kontynuuj, nigdy nie zgaduj, zgłoś rozdźwięk. To połączenie umożliwia umieszczenie pracy w kolejce i odejście.
Kto płaci za ten rodzaj myślenia
Tutaj pole model odgrywa kluczową rolę, a ekonomia całego układu zależy od niego.
Opis realizatora, zaczerpnięty z rzeczywistego projektu, brzmi mniej więcej tak: robot Sonnet wykonywać ma w pełni określone, mechaniczne zadania kodowania z pliku zadań, podczas gdy główny wątek planowania Opus pracuje dalej; nie służy to do podejmowania decyzji projektowych, rozwiązywania otwartych pytań ani przeprowadzania testów jakości w czasie rzeczywistym – wszystko to pozostaje w głównym wątku.
Drugi, droższy model podejmuje decyzje, natomiast tańszy model zajmuje się pisaniem. Wąski zakres działania jest właśnie tym, co sprawia, że tańszy model jest niezawodny: robot Sonnet, który otrzymuje w pełni określoną, numerowaną kolejkę z bazy kodu, którą potrafi odczytać, funkcjonuje spójnie.
Taki podział umożliwia również dwie różne metody pracy przy użyciu tej samej infrastruktury.
- Uregulowany rytm. Ustawia się dwa lub trzy zadania, wysyła agenta do ich wykonania i planuje kolejną partię w miarę ich realizacji. Żadna ze stron nie czeka bezczynnie na drugą.
- Bez nadzoru. Tworzy się dużą liczbę zadań w kolejce, a następnie odchodzi się, by wrócić później do analizy różnic, raportu oraz notatki o stanie wykonania, w której wskazane jest, które zadanie zostało zablokowane i dlaczego.
Pod tym wszystkim znajduje się warstwa uprawnień, która faktycznie egzekwuje zasady. Osoba realizująca zadanie bez nadzoru ma swoje pliki oraz polecenia w shellu dodane do listy dozwolonych w ustawieniach projektu, a wszystko inne poza tą listą musi przejść proces zatwierdzenia. To, co podaje prompt, stanowi politykę; lista dozwolonych elementów jest natomiast barierą.
Jeszcze jedna linijka w tym agencie istnieje z powodu najdroższej pomyłki: przetwarzanie poszczególnych elementów musi odbywać się w kolejności sekwencyjnej, od góry do dołu, w jednej rundzie, bez użycia równoległych procesorów i bez zatrzymywania się w celu raportowania po każdym elemencie.
Agenty równoległe brzmią jak rozwiązanie zapewniające szybkość, ale w rzeczywistości tak nie jest. Każdy z nich ostatecznie wrzuca cały swój wynik do kontekstu, który go stworzył, a sprytnie zaprojektowana struktura może przykryć sesję, która musi to wszystko przeczytać. W ten sposób traci się rzeczywitą pracę. Uruchamianie zadań równolegle na oddzielnych plikach powinno być opcją stosowaną tylko w konkretnych sytuacjach, a nie standardem. Standardem jest praca jednego pracownika, który kolejno przetwarza elementy z jednej kolejki.
Bez budżetu wydaje wszystko
Każdy podagent z narzędziami takimi jak wyszukiwanie, pobieranie danych czy shell będzie pracować bez przerwy, dopóki coś go nie zatrzyma, a stwierdzenie „to wystarczy” nie jest wnioskiem, do którego model może samodzielnie i niezawodnie dojść. Agent badawczy bez budżetu może spędzić popołudnie na przeglądaniu licznych ukrytych kart w przeglądarce, by ostatecznie dostarczyć streszczenie, które mogłyby dać trzy pierwsze wyniki.
Zatem agent do wyszukiwania w sieci działa przy ścisłych ograniczeniach, które znajdują się ponad jego metodologią i wszystkim innym. Plany działania dla poszczególnych źródeł, które ładuje w czasie wykonywania, zawierające listy źródeł oraz taktyki zapytań dla każdej domeny, mają swoją osobną sekcję dalej w tekście.
Cztery wnioski z tej listy ograniczeń są ważniejsze niż same liczby, które się w niej znajdują – warto je dostosować do potrzeb własnej pracy.
Zaproponuj regulację głębokości zamiast stałego limitu. Każda pojedyncza ustawienie jest większość czasu błędne: zbyt restrykcyjne przy trudnym pytaniu, zbyt luźne przy szybkim sprawdzeniu faktu. Dzięki trzem określonym poziomom oraz domyślnemu ustawieniu wybór deep staje się świadomą decyzją, a nie przypadkiem. Określono również kolejność priorytetów: najpierw obliczenia podane przez użytkownika, potem poziom wskazany w instrukcjach, następnie konfiguracja projektu, a na końcu standard.
Budżet zachęca do gry, ponieważ model traktuje go jako cel, więc konieczne są klauzule ograniczające to zjawisko. Klauzule istotne dla tego procesu mówią o pobieraniu jednego wyniku na URL, nigdy ponownym czytaniu już przeczytanej strony, zatrzymaniu się zaraz po udzieleniu odpowiedzi na pytania użytkownika oraz traktowaniu pozostałego budżetu jako czegoś innego niż kwota. Głębokie przetwarzanie, które kończy się po sześciu wyszukiwaniach, uznawane jest za sukces, a nie za marnotrawstwo.
Ostatnie zdanie zostało dodane po tym, jak przetwarzanie udzieliło odpowiedzi na pytanie już przy czwartym wyszukiwaniu i kontynuowało pracę mimo to, ponieważ dwadzieścia było ustalonym limitem. Trzeba głośno powiedzieć, że wcześniejsze zakończenie to zwycięstwo.
Policz rzeczy, które coś kosztują. Budżet pobierania obejmuje każde żądanie sieciowe, od standardowych pobrań po kolejne próby odzyskania stron zablokowanych, a także każde żądanie HTTP w skrypcie pomocniczym, przy czym każda próba ponownego wysłania z kodem 429 jest liczona osobno. W wczesnej wersji liczono jedynie „wołania do pobierania”, przez co agent nieumyślnie omijał te ograniczenia. To nie było oszustwo – po prostu wiernie przestrzegano źle napisanej zasady.
Ustaw tak, aby informował o wydatkach. Po każdej fazie agent raportuje linijkę w stylu [deep: 3/20 wyszukiwań, 5/30 pobierania]. Bez tego nie można odróżnić starannego przeprowadzenia zadania od jego niekontrolowanego przebiegu aż do jego zakończenia. Jeśli budżet się wyczerpie, a pytania pozostaną bez odpowiedzi, agent zatrzymuje się i precyzyjnie wskazuje, co nadal jest nieznane, który URL najprawdopodobniej na to odpowie oraz że ponowne przeprowadzenie zadania w głębszym stopniu jest możliwe. Jedynym zabronionym działaniem jest kontynuowanie pracy po przekroczeniu limitu bez podania tego faktu, ponieważ to użytkownik wybrał poziom, a przekroczenie budżetu unieważnia tę decyzję.
Restrykcje stanowią większość cech dojrzałego agenta
Otwórz najczęściej używany plik agenta i pierwszą rzeczą, która rzuca się w oczy, jest stosunek. Opis roli zajmuje jeden akapit, podczas gdy zakazy wypełniają całą listę. Ta nierównowaga nie jest efektem dodatkowych informacji. Agent wyposażony w prawdziwe narzędzia ma o wiele więcej sposobów na spełnienie wymogów technicznych, niż ktokolwiek może przewidzieć.
Jeden przykład pokazuje, dlaczego to właśnie dodatkowe informacje stanowią sedno sprawy. Agentowi zabrania się używania automatyzacji przeglądarki: żadnej prostej przeglądarki, żadnego wbudowanego przeglądania, żadnego Playwrighta, żadnych narzędzi rozszerzeń Chrome, żadnego otwierania kart czy okien, a jeśli dostępne są jakieś narzędzia przeglądarki, to nie są one przeznaczone do tego zadania. Powód jest tam jasno podany: otwieranie kart w celu czytania stron powodowało kiedyś powstanie około setki takich kart i psuło przebieg zadania.
Kolejny przykład pochodzi od twórcy w repozytorium research-agent, gdzie ten mechanizm jest głównym powodem, dla którego ktoś powinien przestrzegać zasady. Nigdy nie wolno tworzyć plików w katalogach agents/ ani skills/, ponieważ agents/ zawiera bazowe dane aplikacji, a menedżer pakietów podczas instalacji przekształca wszystkie pliki .md znajdujące się w nim w odrębne agenty najwyższego poziomu. Plik umieszczony tam przypadkowo trafiłby do każdego projektu korzystającego z tej aplikacji.
To jest zasada, którą należy wydobyć: każda blokada określa swój mechanizm. Agenta nie trzeba przekonywać. Powód musi zostać zapisany, ponieważ ograniczenie bez niego zostanie usunięte. Po sześciu tygodniach, poprawiając tekst, natrafisz na zdanie mówiące „nigdy nie twórz plików tutaj” – będzie wydawać się arbitralne, więc pomocnie je uogólnisz. Zapis dotyczący tego, że instalator sprowadza wszystko do każdego projektu konsumenta, sprawi, że twój przyszły ja zostawi to w spokoju.
Kilka innych form, jakie przybierają te ograniczenia po dłuższym czasie pracy nad tym:
Zablokuj kategorię i wymień jej przykłady. Proste „brak automatyzacji przeglądarki” pozostawia agencie decyzję o tym, czy okno przeglądania spełnia warunki. Wymienienie sześciu konkretnych narzędzi, których nie może używać, zamyka drogę, którą w przeciwnym razie próbowałby się przecisnąć.
Nazwij zachowanie, a nie tylko narzędzie. Najlepsze zapisy w pliku przeciwdziałają określonej tendencji, a nie wydają polecenia: jeśli zauważysz, że piszesz skrapera lub generator raportów, przestań, ponieważ obechasz zadanie, zamiast je wykonać. Sprawni agenci radzą sobie z ograniczeniami, tworząc narzędzia. To właśnie tę kategorię należy zakazać.
Trzeba zapewnić alternatywne rozwiązania, w przeciwnym razie staje się to autostradą. Niektóre strony naprawdę nie da się pobrać, dlatego istnieje szereg rozwiązań awaryjnych dla zablokowanych adresów URL. Otwiera się one tylko wtedy, gdy zwykła ścieżka pobrań zawiedzie w tym konkretnym adresie. Nigdy nie przydzielają dodatkowego slotu na pobrań, sprawdzają obecność zainstalowanego narzędzia bez jego instalacji i ograniczają ilość wyjścia, aby wydruk strony nie przytłoczył kontekstu. Następnie następuje ostateczne zatrzymanie: jeśli adres URL pozostaje niedostępny po wykorzystaniu wszystkich dostępnych opcji, sprawa jest zamknięta. Zapisz to i przejdź dalej, bez dalszych prób, bez dodatkowych narzędzi, bez żadnych pomysłów.
Wyjaśnij dokładnie, dlaczego ta wyjątkowa sytuacja nie stanowi luky prawnej. Krótki akapit w pliku wyjaśnia, że jednorazowe pobranie tekstu prostego bez interfejsu użytkownika nie narusza zakazu używania przeglądarki, ponieważ zakaz ten dotyczy uruchamiania przeglądarki i pozostawiania otwartych kart do zamknięcia przez osobę. Jeśli tego pominąć, wydaje się, że wyjątek i zakaz ze sobą kolidują, a model w takiej sytuacji wybiera interpretację, która pozwala na większą swobodę.
Poddają się w milczeniu, ale z pewnością siebie
Dwa badania kiedyś przyniosły wyniki nie tylko w porządku, ale nawet doskonałe: czyste ustalenia, autentyczne źródła, spójny raport. Obie prace wskazały Reddit jako główne źródło. Żadne z nich nie pobrało niczego z Reddit.
Stało się tak, że zapytanie WebSearch ograniczone do domeny site:reddit.com zwróciło dziesięć czystych, wiarygodnych wyników z innych domen, w tym z forum społecznościowego skupionego na rynkach rzemieślniczych, strony rządowej poświęconej małym przedsiębiorstwom oraz platformy do udostępniania slajdów, przy czym nie wystąpił żaden błąd. Żadnego błędu 403, żadnego pustego zestawu wyników, żadnego ostrzeżenia. Filtr domen został po prostu zignorowany, a w wynikach nie było żadnej wskazówki na to. Agent otrzymał uporządkowaną listę użytecznych stron z niewłaściwych źródeł i postąpił tak, jak robi to każdy rozsądny pracownik w takiej sytuacji – wykorzystał je i poinformował o sukcesie.
Zasada zapisana tego samego dnia jest teraz podstawą całego projektu: jeśli nie można dotrzeć do określonego źródła, proces musi to odnotować i w żadnym wypadku nie może kontynuować się w milczeniu, używając tego, co zwróciło narzędzie. Raport wskazujący Reddit jako główne źródło, a jednocześnie twierdzący o sukcesie na forach handlowych, jest gorszy od całkowitego niepowodzenia, ponieważ nikt, kto go czyta, nie może tego stwierdzić.
Nieudany proces wymaga ponownego przeprowadzenia. Proces, który potajemnie zmienia swoje źródła, wymaga decyzji opartej na dowodach, które przypuszczasz, że pochodzą z miejsca, z którego nie pochodzą. Izolowane okno kontekstowe, właśnie ta funkcja, jest powodem, dla którego nie możesz zobaczyć, co się dzieje: nie dociera do ciebie żaden transkrypt, tylko jakikolwiek streszczenie, które agent postanowił napisać.
Trzy rozwiązania naprawiają tę sytuację, a żadne z nich nie polega na proszeniu agenta o ostrożność.
Przeprowadź test mechaniczny. Nie wykryto żadnych błędów, więc agent nie widział powodu, by cokolwiek sprawdzać. Rozwiązaniem jest jedno zdanie, które nie wymaga oceny: gdy wyszukiwanie zostało ograniczone do określonego domeny, a żadna z powracających adresów URL do niej nie należy, należy to traktować jako zero wyników, a nie jako zbiór wyników. Nie wymaga to żadnych dodatkowych narzędzi, pobierania danych ani uprawnień, ponieważ adresy URL są już dostępne. Zasada „bądź podejrzliwy wobec swoich źródeł” nie daje agentowi żadnego zadania do wykonania, natomiast zasada „sprawdź nazwę hosta w porównaniu z tą, którą użyłeś do filtrowania” tak.
Traktuj pochodzenie danych jako wymagany kanał wyjściowy z określonym schematem. W tym przypadku struktura wyjściowa przestaje być zbiorem nagłówków sekcji i zaczyna zachowywać się jak konkretny typ. Dwa tablice są powiązane z nazwami swoich kluczy.
unreachable[]zawiera jedną pozycję dla każdej ściany, przy czym klucze to dokładniesource,urlireason. Obejmuje zarówno błędy przy próbie pobrania danych, jak i ciche zastąpienie treści.sources[]zawiera jedną pozycję dla każdego źródła, które faktycznie dostarczyło odpowiedź, przy czym klucze to dokładniesource,urlifields. Strony, które zostały otwarte, ale nie dostarczyły żadnych informacji, nie są rejestrowane. Źródło, które dostarczyło dane dla czterech pól, stanowi jedną pozycję z czterema nazwami, a nie cztery osobne pozycje.
To subtelne wezwanie, które początkowo było błędne: informacja o pochodzeniu służy do adnotacji, a nie do blokowania. Jeśli na pytanie odpowiedział udokumentowany zamiennik, pole uznaje się za odpowiedziane, a wpis unreachable jedynie odnotowuje, że odpowiedź nie pochodziła z wskazanego źródła. Pozwolenie na to, by błąd w konkretnym elemencie doprowadził do awarii całego procesu, spowodowałoby poważne problemy dokładnie w sytuacji, gdy istnieje rozwiązanie obejścia.
Jedna nieudana próba niesie ze sobą lekcję, której warto się nauczyć. Pierwszy szkic tego agenta nakazywał mu „zapisywać to jako niedostępne” w czterech różnych miejscach, ale nigdzie nie określono nazwy pola, tablicy ani pola wyjściowego. Ta instrukcja nie prowadziła do żadnego rezultatu. Agent musiał coś zapisywać, nie mając jednak miejsca na to, więc nic nie zapisywał, a nic się nie skarżyło. Zawsze, gdy piszesz instrukcję dla podagenta, upewnij się, że opisana przez nią akcja ma cel. „Zgłoś X”, bez określenia, w jakim polu ma być to zapisane, nic nie robi i czuje się z tym dobrze.
Sprawdź to spoza agenta. To, czy agent dotrzymał umowy dotyczącej swoich wyjść, określa skrypt uruchamiany później, a nie zapewnienia samego agenta. Około 180 linii kodu w Pythonie sprawdza JSON pod kątem zadeklarowanych pól, a to jest cenniejsze niż jakiekolwiek podkreślenia w instrukcji.
Ta sama koncepcja pojawia się w instrukcjach dla osoby realizującej zadanie w repozytorium bez dostępnej bazy testów. W instrukcjach podano, że żadna taka baza nie istnieje; sekcja „Tests” zawiera listę sprawdzeń, które pełnią tę funkcję – każde z nich musi zostać przeprowadzone, a wyniki muszą być dokładnie opisane. Gdy sprawdzenie brzmi „ten URL się rozwiązuje”, oznacza to faktyczne pobranie treści z tego adresu. URL, którego nie udało się zweryfikować, nie trafia do pliku – jest odnotowywany jako niezweryfikowany wraz z opisem tego, co się stało. Czytelnik, który zaufa linkowi, którego nikt nie sprawdził, straci czas na próbę pobrania treści z adresu 404, czego można by uniknąć prostym wyszukiwaniem, przez co niezweryfikowany URL jest gorszym wyborem niż jego całkowite pominięcie.
Agenci chętnie twierdzą, że przeprowadzili weryfikację, której w rzeczywistości nie dokonali, ponieważ wiarygodne i zweryfikowane twierdzenia wyglądają podobnie w podsumowaniu. Dla każdego istotnego sprawdzenia należy określić konkretną czynność, która stanowi dowód na jego przeprowadzenie.
Jedno zadanie na agenta i nawyki powodujące rozrost pliku
Najlepsi podagenti mają tylko jedno zadanie. Możesz się sprzeciwić, ponieważ wymienione powyżej pliki nie są krótkie, a plik agenta badawczego liczy aż 188 wierszy. Rozstrzygający fakt: zadanie pozostało jednym zdaniem, podczas gdy plik się powiększał. To, co się nagromadziło, to ograniczenia, reguły wykrywania oraz zasady wyjścia – coś w rodzaju blizn wokół stałej „szkieletowej” struktury – przy czym przez rok nie pojawiła się ani jedna nowa odpowiedzialność. Dodawanie wierszy z powodu awarii oznacza, że plik dobrze pełni swoją funkcję. Dodawanie wierszy w celu obsługi nowego rodzaju pracy jest objawem rozrostu pliku, a rozwiązaniem jest podzielenie agenta, a nie dodawanie kolejnych sekcji.
Wszystkie rozdęte wersje wyglądają podobnie, a każda z nich kiedyś została wypuszczona na rynek. Istnieje „everything-reviewer”, który oblicza średnią z pięciu kryteriów, ale nie odnosi sukcesu w żadnym z nich. Istnieje etykieta „senior engineer” bez żadnych konkretnych umiejętności za nią kryjących się. Istnieje agent, który ponownie generuje plik CLAUDE.md, dodając informacje o koszcie tokenów zamiast opisu zachowania, oraz taki, który kopiuje określoną umiejętność, aż obie wersje zaczną się różnić. Wszystkie te rozwiązania mają jeden wspólny błąd: zadanie, które stało się zbyt rozbudowane, by można je było opisać jednym zdaniem.
Oczywistym następnym pytaniem jest to, co po roku takiego rozwoju faktycznie pozostaje w użyciu.
Dwa, które przetrwały
Większość artykułów na ten temat proponuje schemat organizacyjny typów agentów do stworzenia. Rzeczywisty zestaw po roku to zaledwie dwa agenty, i to wszystko.
Jedna informacja ujawniona, ponieważ dotyczy jej własna zasada artykułu: agent do wyszukiwania w sieci powstał jako odgałęzienie projektu o otwartym kodzie źródłowym przeznaczonego do zaawansowanych badań. Szkielet umowy wynikowej, czyli sekcje podsumowujące oraz zawsze wymagana lista źródeł, pochodzi w dużej mierze dosłownie z oryginału. Warstwa sterująca umieszczona na wierzchu, obejmująca budżety, zakazy, schemat pochodzenia oraz drabinkę eskalacji, jest oryginalna i stanowi połowę całkowitej liczby linii tekstu. Wszystko, co dotyczy aspektów związanych z „bliznami” w tym tekście, odnosi się właśnie do tej połowy.
Agent do wyszukiwania w sieci przeprowadza ograniczone badania w sieci i zwraca wyniki wraz z ich źródłami. Obecnie jest zainstalowany w kilkunastu repozytoriach, w tym na statycznym blogu, kilku pipeline’ach oraz kilku projektach badawczych. Wszystkie informacje dotyczące budżetów, zakazów oraz cichej substytucji pochodzą z historii edycji tego jednego pliku.
Wdrożyciel wykonuje w pełni określoną kolejkę zadań, podczas gdy planowanie trwa w innym miejscu. Cztery projekty mają taką kolejkę. To właśnie one dostarczyły informacji na temat umów przekazywania zadań, stanu działania oraz aspektów ekonomicznych delegowania obowiązków.
Pozostałe elementy znajdujące się w folderach agentów trafiły tam wraz z ramami programowymi i funkcjonują jak szuflada na śmieci o lepszym brandingu niż prawdziwa szuflada. Specjaliści, których uznano za koniecznych (badacz testów niestabilnych, agent zajmujący się optymalizacją PR, osoba przygotowująca dokumentację, agent zajmujący się strukturą kodu w projektach porzuconych) wydawali się rozsądni, ale praktycznie żaden z nich nie został stworzony. Te, które ostatecznie pozostały, okazują się nie być tymi, które wydawały się przydatne – to te, w których ten sam konkretny problem związany z wykonywaniem pracy w niewłaściwym kontekście lub przez niewłaściwą osobę ciągle się powtarzał.
Pomijmy więc schemat organizacyjny. Skup się na zadaniach, które chciałbyś wykonać gdzie indziej, i zapisz je osobno.
Najpierw szablon, potem specjalizacja
Wzorzec, który sprawia, że drugi, trzeci i czwarty realizator są tańsi, polega na tym, że agent jest generowany na podstawie szablonu, a następnie modyfikowany tam, gdzie projekt się różni.
Nawyki planowania dostarczają szablon realizatora z miejscami zastępczymi, a przy tworzeniu nowego projektu razem tworzy się agenta, dokument planu oraz dokument z zadaniami. Otrzymujemy w ten sposób określony protokół: czytamy umowę, bierzemy elementy w odpowiedniej kolejności, pomijamy to, co jest zablokowane, utrzymujemy aktualny stan realizacji, działamy w ramach zakresu i na końcu składamy raport. Te zasady nigdy się nie zmieniają pomiędzy projektami, ponieważ opisują sam proces delegowania i nic nie mówią o twoim kodzie.
Po tym każda kopia tworzy własną sekcję dla swojej powierzchni awarii, a umieszczenie dwóch obok siebie jest pouczające. Szablon nakazuje agencie utrzymywanie zestawu testów w stanie „zielonym”. Jeden projekt w ogóle nie posiada takiego zestawu – jest to repozytorium promptów, a jego jedynym plikiem wykonywalnym jest walidator. Dlatego jego twórca mówi coś zupełnie innego: repozytorium zawiera prompty i dane, a nie kod; edycja pliku to edycja promptu; sformułowanie, kolejność i akcenty stanowią implementację; a przepisanie tekstu, które jest lepsze w odbiorze przy jednoczesnym usunięciu surowej ograniczenia, jest regresją, której nic nie wykryje, ponieważ nie istnieją ani budowa, ani testy.
Kopia innego projektu otrzymała instrukcję, by przed pisaniem kodu przeanalizować decyzje z pliku PLAN.md, do których odnosi się dane zadanie, a także pole do raportowania w przypadku potrzeby interwencji Opus lub człowieka. Protokół jest taki sam, ale zagrożenia się różnią.
To jest podział, który należy zapamiętać. Część wielokrotnie używalna podagenta to jego protokół, a część specyficzna dla projektu to jego powierzchnia awarii. Ustal protokół za pomocą szablonu, drugą część zapisz ręcznie i nie próbuj, aby jeden plik obejmował oba elementy.
Skieruj agenta na wiedzę, a nie wklejaj jej do niego
Tutaj umiejętności spotykają się z podagentami, a koncepcja stała się znacznie bardziej konkretna, gdy od niej zaczęła zależeć rzeczywista ścieżka przetwarzania.
Moja wcześniejsza rada polegała na nazwaniu odpowiedniej umiejętności wewnątrz ciała agenta. Lepszym rozwiązaniem jest zasada bardziej rygorystyczna: agent czyta wiedzę w czasie wykonywania, zanim może podjąć działanie, a prompt wyjaśnia powód.
Agent badawczy nie może przeprowadzić żadnego wyszukiwania, dopóki nie przeczyta tabeli routingu przechowywanej w ramach danej umiejętności. Instrukcja jest oznaczona jako obowiązkowa i stanowi, że przed każdym wyszukiwaniem lub pobieraniem danych należy przeczytać tabelę przy pierwszej dostępnej ścieżce; nie wolno tego pominąć; nie wolno kierować zapytania na podstawie pamięci, ponieważ moduły się zmieniają, podczas gdy prompt pozostaje niezmienny: ten, który pamiętamy, może już nie istnieć, a ten, którego potrzebujemy, może jeszcze nie powstać.
To stwierdzenie o zmianie listy podczas niezmienionego promptu stanowi pełne uzasadnienie dla tego wzorca. Wiedza (które źródła odpowiadają na jakie rodzaje pytań, jak je wysyłać, co jest znane jako zablokowane) zmienia się co miesiąc, podczas gdy metoda pozostaje niezmienna. Jeśli w ciele agenta zaimplementuje się listę źródeł, każde nowe źródło zmusza do edycji promptu, który w przeciwnym razie pozostałby niezmieniony, a agent będzie z pewnością kierował zapytania do modułu usuniętego już w marcu.
Two mechaniki okazały się ważniejsze, niż się spodziewano.
Kandydaci w kolejności, a nie jedna ścieżka. Aplikacja działa w projektach zorganizowanych inaczej, na dwóch maszynach pod różnymi nazwami użytkowników, skonfigurowanych przez różnych instalatorów. Dlatego instrukcja wymienia lokalizacje kandydatów w kolejności i zaleca wybranie pierwszej dostępnej, priorytetowo kopiów lokalnych projektu przed tymi na poziomie użytkownika. Jeśli zaimplementuje się sztywną ścieżkę, wszystko będzie działać tylko na jednej maszynie.
Literowe nazwy łączą poszczególne warstwy, a nic ich nie weryfikuje. Projekt składa się z trzech poziomów: umiejętności koordynują działanie, agent wykonywa pracę, a moduły danych przechowują wiedzę. Nie ma żadnych importów. Umiejętność uruchamia agenta pod jego dokładnie zarejestrowaną nazwą, natomiast agent znajduje moduły za pomocą ścieżki. To sprawia, że repozytorium zawiera najprostsze, ale jednocześnie najniebezpieczniejsze zalecenie – należy unikać przemiany nazwy agenta do wyszukiwania w sieci, ponieważ istniejące aplikacje korzystają z niego bezpośrednio.
Nazwa agenta pełni rolę publicznego API, a żaden narzędzie o tym nie informuje: nie ma kompilatora, żadnych testów ani ostrzeżeń. Przemiana nazwy wygląda jak zwykły commit, ale powoduje awarie we wszystkich aplikacjach korzystających z agenta w każdym repozytorium, w którym został zainstalowany, a o problemie dowiadujemy się dopiero następnym razem, gdy zlecamy zadanie badawcze i odpowiada agent ogólny.
Gdzie znajdują się pliki: osobiste, projektowe, spakowane
Istnieją trzy poziomy, a na trzecim mieszkają wszyscy prawdziwi agenci.
- Personalny (
~/.claude/agents/) przeznaczony jest dla specjalistów ogólnych potrzebnych we wszystkich projektach. Traktuj go jak warsztat, gdzie nie ma problemu z psuciem rzeczy. - Projektowy (
.claude/agents/, zcommitowany) służy specjalistom, którzy mają sens tylko w jednym kodzie, np. implementatorowi świadomemu, że projekt nie ma testów. Zcommituj go, a będzie czekał na ciebie przy powrocie, nawet po czterech miesiącach, gdy projekt już wyjdzie ci z głowy. - Opakowany (zainstalowany przez menedżera pakietów i przytwierdzony do konkretnej wersji) sprawia, że agent staje się zależnością. To poziom, o którym nikt nie wie, że jest potrzebny, dopóki ten sam agent nie znajdzie się w tuzinie repozytoriów, a trzynaście jego kopii nie zacznie się od siebie oddalać.
Trzeci poziom zmienia kilka rzeczy, więc lepiej je znać, zanim tam dotrzesz.
Łącz agenta z umiejętnościami, które go uruchamiają. Pakiet zawiera je oba jako jedną całość z prostego powodu: umiejętności zainstalowane bez odpowiednich agentów tworzą proces, który zawodzi przy pierwszym użyciu. Umiejętność, która próbuje skierować żądanie do brakującego agenta, oznacza błędną instalację, przy czym w najlepszym przypadku pojawia się czytelne komunikat o błędzie. Są one jedną całością, ponieważ stanowią jeden kontrakt.
Dowiedz się, co robi twój instalator z plikami. Ten pakiet jest instalowany za pośrednictwem APM firmy Microsoft, które przekształca każdy plik .md znajdujący się w katalogu agents/ w odrębnego agenta najwyższego poziomu. To ustawienie domyślne jest rozsądne, ale nadal powoduje problemy. Jeśli umieścisz tam plik danych, każdy projekt korzystający z niego otrzyma fałszywego zarejestrowanego agenta. Jeśli natomiast napiszesz agent specyficzny dla danego projektu, ten zainstaluje się we wszystkich repozytoriach. Z tego powodu moduły strategii wyszukiwania znajdują się w katalogu skills/, a nie w folderze agents/, gdzie wydawałoby się, że powinny być – w agents/ struktura tych modułów zostałaby utracona podczas instalacji, a co więcej zarejestrowano by pięć fałszywych agentów dla każdego projektu korzystającego z nich.
Zakotwicz komit i pamiętaj, że konsumenty nadążają z opóźnieniem. Konsumenty polegają na wartości SHA, więc poprawka nie jest dostępna dla nikogo, dopóki zakotwiczenie nie zostanie zmienione i instalacja nie zostanie ponownie przeprowadzona. Napisanie poprawki to nie to samo, co jej wdrożenie. Na stronie wydaje się to oczywiste, ale o północy, gdy błąd naprawiony w zeszłym tygodniu ponownie się pojawia, jest zupełnie inaczej.
Mimo to należy przeprowadzać oczyszczanie. Katalog pełen nakładających się, na wpół zapomnianych agentów generuje tylko hałas zamiast przydatnych narzędzi. Połącz te dwa, które znalazły się w tym samym zadaniu. Usuń ten, który nie był uruchamiany od miesięcy, ponieważ historia git utrzyma go, jeśli okazuje się, że usunięcie było błędne. To również przyzwoita rada życiowa, ale jest ignorowana w przypadku prawdziwego kosza na śmieci w domu.
Ta sama idea w innych narzędziach
Claude Code nie jest jedynym miejscem, gdzie to występuje. Jeśli przechodzisz między różnymi narzędziami, te idee przenoszą się tam, nawet jeśli formaty plików się różnią.
GitHub Copilot i VS Code nazywają je spersonalizowanymi agentami, przechowywanymi jako pliki .agent.md, zazwyczaj w katalogu .github/agents/, z opcją utworzenia osobistej biblioteki w katalogu użytkownika. Frontmatter zawiera więcej pól niż w przypadku Claude’a: oprócz poprzedniego name, description i tools dostępne są argument-hint, model, user-invocable, disable-model-invocation oraz, co najważniejsze, handoffs. Gotowy agent może wyświetlać przycisk, który przekazuje zadanie innemu agentowi z już wypełnionym następnym poleceniem, dzięki czemu planowanie, implementacja i przegląd odbywają się łącznie, bez łączenia się w jeden chaotyczny agent. Pułapka, jeśli spojrzy się na starsze przykłady: dawne pole infer przekształciło się w dwa oddzielne pola, user-invocable i disable-model-invocation – zmiana, która z perspektywy czasu wydaje się schludna, ale na początku jest myląca.
Kolejnym twierdzeniem, na które natrafisz, jest to, że VS Code rozpoznaje pliki .claude/agents/ i tłumaczy nazwy narzędzi, dzięki czemu jeden agent może obsługiwać oba narzędzia bez żadnych kosztów. To prawda, ale może wprowadzać w błąd. Słownictwo narzędzi się nie pokrywa, a zapytanie, które zakazuje użycia narzędzi podając ich nazwy, jak to robi każdy dojrzały agent, nie przetrwa automatycznego tłumaczenia bez uszkodzeń.
Zamiast tego dostępny jest jedno kanoniczne zapytanie wraz z prostym, lokalnym narzędziem pomocniczym dla każdego narzędzia. Cały agent po stronie Copilota w tym pakiecie składa się z jedynie jedenastu linijek:
---
name: Web Research Writer
description: "Use for bounded web research that must read a local schema, search and fetch current sources, write one designated result file, and validate it with a local command."
tools: [read, search, web, edit, execute]
user-invocable: false
disable-model-invocation: false
---
Load the installed canonical research prompt from the first existing candidate:
1. `.github/agents/web-search-agent.agent.md`
2. `.claude/agents/web-search-agent.md`
Follow its search budgets, module routing, source standards, tool discipline, output, and validation rules. Ignore that file's incompatible `tools` frontmatter; this wrapper's Copilot-native tool categories govern this session.
To jest cały schemat. Natywny frontmatter umożliwia hostowi prawidłowe zarejestrowanie agenta, drabina ścieżek pomaga znaleźć rzeczywisty prompt, a jedno proste zdanie określa, który słowniczek narzędzia ma pierwszeństwo. Wszystkie 188 linii zgromadzonego zachowania znajduje się w jednym pliku, a drugie narzędzie otrzymuje wskaźnik zamiast oddzielnego pliku. Dwie kopie promptu tworzą dwa oddzielne prompty, a w dniu, w którym jeden z nich otrzyma poprawkę błędu, a drugi nie, zaczynają one przedstawiać się jako jeden agent.
W dokumencie README projektu wskazano na jeden problem. Jeśli skieruje się loader na katalog .github/agents/, kanoniczny prompt zostanie zarejestrowany jako samodzielny agent, przez co Copilot może pokazywać podwójne nazwy: „Web Research Writer” oraz plik kanoniczny poniżej niego. Należy wybrać jeden katalog domowy dla każdego narzędzia albo przechowywać plik kanoniczny w katalogu .claude/agents/, gdzie automatyczne wykrywanie przez Copilota go ignoruje.
Wszystko inne, w tym Cursor i Windsurf, kieruje się w tym samym kierunku pod nazwami takimi jak zasady, tryby czy agenci. Szczegóły zmieniają się tak często, że odsyłanie do aktualnej dokumentacji każdego narzędzia jest lepsze niż pewne stwierdzenia na temat zmian z zeszłego miesiąca. Podstawa pozostaje niezmienna: plik wielokrotnego użycia, który definiuje rolę i jest celowo wywoływany. Naucz się tego raz, a resztą jest już tylko znalezienie folderu, w którym każde narzędzie przechowuje swoje dane.
Jak naprawdę tworzy się dobre rozwiązania
Każdy z tych podagentów zaczynał od zbyt szerokiego zakresu. Był „recenzent”, który sprawdzał wszystko, „planista”, który nie miał pojęcia, jak powinien wyglądać plan, oraz „badacz”, który podchodził do każdego błędu tak samo jak do poprzedniego. To nie jest porażka – to punkt wyjścia.
Część przydatna, ta, która mogłaby pomóc rok temu, to nie „iteracja”. Wszyscy mówią o iteracji – to właśnie z nich składają się iteracje.
Przeczytaj ponownie powyższe pliki agenta i zwróć uwagę, gdzie znajdują się poszczególne elementy. Akapit opisujący rolę, strona z ograniczeniami, schemat z zapisanymi nazwami kluczy, reguła mechaniczna służąca do wykrywania, liczbowy budżet z zapisem zakazu manipulacji nim, uwaga o konieczności ujawniania płatnych zleceń, a także zakaz wyjaśniający, co instalator robi z błędami. Prawie wszystkie te elementy odnotowują jeden konkretny problem, który miał miejsce w pewnym momencie.
Po nieudanym wyniku kluczowym pytaniem nie jest już to, jak lepiej sformułować rolę. Należy zapytać, co dokładnie zrobił agent, która część pliku na to pozwoliła oraz jakie zasady zdaniowe wykluczą to w przyszłości. Setka kart w przeglądarce. Dziesięć wyników spoza domeny bez błędów. Instrukcja, która nie miała gdzie umieścić odpowiedzi. Weryfikacja zgłoszona, ale nigdy nie przeprowadzona. Każdy z tych elementów staje się wierszem, a ten wiersz przetrwa sesję, która go nauczyła – to właśnie ma na celu przechowywanie go w pliku.
Ta sama procedura sprawdzania obowiązuje przed zatrzymaniem agenta tak samo jak przed zatrzymaniem umiejętności: czy jego zadanie można sformułować w jednym zdaniu? Jeśli nie, jest zbyt szerokie, a w jednym „trenchcoat” znajdują się dwa mniejsze agenty. Aby ocenić, czy jest naprawdę dobry, potrzebna jest inna procedura: gdy popełnia błąd, czy można wskazać wiersz, który mu na to pozwolił? Jeśli nie, to jeszcze nie jest specjalistą, tylko tylko „nastrojem” z metadanymi.
Łącząc je, unikasz konieczności ciągłego proszenia tego samego bardzo zdolnego specjalisty o pomoc. Masz wtedy małą grupę specjalistów, którzy już rozumieją twój świat oraz swoje obowiązki. Dla osoby, która chce osiągnąć więcej, niż rozsądnie pozwala na to jedna osoba, jest to najbliższe możliwe rozwiązanie polegające na uzyskaniu pomocy bez faktycznego zatrudniania kogoś.
Spójrz na pracę, która według ciebie powinna zostać wykonana gdzie indziej – to podagent, który wciąż czeka na uratowanie. A ostatni raz, gdy podagent cię zawiodł, oznaczał to, że wciąż czeka na napisanie określonej linijki kodu.
Literatura pokrewna
- Praktyczne notatki: Przewodnik krok po kroku dla rozwoju swojego osobistego agenta — Szczegółowy opis Praktycznych notatek: Przewodnika krok po kroku dla rozwoju swojego osobistego agenta: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: Qwen3.8–27B jako nowy agent do programowania z SGLang/vLLM — Szczegółowy opis Praktycznych notatek: Qwen3.8–27B jako nowego agenta do programowania z SGLang/vLLM: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.