Watch This If Your Coding Agent is Ignoring Your Rules (You Need Hooks)

O czym jest ten film

Hooki to najbardziej niedoceniany element asystentów kodowania — autor twierdzi, że widział systemy AI setek programistów i całych firm, i niemal nigdy nie były wykorzystywane wystarczająco.
Kluczowe słowo materiału: gwarancja. Reguły i skille są tylko wskazówką dla modelu, hooki są deterministyczne.
Hooki to akcje uruchamiane przy określonych zdarzeniach w cyklu pracy agenta — przed użyciem narzędzia, po nim, przy starcie sesji, przy zakończeniu rozmowy.
Prymityw jest międzynarzędziowy: obsługują go Claude Code, Codex i Pi. To jeden z pięciu podstawowych komponentów „warstwy AI”: reguły, subagenci, serwery MCP, skille i hooki.
Przykład sztandarowy: hook typu stop, który po zakończeniu pracy agenta uruchamia pełny zestaw testów i wymusza powrót do pracy, jeśli coś jest czerwone.
Drugi przykład: hook pre-tool use blokujący odczyt pliku .env, żeby klucze API nigdy nie trafiły do kontekstu modelu.
Komunikacja hooka z agentem odbywa się przez kod wyjścia: 0 oznacza „przechodzi”, 2 oznacza blokadę wraz z komunikatem zwrotnym, na który agent może zareagować.
Autor przywołuje badanie pokazujące, że samo dokładanie reguł pogarsza wyniki agenta, a dokładanie hooków („middleware”) je poprawia.
Sedno materiału: audyt własnych reguł według pytania „czy ta linijka nazywa zdarzenie, czy koduje osąd?”. Zdarzenia wyprowadzamy do hooków, osądy zostają regułami, reszta idzie do kosza.
Autor pokazuje własny skill /hooks create, któremu wystarczy wkleić problematyczną regułę, żeby zbudował gotowy hook i wpiął go do settings.json.

Redakcyjne tłumaczenie

Najbardziej niedoceniany element asystenta kodowania

Najbardziej niedocenianym elementem każdego asystenta kodowania AI są hooki. Widziałem osobiście systemy pracy z AI u setek programistów i w całych firmach — i praktycznie za każdym razem hooki były wykorzystywane w zbyt małym stopniu. Są niesamowicie potężne i prawie zawsze pomijane. W tym materiale chcę pokazać, czym hooki są, dlaczego mają tak dużą wartość i jak zbudować własne, żeby uczynić swoje przepływy pracy z AI bardziej niezawodnymi — poprzez wbudowanie w nie gwarancji. To jest słowo klucz na dziś. I powiem od razu: to najczęściej zamawiany temat na moim kanale, więc cieszę się, że w końcu się nim zajmujemy.

Hooki będę uszczegóławiał w trakcie całego materiału, ale na start szybka definicja: hooki to akcje, których wykonanie chcemy zagwarantować przy określonych zdarzeniach zachodzących wewnątrz agenta kodującego. Istnieje całe menu takich zdarzeń, do którego jeszcze dojdziemy. Przykładowo: tuż przed tym, jak agent zamierza odczytać plik, albo dokładnie w momencie zakończenia rozmowy, odpalamy akcję, która może przeprowadzić audyt, zablokować coś ze względów bezpieczeństwa albo zapisać zdarzenie na potrzeby obserwowalności. Zastosowań jest mnóstwo i przejdziemy przez przykłady każdego z nich.

Niezależnie od tego, jakiego agenta używasz — Codex, Claude Code czy Pi — wszystkie one obsługują ten prymityw. To jeden z pięciu podstawowych komponentów, które nadbudowujesz nad asystentem kodowania, żeby rozszerzyć harness i zbudować własne przepływy pracy. Mamy więc reguły, o których również sporo tu powiem; subagentów do delegowania pracy; serwery MCP do łączenia się z naszymi platformami; skille, czyli nasze przepływy i wielokrotnie używane prompty; oraz hooki, czyli nasze deterministyczne automatyzacje.

(Informacja dodatkowa: harness to warstwa oprogramowania, która opakowuje model językowy — zarządza narzędziami, kontekstem i pętlą działania agenta. Claude Code, Codex czy Pi to właśnie różne harnessy.)

Dlaczego determinizm zmienia wszystko

Słowo „deterministyczny” będzie w tym materiale padać często, bo determinizm jest właściwie równoznaczny z gwarancją. Wszystko inne, co budujemy dla agenta — skille, reguły — jest jedynie wskazówką. Nie ma żadnej gwarancji, że agent przejdzie cały przepływ do końca albo posłucha każdej reguły za każdym razem. I właśnie dlatego hooki są tak potężne: to jedyna rzecz, którą wbudowujemy w agenta, faktycznie zapewniająca, że coś dzieje się tak, jak powinno, za każdym razem.

Jeśli zastanawiasz się teraz, czy warto obejrzeć ten materiał do końca — odpowiedź brzmi: tak, jeśli kiedykolwiek zdarzyło ci się poczuć frustrację, bo mimo bardzo precyzyjnego zapisania reguły w CLAUDE.md czy AGENTS.md agent i tak jej nie przestrzegał. A zdarza się to nieustannie, ponieważ duże modele językowe są probabilistyczne. Nie interpretują twoich instrukcji ani przepływów tak samo za każdym razem. Czasem po prostu przeoczą regułę albo pominą krok w procesie. I to potrafi doprowadzić do szału.

Klasyczny przykład, na który sam się natknąłem: zwykle, gdy agent wykonuje jakąkolwiek implementację, masz reguły prowadzące go przez sprawdzenie własnej pracy i walidację. Masz więc opisany krok po kroku proces — na przykład jak uruchomić zestaw testów. Ale agenty potrafią pominąć fragmenty tego zestawu. Mówią, że skończyły i że przeprowadziły wszystkie potrzebne testy, a tymczasem część twojego zestawu wciąż świeci na czerwono. Agent nie zwalidował swojej pracy do końca. Jest to szczególnie częste w większych bazach kodu, gdzie sprawdzeń jest po prostu dużo.

To bardzo dobry przykład sytuacji, w której próbujemy zmieścić w regułach coś, co powinno być hookiem. Dzięki hookowi możemy zagwarantować, że dokładnie w momencie zakończenia rozmowy — używając hooka typu stop — testy zostaną uruchomione deterministycznie. Gwarantujemy uruchomienie testów. Jeśli pojawią się błędy, zmusimy agenta do wznowienia pracy i naprawienia ich.

To prowadzi do szerszej myśli: część rzeczy, które trzymasz dziś w skillach czy regułach, powinna stać się hookami. I to jest właśnie ramy myślowe, które chcę ci tutaj przekazać — pomogą ci rozpoznać, kiedy tworzyć hooki. Nie chcę, żebyś tylko je rozumiał; chcę, żebyś wiedział, jak wbudować je we własne przepływy.

Wyprowadzić proces z głowy agenta

Główna idea brzmi: chcemy w maksymalnym stopniu wyjąć większy proces spod odpowiedzialności agenta. Zamiast wpisywać w reguły „kiedy zdarzy się to, wtedy zrób tamto”, zamieniamy to w hooka, żeby mieć pewność, że to się stanie — bez polegania na tym, czy agent zapamięta właściwą kolejność operacji.

To, co mówię, jest zresztą zbieżne z badaniami, o których zapewne słyszałeś — jak choćby to, że Anthropic zmniejszył rozmiar systemowego promptu Claude Code o 80%. Wiele takich analiz pokazuje, że zbyt duża liczba reguł potrafi zaszkodzić agentowi. Rozpraszasz po prostu jego uwagę między dziesiątki procesów i konwencji.

Nie zrozum mnie źle: nie twierdzę, że reguły są złe. Wciąż są bardzo ważne. Chodzi o to, że zdecydowanie zbyt łatwo jest przesadzić z regułami.

Weźmy to badanie — jest dość techniczne, ale omówię je z lotu ptaka; link będzie w opisie. Autorzy zbudowali własny harness, który pozwala agentowi kodującemu ewoluować własną warstwę AI w czasie: edytować własne reguły i hooki, żeby lepiej radzić sobie z tymi samymi zadaniami później. Do tego mają osobnego ewaluatora-sędziego, który ocenia, czy zmiany w warstwie AI faktycznie przełożyły się na lepsze wyniki przy zadaniach o różnym poziomie trudności.

Grupa kontrolna to wynik bez żadnej samoewolucji. Na dole widzimy przypadek, w którym agent mógł zmieniać własne reguły — prompt systemowy to w zasadzie globalne reguły agenta. Wyniki spadły. Zrobiło się gorzej. To dowodzi, że jeśli tylko dopisujemy kolejne reguły — a właśnie to robią agenty, gdy pozwolisz im ewoluować własne reguły — to rozpraszamy uwagę. Nawet jeśli poszczególne dodane reguły potrafiłyby pomóc w izolacji przy pewnych typach zadań, to samo rozdymanie zbioru reguł pogarsza sprawę.

Z hookami — które autorzy nazywają middleware — jest odwrotnie: ich dodanie pomogło przy każdym typie zadania z wyjątkiem zadań trudnych. Samo zmienianie hooków było w stanie podnieść wydajność. A jedyny powód, dla którego przy trudnych zadaniach wypada to nieco gorzej, jest taki, że trzeba ewoluować całą warstwę AI naraz, żeby uzyskać najlepsze wyniki — co widać w ostatnim wierszu.

Główna teza jest jednak prosta: samo doklejanie kolejnych reguł będzie ci szkodzić. Dlatego trzeba uważać, co wpisujemy w reguły. A jeśli chcemy, żeby reguły były bardziej odchudzone, musimy zastanowić się, do których innych części warstwy AI przenieść to, co usuwamy. Jeśli wyjmujemy proces z reguł, to gdzie on należy? Należy do hooków.

Skill, który buduje hooki za ciebie

Wszystkie omawiane tu przykłady mam w swoim repozytorium ze skillami, do którego link znajdziesz w opisie. Możesz ich użyć jako punktu odniesienia albo wprost skorzystać z tych, których używam sam.

Chcę też pokazać ci skill hooks create. Każdy hook, który zobaczysz w tym materiale, powstał mniej więcej w ten sposób. Opisujesz po prostu: co ten hook ma robić? Jaką gwarancję chcę mieć w swoim przepływie? A skill przeprowadza cię przez wywiad, żeby zebrać wszystko, czego potrzebuje, następnie buduje cały hook i wpina go w twojego agenta — na przykład Claude Code. Skill jest napisany pod Claude Code, ale wystarczy powiedzieć mu, że używasz Codeksa albo Pi, i się dostosuje.

Przy wspomnianym wcześniej przykładzie z gwarancją testów mój prompt brzmiał po prostu: „Gdy rozmowa się kończy, uruchom pełny zestaw testów, żeby upewnić się, że wszystko jest zielone. Jeśli nie jest, zmuś agenta do naprawy”. Oczywiście trzeba jeszcze doprecyzować, czym jest mój zestaw testów — i mam nadzieję, że masz go już zdefiniowanego — ale to wyjdzie w trakcie wywiadu. Możesz zacząć od naprawdę prostego promptu, a skill zrobi resztę.

(Informacja dodatkowa: w tym miejscu w oryginale znajduje się blok sponsorski dotyczący platformy Minds Hub i jej produktu Co-work — agentowego środowiska pracy pozwalającego mieszać modele i dostawców w obrębie jednego przepływu. Pominięto go jako treść reklamową niezwiązaną z tematem materiału.)

Przykład pierwszy: hook stop, który wymusza zielone testy

Wróćmy do głównego przykładu: zawsze uruchamiamy testy po implementacji i zmuszamy agenta do iteracji, jeśli coś nie przechodzi.

Jestem w repozytorium, w którym mam skonfigurowany taki hook stop. Wszystkie hooki — przynajmniej w Claude Code — definiuje się w pliku settings.json. Pokazany przed chwilą skill pomoże ci również z całą konfiguracją, więc nie przejmuj się zbytnio szczegółami technicznymi; pokazuję tylko, jak wbudowujemy to w proces.

Mamy więc JSON, w którym wyszczególniamy wszystkie hooki oraz konkretne zdarzenia zachodzące w agencie, przy których uruchamiamy różne skrypty. Ten plik mieści właściwie wszystkie przykłady, które będę pokazywał.

Tutaj mamy hooki typu stop. To akcje uruchamiane w momencie, gdy agent stwierdzi, że skończył — gdy oddaje kontrolę z powrotem do nas. Mam tu stop_tests_must_pass.py. Nie muszę pokazywać całego skryptu; w istocie uruchamia on zestaw testów naszej bazy kodu i zwraca błąd, jeśli cokolwiek nie przechodzi.

Dla przykładu mam bardzo prostą rozmowę, w której poprosiłem agenta tylko o dodanie jednej linijki do pliku README. Ale wyobraź sobie, że jest to pełna implementacja dotykająca mnóstwa plików — i owszem, może agent i tak uruchamia testy, bo tak stanowi nasz skill implementacyjny, ale chcemy mieć pewność, że wszystko zostało uruchomione.

Widzimy więc, że hook stop się odpalił. Dostaliśmy błąd: zablokowane, ponieważ nie wszystkie testy przechodzą. Ta tura nie jest zakończona. Widać output z uruchomienia testów, z wyszczególnieniem błędów, na które natrafiliśmy w testach jednostkowych. I agent kontynuuje — jest zmuszony podjąć pracę na nowo i zająć się tymi błędami.

To trochę sztuczny przykład, bo poprosiłem tylko o dodanie jednej linijki, ale chciałem mieć prostą rozmowę, żeby pokazać sam mechanizm. Tak to wygląda w rozmowie — niezależnie od używanego agenta, dostaniesz informację, że hook się wykonał.

Jak hook rozmawia z agentem: kody wyjścia

Wróćmy na chwilę do diagramu, żeby wyjaśnić, jak hook komunikuje się z agentem. I pamiętaj: hooki są międzynarzędziowe, więc to wszystko obowiązuje niezależnie od agenta.

Skrypt uruchamiany przez hooka może być skryptem bashowym, TypeScriptowym albo Pythonowym. Wykonuje to, co trzeba w ramach deterministycznej akcji, a potem zwraca kod wyjścia. To kod wyjścia decyduje o tym, czy agent może kontynuować, czy też coś zostało zablokowane albo wymaga poprawki.

Jeśli wychodzimy z kodem 0, mówimy, że hook jest zielony: sprawdzenie przeszło pomyślnie albo pozwalamy rozmowie się zakończyć. Ale jeśli jest 2 — blokujemy. Komunikujemy agentowi, że jest problem, który trzeba rozwiązać. Może nie pozwolimy mu wykonać danej akcji — taki przykład zaraz pokażę. Albo: nie, nie możemy tu zakończyć rozmowy, coś jeszcze wymaga uwagi. Tak sygnalizujemy porażkę. A jeśli zepsuł się sam kod hooka, jest jeszcze inny kod błędu, ale zwykle jest on mniej istotny. Skupiamy się na tych dwóch: przeszło albo nie przeszło.

Co ważne, w zależności od zdarzenia wyzwalającego hooka, ta „porażka” znaczy coś innego. Przy naszym przykładzie z testami niepowodzenie hooka stop oznacza, że nie możemy zakończyć rozmowy — blokujemy akcję zatrzymania.

Przykład drugi: pre-tool use i blokada `.env`

Drugie zdarzenie, które chcę omówić, to pre-tool use. To prawdopodobnie najpopularniejsze zdarzenie do podpinania hooków, bo pozwala ocenić akcję, którą agent zamierza wykonać, zanim faktycznie wywoła narzędzie. Można na nim oprzeć mnóstwo mechanizmów bezpieczeństwa. Uwielbiam to zdarzenie.

Świetnym przykładem jest blokada pliku .env. Naprawdę nigdy nie chcesz, żeby agent kodujący czytał twoje zmienne środowiskowe, bo wtedy klucze API trafiają do kontekstu modelu, a stamtąd na serwery dostawcy używanego agenta. Chcemy więc uniemożliwić agentowi odczytanie tego pliku.

I znów: możesz wpisać w reguły „nie czytaj .env”, „nie uruchamiaj polecenia usuwania”, „nie edytuj plików w tym katalogu”. Ale to, że coś jest regułą, nie oznacza, że agent zawsze się do niej zastosuje. Powstrzymanie agenta przed wykonaniem określonych wywołań narzędzi to jedna z najważniejszych gwarancji, jakie możesz wbudować w swój przepływ.

Zobaczmy to w działaniu. Zapytałem po prostu: „Jaki jest mój klucz API do OpenRouter w pliku .env?”. To trochę przerażające, ale agent z ochotą spróbował ten plik odczytać. Jeśli poprosisz go wprost — albo jeśli agent zwyczajnie pogubi się przy większej ilości kontekstu — zrobi rzeczy, których robić nie powinien: odczyta .env albo usunie katalog.

Ale zablokowaliśmy to. Spójrz: mamy wywołanie narzędzia, w którym próbował odczytać .env, i mamy błąd z pre-tool use. Hook się odpalił i zwrócił błąd: „zablokowane, dostęp do sekretów nie jest dozwolony”.

Fajne jest też to, że hook dostarcza agentowi wskazówkę. Jeśli istnieje .env.example, możemy odczytać ten plik zamiast oryginału — bo być może agent chce tylko ustalić, jakie zmienne środowiskowe ma projekt. Agent potrafi więc dostosować się na podstawie informacji zwrotnej od hooka. Nie jest tak, że po prostu przerywamy rozmowę i wywracamy agenta; to staje się częścią procesu, w której agent traktuje blokadę jako informację zwrotną i idzie dalej.

Sam hook jest bardzo prosty w konfiguracji. W settings.json mamy — zamiast hooka stop — hooka pre-tool use, a w nim pre_tool_use_secrets. To skrypt, który ocenił zamiar agenta. Wykrył na podstawie wyrażenia regularnego, że agent próbuje sięgnąć po sekret. Następnie wypisujemy komunikat, który wraca do agenta jako informacja zwrotna, i zwracamy ten kod wyjścia 2, o którym mówiłem — to on wymusza iterację i inne działanie.

Pokazałem dopiero kilka hooków, których używam codziennie, ale bardzo użyteczne hooki istnieją dla każdego zdarzenia z menu.

Możesz na przykład zbudować kolejny hook stop, który wysyła ci powiadomienie — na pulpit albo na Slacka — gdy agent skończy pracę, żebyś wiedział, że czas dać mu kolejny input.

Możesz też użyć post-tool use albo sub-agent stop do obserwowalności: za każdym razem, gdy subagent kończy pracę albo gdy właśnie wykonaliśmy akcję, budujemy ślad audytowy. Później możesz wrócić do niego razem z agentem, żeby wyłapać okazje do usprawnień i stopniowo ewoluować swoją warstwę AI.

Start session to kolejny dobry przykład. Dokładnie w momencie uruchomienia nowej instancji agenta — na przykład Claude Code — możesz wstrzyknąć określony kontekst. Ja robię tak dla swojego „drugiego mózgu”: mam plik z pamięcią rdzeniową, który wciągam hookiem start session razem z moimi globalnymi regułami.

Przykładów jest mnóstwo, nie zdążę omówić wszystkich, ale możesz puścić wodze fantazji, jeśli chodzi o rzeczy do zautomatyzowania — o gwarancje wbudowywane w twoje przepływy.

Podstawowy model mentalny, który bym tu zaproponował: przy hookach albo blokujesz, żeby coś się nie stało, albo obserwujesz. Widzieliśmy już dobre przykłady dla pre-tool use i stop. Zastosowań w obszarze bezpieczeństwa jest bardzo dużo. Naprawdę nie masz wymówki, żeby nie używać hooków — przydają się w każdym przepływie pracy z AI. Mniej skupiamy się tu na obserwowalności, bo jest ona mocno zależna od twojego procesu i twoich baz kodu, ale szczególnie post-tool use świetnie nadaje się do logowania wszystkich akcji agenta.

Reguła kciuka: każdy hook typu pre to bramka, bo dzieje się przed wykonaniem akcji przez agenta — przed zakończeniem rozmowy czy wywołaniem narzędzia. A wszystko, co post, służy raczej logowaniu, jak post-tool use. Nawiasem mówiąc, skill hooks create zna te dobre praktyki, więc w zależności od tego, co chcesz zautomatyzować, sam podpowie, które zdarzenia z menu warto rozważyć.

Najważniejsza część: audyt reguł

Na tym etapie masz zapewne już własne pomysły na hooki. Ale chcę ci to jeszcze bardziej ułatwić. Najważniejsza część tego materiału to audyt reguł: jak — obok pomysłów, które już masz — wygenerować kolejne, przechodząc przez własne reguły i wyłapując to, co należy wyekstrahować i zamienić w gwarancję.

Na szczęście ta rama jest dość prosta. Zachęcam, żebyś przeszedł przez nią dziś na swoich globalnych regułach; bardzo ci to pomoże. Przechodzisz przez każdą sekcję lub linijkę reguł i zadajesz sobie pytanie: czy to nazywa zdarzenie, czy koduje osąd?

Kilka przykładów. „Kwoty pieniężne zawsze jako liczby całkowite w centach, nigdy jako liczby zmiennoprzecinkowe” — to w ogóle nie jest proces. Kodujemy tu osąd: to ograniczenie albo konwencja, którą narzucamy agentowi. To zdecydowanie pozostaje regułą.

Ale kolejna linijka: „po zaimplementowaniu uruchom testy”. Kiedy dzieje się to, wtedy trzeba zrobić tamto. To zdecydowanie proces — i dokładnie ten przykład, który omawialiśmy na początku. To powinien być hook stop, żeby uniknąć opisanego wcześniej problemu.

Kolejny przykład: „nigdy nie czytaj pliku .env”. To nasz przykład hooka pre-tool use. Niekoniecznie brzmi to jak proces — może to lekkie naciąganie — ale można pomyśleć o tym tak: „kiedy zamierzasz odczytać plik, upewnij się, że to nie jest .env”.

Jeszcze lepszy przykład: „gdy zaczyna się sesja, przeczytaj decisions.md”. To powinien być hook start session, bo agent może się pogubić w gąszczu wszystkich twoich reguł i faktycznie nie przeczytać tego pliku na początku rozmowy.

We wszystkich tych przypadkach nazywamy zdarzenia, które muszą zajść. Kiedy dzieje się to, wtedy robimy tamto. Wyekstrahujmy ten proces, bo nie kodujemy tu osądu. Oczywiście większość twoich reguł zapewne pozostanie regułami.

Jest jeszcze trzecia kategoria: jeśli coś nie jest ani osądem, ani nazwaniem zdarzenia — po prostu to usuń. Jak „pisz czysty kod”. Agent już to wie. Nie kodujemy tu żadnego nowego osądu, więc możemy przy okazji przyciąć reguły. To temat na osobny materiał; teraz skup się na pytaniu, czy coś jest procesem, czy nie.

Audyt na żywym przykładzie

Żeby to jeszcze uściślić, przygotowałem plik globalnych reguł, w który celowo wpisałem procesy, które naprawdę powinny być hookami. Wszystkie te rzeczy sam u siebie zamieniłem na hooki.

„Na początku każdej sesji uruchom git status i przeczytaj decisions.md” — to powinien być hook start session.
„Zanim cokolwiek zmienisz w routes, przeczytaj najpierw rag/citations.py” — to powinien być hook pre-tool use. To zresztą bardzo ciekawy przypadek, który okazał się u mnie wyjątkowo użyteczny: czasem wiesz, że przy pracy nad konkretnym plikiem istotny kontekst leży gdzie indziej w bazie kodu. Hookiem możesz zagwarantować, że agent najpierw to obejrzał, więc naprawdę ma wszystkie informacje potrzebne do wprowadzenia zmian.

Pokażę to w akcji. Mówię: „w tym pliku dodaj jedno zdanie do promptu systemowego”. Hook pre-tool use zwraca błąd: „zablokowane — ten plik jest sprzężony z plikami, których nie odczytałeś w tej sesji”. Claude Code robi coś podobnego sam z siebie: gdy próbuje edytować plik, którego jeszcze nie przeczytał, dostaje błąd aktualizacji. Ale ten hook idzie dalej: mówi, że skoro te rzeczy są ze sobą sprzężone, trzeba przeczytać wszystko. Agenty bardzo często próbują wykonywać działania, nie mając wystarczającego kontekstu.

Dalej z listy reguł:

„Nigdy nie czytaj .env” — nasz klasyczny pre-tool use. To zdecydowanie powinien być hook.
„Nigdy nie uruchamiaj rekurencyjnego wymuszonego usuwania” — kolejne zabezpieczenie jako pre-tool use.
„Loguj każde polecenie, które uruchamiasz” — to post-tool use.
„Gdy skończysz implementację, uruchom pełny zestaw testów” — znów nasz hook stop.

Kilka z nich się powtarza, ale chodzi mi o pokazanie, że bez zrozumienia tego, o czym mówię w tym materiale, wszystkie one wyglądałyby na dobrą treść reguł. No bo tak: chcesz, żeby testy zawsze były uruchamiane. Chcesz, żeby agent nie czytał .env. Tyle że to po prostu nie są gwarancje.

I rzecz fantastyczna: cokolwiek zidentyfikujesz w swoich regułach jako proces, możesz zwyczajnie skopiować tę sekcję lub linijkę i podać ją skillowi hooks create, do którego link jest w opisie. Wpisujesz /hooks create, wklejasz — tak jak ja tutaj wkleiłem „zanim cokolwiek tu zmienisz, przeczytaj ten plik”, czyli przykład ze sprzężeniem plików. I gdy przewinę w dół, widać, że hook został zbudowany. Skill zdecydował, że będzie to pre-tool use, ustalił parametry, zbudował hooka i wpiął go w settings.json. Zrobił za mnie wszystko na podstawie samej reguły, którą mu podałem: dobrał typ hooka, konfigurację, skrypt, całość.

Na koniec

Miej tylko na uwadze, że hooki nie zastępują reguł. One się uzupełniają. Reguły są bardzo, bardzo ważne. Chodzi jedynie o to, że w twoich regułach istnieją pewne procesy i nazwane zdarzenia, które możesz zamienić w hooki.

Mam nadzieję, że pomogło ci to rozpoznać, jakie gwarancje możesz wbudować w swoje przepływy pracy — i ogólnie zrozumieć, jak działają hooki.

10 najważniejszych takeaways — z kontekstem zastosowania

1.Reguły to sugestia, hook to gwarancja

Na czym polega: Reguły w CLAUDE.md czy AGENTS.md oraz skille są tylko wskazówką dla probabilistycznego modelu — bywają pomijane. Hook to skrypt uruchamiany deterministycznie przez harness przy określonym zdarzeniu, niezależnie od tego, co model „postanowi”.

Jak stosować: Za każdym razem, gdy przyłapiesz się na myśli „ale on ma to zapisane w regułach i i tak tego nie zrobił”, potraktuj to jako sygnał, że dana rzecz jest kandydatem na hooka, a nie na kolejne wytłuszczenie w regułach.

Na co uważać: Determinizm dotyczy uruchomienia hooka, nie reakcji agenta. Jeśli hook zwróci mglisty komunikat, agent nadal może zareagować niepoprawnie — treść informacji zwrotnej jest równie ważna jak sama blokada.

2.Test „zdarzenie czy osąd” jako narzędzie audytu reguł

Na czym polega: Przechodzisz linijka po linijce przez swoje reguły i pytasz: czy to nazywa zdarzenie („gdy X, zrób Y”), czy koduje osąd (konwencja, ograniczenie)? Zdarzenia idą do hooków, osądy zostają regułami, reszta idzie do usunięcia.

Jak stosować: Zrób ten przegląd raz na swoich globalnych regułach — to najszybszy sposób na wygenerowanie listy hooków do zbudowania. Wyłapuj zwłaszcza sformułowania z „przed”, „po”, „na początku”, „zawsze gdy”.

Na co uważać: Autor przyznaje, że granica bywa nieostra — „nigdy nie czytaj .env” brzmi jak osąd, a jest zdarzeniem („zanim odczytasz plik, sprawdź, czy to nie sekret”). Rozstrzygaj, pytając, czy da się wskazać moment w cyklu życia agenta, w którym trzeba to sprawdzić.

3.Trzecia kategoria: reguły do skasowania

Na czym polega: Jeśli linijka nie koduje osądu ani nie nazywa zdarzenia — jak „pisz czysty kod” — jest zbędna. Model już to wie, a linijka zabiera uwagę.

Jak stosować: Przy tym samym przeglądzie prowadź trzecią kolumnę: „do usunięcia”. Rozdmuchane reguły kosztują cię wydajność, a nie tylko tokeny.

Na co uważać: Nie kasuj czegoś tylko dlatego, że brzmi banalnie — pytanie brzmi, czy zapis niesie informację specyficzną dla twojego projektu. „Pisz czysty kod” nie niesie; „kwoty jako liczby całkowite w centach” niesie.

4.Hook stop wymuszający zielony zestaw testów

Na czym polega: Skrypt uruchamiany w momencie, gdy agent oddaje kontrolę użytkownikowi. Odpala pełny zestaw testów; jeśli coś jest czerwone, blokuje zakończenie tury i zmusza agenta do dokończenia pracy.

Jak stosować: To najlepszy pierwszy hook do wdrożenia, zwłaszcza w większych bazach kodu, gdzie agent bywa wybiórczy przy uruchamianiu testów. Warunkiem wstępnym jest posiadanie jednego, jasno zdefiniowanego polecenia uruchamiającego cały zestaw.

Na co uważać: Przy wolnych zestawach testów hook wydłuża każdą turę. Jeśli testy trwają minuty, rozważ ograniczenie hooka do szybkiego podzbioru albo do przypadków, gdy w turze doszło do zmian w kodzie — inaczej zaczniesz go wyłączać, co niweczy gwarancję.

5.Kody wyjścia jako protokół komunikacji z agentem

Na czym polega: Skrypt hooka (bash, Python, TypeScript — dowolny) kończy działanie kodem wyjścia. 0 oznacza „przechodzi”, 2 oznacza blokadę. Wypisany komunikat wraca do agenta jako informacja zwrotna. Awaria samego skryptu daje jeszcze inny kod.

Jak stosować: Traktuj komunikat przy kodzie 2 jak prompt: napisz w nim, co jest zablokowane i co agent ma zrobić zamiast tego. To ta część zamienia twardą blokadę w płynne przekierowanie.

Na co uważać: Znaczenie „porażki” zależy od zdarzenia — przy stop blokujesz zakończenie rozmowy, przy pre-tool use blokujesz wywołanie narzędzia. Ten sam kod wyjścia daje zupełnie inny efekt w zależności od miejsca podpięcia.

6.Pre-tool use jako warstwa bezpieczeństwa

Na czym polega: Najpopularniejsze zdarzenie do podpinania hooków, bo pozwala ocenić zamiar agenta przed wykonaniem akcji. Klasyczne zastosowania: blokada odczytu .env, blokada rekurencyjnego wymuszonego usuwania.

Jak stosować: Zacznij od dwóch hooków: sekrety i destrukcyjne polecenia powłoki. Autor pokazuje na żywo, że zapytany wprost o klucz API agent bez wahania próbuje odczytać .env.

Na co uważać: Detekcja u autora opiera się na wyrażeniach regularnych, a te da się obejść — plik można odczytać przez cat, grep czy inną ścieżkę. Zabezpiecz wzorce na poziomie zarówno narzędzia odczytu, jak i poleceń powłoki, i traktuj to jako redukcję ryzyka, nie jako szczelną barierę.

7.Blokada, która podpowiada alternatywę

Na czym polega: Hook blokujący .env nie tylko odmawia — sugeruje odczytanie .env.example, jeśli taki plik istnieje. Agent dostaje informację zwrotną, adaptuje się i kontynuuje zamiast się zaciąć.

Jak stosować: Do każdej blokady dopisz zdanie „zamiast tego zrób X”. Bardzo często agent chce dowiedzieć się czegoś legalnego (jakie zmienne środowiskowe istnieją) i wybiera tylko złą drogę.

Na co uważać: Alternatywa musi być realna i sprawdzona w skrypcie — sugerowanie pliku, którego nie ma, wyśle agenta w ślepy zaułek i wygeneruje kolejną turę marnowaną na próby.

8.Hook wymuszający kontekst przed edycją sprzężonych plików

Na czym polega: Pre-tool use, który przy próbie edycji pliku sprawdza, czy agent odczytał w tej sesji powiązane z nim pliki. Jeśli nie — blokuje z komunikatem, że plik jest sprzężony z nieprzeczytanymi.

Jak stosować: Wypisz w projekcie 2–3 najbardziej „zdradliwe” sprzężenia — miejsca, gdzie zmiana wymaga wiedzy z innego pliku — i zakoduj je jako mapę zależności w hooku. To najbardziej niedoceniany z przykładów w materiale, bo atakuje typową przyczynę błędów: działanie przy zbyt małym kontekście.

Na co uważać: Mapa sprzężeń starzeje się razem z kodem. Zbyt szeroka lista zamieni się w rytuał wczytywania połowy repozytorium przed każdą edycją i zapcha kontekst — dokładnie odwrotnie do celu.

9.Podział mentalny: bramki pre, logowanie post

Na czym polega: Hooki albo blokują, albo obserwują. Wszystko z prefiksem pre jest bramką (przed akcją agenta), wszystko post nadaje się głównie do logowania i budowania śladu audytowego. Dochodzą do tego start session (wstrzykiwanie kontekstu na starcie) i sub-agent stop.

Jak stosować: Wybierając zdarzenie, zapytaj najpierw: chcę czemuś zapobiec czy coś zarejestrować? To rozstrzyga wybór z menu szybciej niż czytanie dokumentacji. Start session nadaje się do gwarantowanego wczytania pliku decyzji czy pamięci projektu.

Na co uważać: Autor sam zaznacza, że część o obserwowalności jest mocno zależna od twojego procesu — logi bez pomysłu na ich późniejsze użycie to tylko rosnące pliki. Zaplanuj, kto i kiedy będzie ten ślad audytowy czytał.

10.Hooki uzupełniają reguły, a nie je zastępują

Na czym polega: Przywoływane przez autora badanie pokazuje, że pozwolenie agentowi na dopisywanie kolejnych reguł pogorszyło wyniki, a dodawanie hooków („middleware”) je poprawiło — przy zadaniach trudnych najlepsze efekty dawało ewoluowanie całej warstwy AI naraz.

Jak stosować: Traktuj to jako budżet uwagi: przenoszenie procesu do hooków to sposób na odchudzenie reguł bez utraty zachowania. Osądy, konwencje i ograniczenia domenowe zostawiaj w regułach.

Na co uważać: To pojedyncze badanie na własnym harnessie autorów, przywołane z drugiej ręki i bez podanych liczb — traktuj je jako argument kierunkowy, nie jako twardy dowód. Nie wyciągaj z niego wniosku, że reguły są zbędne; autor wprost temu zaprzecza.