12 zasad budowy agentów AI

Ten wpis powstał przy okazji. Przygotowywałem się do egzaminu Claude Certified Architect Foundations i po drodze zbudowałem sobie ściągę z powtarzających się wzorców odpowiedzi. Po kilku podejściach do testów próbnych zobaczyłem rzecz, której się nie spodziewałem.

Ten egzamin prawie nie sprawdza wiedzy encyklopedycznej. Sprawdza osąd. Każde pytanie ma jedną najlepszą odpowiedź i trzy wiarygodne pułapki, a o wyborze prawie zawsze decyduje ta sama garstka reguł. Nauczyłem się ich, żeby zdać. Zostały mi, bo to po prostu opis tego, jak buduje się agentów, którzy nie umierają w drugim tygodniu.

Wykładam całą ściągę. Zaczynam od dwunastu zasad w formie, w jakiej ich używam: co robić i jaka wersja tej samej decyzji jest pułapką. Potem pokazuję siedem pułapek, które wracały w kółko, schodzę na poziom pięciu domen i kończę tabelą faktów.

Nie musisz podchodzić do żadnego egzaminu, żeby ci się przydały. Jeśli podchodzisz, tym lepiej.

Dwanaście zasad

Determinizm wymuszaj kodem

Jeśli reguła musi zadziałać za każdym razem (zweryfikuj tożsamość przed zwrotem pieniędzy, zablokuj zwrot powyżej progu, nigdy nie ruszaj plików źródłowych), to nie jest zadanie dla promptu.

Rób: hook, gate przed wywołaniem, lista dozwolonych narzędzi. Kod daje gwarancję.

Pułapka: „wzmocnij prompt systemowy", „napisz, że to obowiązkowe". Prompt ma niezerową awaryjność.

Wybierz najtańszą poprawkę, która trafia w przyczynę

Zanim zbudujesz podsystem, sprawdź, czy problemu nie rozwiązuje lepszy opis, jawne kryterium albo zmiana konfiguracji.

Rób: najmniejsza dźwignia, która rusza prawdziwą przyczynę.

Pułapka: klasyfikator, warstwa routingu albo fine-tune, zanim ktokolwiek dotknął promptu.

Zły wybór narzędzia? Zacznij od opisów

Opis narzędzia to główny mechanizm, którym model decyduje, czego użyć. Jak model wybiera źle, to najczęściej opis jest za ubogi.

Rób: dopisz format wejścia, przykładowe zapytania, przypadki brzegowe i różnicę wobec podobnego narzędzia.

Pułapka: najpierw few-shot albo router po słowach kluczowych.

Przeinżynierowanie to prawie zawsze zła odpowiedź

Nowy błyszczący podsystem rzadko bije poprawkę promptu albo zawężenie zakresu. Dopasuj wysiłek do problemu.

Rób: najpierw prompt i konfiguracja, potem architektura.

Pułapka: klasyfikator ML, analiza sentymentu, trening własnego modelu, „weźmy większy model".

Większe okno kontekstu to nie lepsza uwaga

Większe okno ani wyższy model nie naprawiają rozproszenia uwagi, gubienia środka wejścia ani chaotycznego przeglądu wielu plików.

Rób: dekompozycja, przycinanie, zawężanie zakresu, struktura.

Pułapka: „użyjmy modelu z większym oknem, to wszystkie pliki dostaną uwagę".

Sentyment i pewność siebie modelu to nie sygnały

Nie eskaluj dlatego, że klient napisał ostro. Nie routuj po tym, jak model sam ocenia swoją pewność w skali 1 do 10. Ta ocena jest źle skalibrowana i na trudnych przypadkach model bywa pewny swego, będąc w błędzie.

Rób: jawne kryteria i few-shot. Pewność kalibruj na oznaczonym zbiorze walidacyjnym.

Pułapka: auto-eskalacja po negatywnym sentymencie, próg na samoocenie.

Niezależna instancja bije autorecenzję

Świeży model, który nie widział, jak powstawał kod, łapie więcej niż ten sam model proszony o sprawdzenie samego siebie.

Rób: druga instancja bez kontekstu generowania.

Pułapka: „dodaj krok autorecenzji", „włącz rozszerzone myślenie, to znajdzie swoje błędy".

Najmniejsze potrzebne uprawnienia

Każdy agent dostaje narzędzia swojej roli. Cztery czy pięć, nie osiemnaście. Im więcej narzędzi, tym gorszy wybór.

Rób: zawężaj do roli. Dorzuć jedno wąskie narzędzie międzyrolowe, gdy jakaś potrzeba wraca często.

Pułapka: „dajmy mu wszystko, to sobie poradzi z każdym zadaniem".

Struktura bije wolny tekst. Wszędzie

Ustrukturyzowane błędy (kategoria, czy da się ponowić, wynik częściowy), ustrukturyzowane wyjście, ustrukturyzowane przekazania między agentami, jawna proweniencja.

Rób: daj następnemu w kolejce dokładnie te pola, których potrzebuje.

Pułapka: „Operation failed" albo streszczenie prozą, które gubi identyfikatory, kwoty, źródła i daty.

Nie tłum błędów i nie panikuj

Dwa lustrzane grzechy. Pierwszy to złapać wyjątek i zwrócić pustkę jako sukces. Drugi to ubić cały workflow, bo jednemu subagentowi minął timeout.

Rób: lokalnie odratuj to, co przejściowe. Resztę przekaż z kontekstem wyżej i pozwól koordynatorowi zdecydować.

Pułapka: pusty wynik udający sukces albo jeden timeout, który przewraca wszystko.

Dopasuj API do wymagań opóźnienia

Batch API kosztuje o połowę mniej, ale idzie do 24 godzin, nie ma SLA na czas i nie obsługuje wywołań narzędzi w trakcie.

Rób: synchronicznie to, co blokuje człowieka. Batchem to, co może poczekać do rana.

Pułapka: przeniesienie blokującego sprawdzenia przed mergem na Batch API „dla oszczędności".

Ponowienie naprawia format, nie brakujące dane

Ponowienie z informacją o błędzie świetnie naprawia zły format i złamaną strukturę. Nie wyczaruje informacji, której nie ma w źródle.

Rób: zrób pole nullowalne, żeby model zwrócił null zamiast zmyślać.

Pułapka: kolejne ponowienia ekstrakcji z dokumentu, którego nigdy nie podałeś.

Siedem pułapek, które wracają

Złe odpowiedzi też mają swoje wzorce. Te siedem wracało w kółko, w różnych przebraniach.

„Wzmocnij prompt systemowy" / „napisz, że to obowiązkowe"

Podsuwane zawsze tam, gdzie wymagany jest determinizm.

Prompt jest probabilistyczny, czyli to dokładnie ta awaria, którą opisuje pytanie. Wymuś w kodzie.

„Dodaj przykłady few-shot"

Podrzucane jako łatka na ubogi opis albo na twardą regułę.

Few-shot jest dobry na niejednoznaczny osąd, format i fałszywe alarmy. Nie na opisy narzędzi ani na reguły, które muszą zawsze zadziałać.

„Wytrenuj klasyfikator / model / sentyment / fine-tune"

Ciężka opcja z półki ML.

Przeinżynierowane, zanim ktoś sprawdził tanie dźwignie w prompcie i konfiguracji. Przy okazji: sentyment to nie złożoność sprawy.

„Użyj większego okna / wyższego modelu"

Sprzedawane jako lek na uwagę rozproszoną po wielu plikach.

Rozmiar okna nie naprawia rozproszenia uwagi ani braku dekompozycji. Podziel robotę.

„Scal wszystko w jedno mega-narzędzie"

„Zróbmy jedno narzędzie, które ogarnia wszystko."

Gdy lekarstwem jest rozróżnienie opisów albo rozbicie narzędzia, scalanie pogarsza wybór.

„Ogólny błąd / pusty sukces / ubij workflow"

Trzy złe kształty obsługi błędu.

Kolejno: ukrywa kontekst, tłumi awarię, przesadza z reakcją. Zwróć ustrukturyzowany kontekst błędu.

„Polegaj na kolejności / ponawiaj na ślepo / cachuj spekulacyjnie"

Skróty przy batchu i weryfikacji.

Koreluj przez custom_id. Ponawiaj tylko błędy do naprawienia. Nie zgaduj, co cachować.

WSPÓŁPRACA

To robię na co dzień — doradzam przy strategii AI i buduję agentów, którzy przeżywają demo.

Doradztwo AI Wdrożenia AI

Pięć domen egzaminu

Zasady wyżej rozstrzygają większość pytań. Reszta ściągi schodzi głębiej. Podaję wagi z publicznego przewodnika i niczego nie skracam, bo to najlepsza mapa tego, co realnie trzeba umieć.

Domena 1 · Architektura agentowa i orkiestracja

27% · najcięższa domena

Sterowanie pętlą · stop_reason

Kontynuuj, dopóki leci tool_use (dopisz wynik narzędzia), zatrzymaj się na end_turn. Nigdy nie kończ pętli, parsując tekst naturalny ani na sztywnym limicie iteracji.

Równoległe subagenty · potrzebna współbieżność

Wyślij wiele wywołań Task w JEDNEJ odpowiedzi asystenta, nie w kolejnych turach. allowedTools musi zawierać Task.

Przekazywanie kontekstu · subagent „zapomniał"

Subagenty nie dziedziczą kontekstu. Podaj wcześniejsze ustalenia wprost w prompcie, a metadane źródeł trzymaj jako dane strukturalne.

Koordynator · hub and spoke

Cała komunikacja idzie przez koordynatora. Raport, w którym brakuje całych podtematów, znaczy zwykle jedno: dekompozycja była za wąska.

Hooki wymuszające · obowiązek albo polityka

Gate wstępny na kolejność. Hook przechwytujący, żeby zablokować wywołanie łamiące politykę (zwrot powyżej progu) i eskalować. Hook PostToolUse, żeby ujednolicić formaty czasu i statusów.

Dekompozycja · przewidywalne czy otwarte

Łańcuch promptów do przewidywalnych, wieloaspektowych zadań. Podejście dynamiczne (zmapuj, ustal priorytety, dostosuj) do otwartego śledztwa.

Sesje · wznowić czy zacząć od nowa

--resume nazwanej sesji, gdy kontekst jest wciąż ważny. fork_session na rozbieżne gałęzie. Świeży start ze wstrzykniętym podsumowaniem, gdy wyniki narzędzi się zdezaktualizowały.

Przekazanie człowiekowi · eskalacja

Oddaj ustrukturyzowane podsumowanie: identyfikator klienta, przyczyna źródłowa, kwota, rekomendowane działanie.

Domena 2 · Projektowanie narzędzi i integracja MCP

18%

Wybór narzędzia · model bierze złe

Najpierw rozszerz, przemianuj albo rozbij opisy.

Błędy MCP · narzędzie padło

isError plus strukturalne metadane: errorCategory (przejściowy, walidacja, biznesowy, uprawnienia) i isRetryable. Odróżnij brak dostępu od poprawnie pustego wyniku. Reguła biznesowa to retriable:false plus przyjazny komunikat.

Dystrybucja · za dużo narzędzi

Zawęź do roli. Zamień ogólny fetch_url na ograniczony load_document. Dorzuć jedno wąskie narzędzie międzyrolowe na częstą potrzebę.

tool_choice · wymuszenie zachowania

auto (może odpowiedzieć tekstem) · any (musi wywołać jakieś narzędzie) · {type:tool,name} (musi wywołać to konkretne).

Zasięg MCP · gdzie mieszkają serwery

.mcp.json to projekt i współdzielenie (${ENV} na sekrety), ~/.claude.json to prywatne. Narzędzia wszystkich serwerów są dostępne naraz. Zasoby MCP wystawiają katalogi, co ucina zapytania rozpoznawcze. Wzbogać opisy, żeby agent wolał je od Grepa.

Narzędzia wbudowane · którego użyć

Grep to szukanie po treści · Glob po wzorcu nazwy · Read/Write na cały plik · Edit na unikalne dopasowanie. Gdy dopasowanie nie jest unikalne, idź w Read+Write.

Domena 3 · Konfiguracja i workflow Claude Code

20%

Hierarchia CLAUDE.md · kolega tego nie dostał

~/.claude/CLAUDE.md jest prywatny i nie idzie przez VCS. Przenieś konwencje do .claude/CLAUDE.md w projekcie albo do korzenia repo, żeby wczytał je każdy klon.

Reguły per ścieżka · konwencje na rozrzuconych plikach

.claude/rules/ z globami w polu paths: (**/*.test.tsx) wczytuje się po typie pliku w wielu katalogach. Bije CLAUDE.md per katalog.

Komendy · wspólne czy prywatne

.claude/commands/ to projekt (idzie przez VCS), ~/.claude/commands/ to prywatne. Tablica komend w .claude/config.json nie istnieje.

Skille · co daje frontmatter

context: fork izoluje gadatliwe wyjście · allowed-tools deterministycznie ogranicza narzędzia · argument-hint dopyta o brakujący argument. Skille wczytują się na żądanie, CLAUDE.md zawsze.

Plan czy wprost · jak duże to jest

Tryb planowania na duże, architektoniczne, wieloplikowe i wielowariantowe. Wykonanie wprost na małe i dobrze zakreślone. Do gadatliwego rozpoznania użyj subagenta Explore.

Doprecyzowanie · jak sterować

Konkretne przykłady wejścia i wyjścia biją prozę. TDD przez wspólne czerwone testy. Wzorzec wywiadu. Poprawki, które na siebie wpływają, wrzuć w jedną wiadomość, niezależne rób po kolei.

Integracja z CI · uruchomienia automatyczne

-p/--print na tryb nieinteraktywny · --output-format json plus --json-schema na deterministyczne bramki. Podaj wcześniejsze ustalenia, żeby nie dublować komentarzy. Niezależna instancja recenzuje lepiej niż autor.

Domena 4 · Prompt engineering i wyjście strukturalne

20%

Precyzja · mniej fałszywych alarmów

Jawne kryteria kategorii z przykładami kodu biją „bądź konserwatywny" i filtry po pewności. Kategorię z wysokim odsetkiem fałszywych alarmów wyłącz na czas naprawy jej promptu.

Few-shot · 2 do 4 przykładów

Na przypadki niejednoznaczne, spójność formatu, cięcie fałszywych alarmów i zróżnicowaną strukturę dokumentów. Generalizuje się na nowe wzorce.

Wyjście strukturalne · pewny JSON

tool_use plus schemat JSON eliminuje błędy składni, ale nie semantyki (pozycje, które się nie sumują). tool_choice:any, gdy typ dokumentu jest nieznany.

Anty-konfabulacja · brakujące pola

Zrób pola opcjonalne albo nullowalne, żeby model zwrócił null zamiast zmyślać. Dodaj enum other ze szczegółem albo unclear.

Ponowienie z walidacją · samokorekta

Dopisz nieudaną ekstrakcję i konkretne błędy. Działa na format i strukturę, nie na informację, której nie ma w źródle.

Batch · duże wolumeny

Połowa ceny, do 24 godzin, bez SLA, bez wywoływania narzędzi w trakcie. Na noc tak, blokująco nie. Koreluj przez custom_id. Wysyłaj ponownie tylko nieudane identyfikatory, a za duże podziel.

Architektura recenzji · duże PR-y

Przebieg lokalny per plik plus osobny przebieg integracyjny między plikami. Niezależna instancja bije autorecenzję.

Domena 5 · Zarządzanie kontekstem i niezawodność

15%

Zachowaj fakty · długie rozmowy

Trzymaj trwały blok faktów sprawy (kwoty, daty, identyfikatory) poza streszczaną historią. Przycinaj gadatliwe wyniki narzędzi do potrzebnych pól. Kluczowe podsumowanie dawaj na początek, z nagłówkami sekcji.

Eskalacja · kiedy oddać człowiekowi

Wyraźną prośbę o człowieka uszanuj natychmiast, bez śledztwa. Eskaluj przy luce w polityce albo braku postępu. Przy wielu dopasowaniach poproś o dodatkowy identyfikator, nie zgaduj. Nie po sentymencie i nie po samoocenie.

Propagacja błędów · wiele agentów

Ustrukturyzowany kontekst: typ awarii, próbowane zapytanie, wyniki częściowe, alternatywy. Przejściowe ratuj lokalnie. Nigdy nie tłum i nie przewracaj całego workflow.

Duże repo · degradacja kontekstu

Pliki brudnopisu · delegowanie do subagentów · streszczanie między fazami · /compact · odtwarzanie po crashu z manifestu.

Recenzja ludzka · kalibracja

Zbiorcza dokładność ukrywa awarie per typ i per pole. Używaj warstwowego losowania. Pewność na poziomie pola kalibruj na oznaczonym zbiorze. Przypadki niepewne i sprzeczne kieruj do ludzi.

Proweniencja · synteza z wielu źródeł

Przeprowadź mapowanie teza do źródła przez całą syntezę. Sprzeczne dane opisz z ich źródłami, nie wybieraj jednego. Wymagaj dat publikacji, żeby różnica w czasie nie udawała sprzeczności. Finanse renderuj tabelą, newsy prozą.

Fakty i flagi do rozpoznania na pierwszy rzut oka

Na koniec surowa tabela. Rzeczy, które albo się wie, albo się zgaduje. Ostatni wiersz lubię najbardziej: zebrałem w nim „funkcje", które nie istnieją, a brzmią zupełnie wiarygodnie.

Rzecz	Co zapamiętać
`stop_reason`	`tool_use` to uruchom narzędzie i wróć do pętli · `end_turn` to koniec.
Claude Code CLI w CI	`-p`/`--print` nieinteraktywnie · `--output-format json` · `--json-schema`.
Message Batches API	Połowa ceny · do 24 godzin · BEZ SLA na czas · BEZ wywoływania narzędzi w trakcie · korelacja przez `custom_id`.
`tool_choice`	`auto` / `any` / `{"type":"tool","name":"…"}`.
Pliki konfiguracji Claude Code	`.claude/rules/` (glob w `paths:`) · `.claude/commands/` · `~/.claude/commands/` · `.claude/skills/` z SKILL.md.
Frontmatter skilla	`context: fork` · `allowed-tools` · `argument-hint`.
Hierarchia CLAUDE.md	`~/.claude/CLAUDE.md` (prywatny, nieudostępniany) → `.claude/CLAUDE.md` w projekcie lub korzeń → podkatalog. `@import` do modularyzacji · `/memory` do podglądu.
Sesja i kontekst	`--resume` · `fork_session` · `/compact` · subagent `Explore`.
MCP	`.mcp.json` (projekt) kontra `~/.claude.json` (użytkownik) · rozwijanie `${ENV}` · zasoby MCP to katalogi · `isError` · `errorCategory` · `isRetryable`.
Narzędzia wbudowane	`Read · Write · Edit · Bash · Grep · Glob`.
Wzorce schematów	Pola nullowalne i opcjonalne · enum `other`/`unclear` · `calculated_total` kontra `stated_total` · `conflict_detected`.
⚠ „Funkcje", których NIE MA	Zmienna `CLAUDE_HEADLESS` · flaga `--batch` w Claude Code · tablica komend w `.claude/config.json`.

Co z tego zostaje

Jak się na to popatrzy z góry, dwanaście zasad zwija się do trzech zdań.

Co musi zadziałać zawsze, zapisz w kodzie, nie w prośbie. Dopasuj wielkość poprawki do wielkości problemu. Przekazuj strukturę, nie prozę.

Cała reszta to warianty tych trzech. I żadna z nich nie jest wiedzą egzaminacyjną. To lista rzeczy, na których projekty agentowe wykrwawiają się w produkcji, spisana przypadkiem przy okazji nauki do testu.

Skąd to jest. Notatki własne z przygotowań do egzaminu Claude Certified Architect Foundations, opartego na publicznym przewodniku egzaminacyjnym. To materiał nieoficjalny, niepowiązany z Anthropic ani przez Anthropic nierekomendowany. Zasady opisują moją praktykę, nie treść egzaminu.

12 zasad budowy agentów. Notatki z przygotowań do certyfikatu Anthropic