Pre/Post akcje: auto-format, auto-test, auto-lint

Czego się nauczysz

• Jak praktycznie wykorzystać PreToolUse i PostToolUse
• Jak budować hooki do formatowania, testów, lintowania i blokowania ryzykownych komend
• Jak zwracać decyzje allow, ask i deny bez mieszania logiki biznesowej z promptem

Najbardziej użyteczne hooki są nudne

I to jest ich zaleta.

Najlepsze hooki nie robią nic spektakularnego. Robią za to konsekwentnie to samo po każdej edycji albo przed każdym ryzykownym wywołaniu narzędzia.

W praktyce właśnie takie nudne automatyzacje dają największy zwrot:

• formatter po zmianie pliku
• lint albo test po edycji
• blokada niebezpiecznej komendy terminala
• wymuszenie approvalu dla wrażliwego typu operacji

Myśl w kategoriach dwóch punktów kontroli

Przy hookach pre i post warto przyjąć prosty model:

• PreToolUse decyduje, czy narzędzie w ogóle powinno ruszyć
• PostToolUse sprawdza, co stało się po wykonaniu i czy trzeba dołożyć walidację albo kontekst

To rozróżnienie robi porządek.

Jeśli chcesz zablokować niebezpieczne działanie, myślisz o PreToolUse.

Jeśli chcesz po edycji uruchomić formatter albo dopiąć informację o błędach lintowania, myślisz o PostToolUse.

Format hooka jest prosty, ale warto znać ważne pola

W pliku JSON definiujesz hooks, a w nim listy komend dla konkretnych eventów.

Każdy wpis ma obowiązkowo type: "command", a dalej najczęściej używasz:

• command
• windows, linux, osx
• cwd
• env
• timeout

To ważne szczególnie na Windows, bo często lepiej jawnie podać komendę powershellową zamiast liczyć na domyślny shell.

Najprostszy i najczęstszy wzorzec: formatter po edycji

Docs zaczynają właśnie od tego i słusznie.

Jeśli agent edytuje plik, PostToolUse może odpalić Prettiera albo inny formatter dla wskazanego pliku. To jest bardzo dobry pierwszy hook, bo:

• jest lokalny i łatwy do zrozumienia
• szybko pokazuje realny efekt
• nie zmienia modelu zaufania tak mocno jak hooki terminalowe

To dobry przykład automatyzacji, która zwiększa spójność bez specjalnego ryzyka.

Lint i testy też nadają się do post-akcji, ale z głową

Tu wiele osób robi pierwszy błąd: próbuje odpalać pełny zestaw testów po każdej mikrozmianie.

To zwykle prowadzi do wolnego, głośnego workflow, którego wszyscy zaczynają nienawidzić.

Znacznie lepiej działa myślenie warstwowe:

• po pojedynczej edycji: formatter albo szybki lint
• po większym kroku: testy targetowane
• przed końcem zadania: pełna walidacja

Hook ma pomagać agentowi, a nie zabijać tempo każdej iteracji.

PreToolUse to miejsce na guardraile

Jeśli chcesz chronić repo albo środowisko, PreToolUse jest centralnym punktem kontroli.

Hook dostaje między innymi nazwę narzędzia, wejście i identyfikator wywołania. Może zwrócić hookSpecificOutput z decyzją:

• allow
• ask
• deny

To jest bardzo praktyczne, bo zamiast pisać ogólną instrukcję typu “uważaj na destrukcyjne komendy”, możesz sprawdzić parametry wejściowe i zareagować konkretnie.

ask bywa niedoceniane

Wiele osób myśli tylko w trybie zero-jedynkowym: przepuść albo zablokuj.

Tymczasem ask bywa najlepszą decyzją. Pozwala zostawić agentowi autonomię w zwykłych sytuacjach, ale zatrzymać go wtedy, gdy zakres działania robi się zbyt szeroki.

Dobry przykład:

• mała edycja w src/ może dostać allow
• operacja na plikach konfiguracyjnych albo polecenie terminalowe z większym skutkiem może dostać ask

Post-akcja może też zwracać kontekst do modelu

To ważna, praktyczna rzecz z docsów.

PostToolUse nie musi tylko odpalać komendy. Może też dołączyć additionalContext, dzięki czemu agent wie, co wyszło z walidacji.

To ma ogromny sens przy lintowaniu albo testach. Agent nie musi zgadywać, że po edycji pojawił się nowy problem. Hook może mu to dopisać wprost do rozmowy.

Projektuj hooki jak małe, ostre narzędzia

Nie próbuj z jednego hooka robić mini-orkiestratora całego procesu developerskiego.

Lepszy wzorzec jest taki:

• jeden hook robi jedną rzecz
• nazwa pliku hooka zdradza intencję
• timeout jest rozsądny
• komenda jest przewidywalna i możliwie krótka

To później bardzo upraszcza debugowanie.

Bezpieczeństwo nadal obowiązuje

To, że hook ma dobrą intencję, nie znaczy jeszcze, że jest bezpieczny.

Docs podkreślają kilka rzeczy:

• hooki uruchamiają shell commands
• wejście od agenta trzeba traktować ostrożnie
• skrypt hooka też jest kawałkiem kodu, który trzeba reviewować

Szczególnie ważne jest ostrzeżenie dotyczące sytuacji, gdy agent może edytować skrypty hooków, a potem je uruchamiać. To jest bardzo zły układ, jeśli nie masz odpowiednich ograniczeń approvali.

Ćwiczenie praktyczne

Zaprojektuj dwa hooki dla własnego repo:

1. PostToolUse, który po edycji pliku uruchamia formatter albo szybki lint.
2. PreToolUse, który dla ryzykownych komend terminalowych zwraca ask albo deny.

Dla każdego z nich odpowiedz:

• jaki event wybierasz i dlaczego
• jaki jest minimalny zestaw danych wejściowych potrzebny do decyzji
• co ma być sygnałem sukcesu, a co powodem blokady
• czy wynik ma tylko logować, czy też dodać kontekst do modelu

Kluczowe wnioski

• PreToolUse służy głównie do guardraili i kontroli ryzyka.
• PostToolUse jest idealny do formatowania, lintowania i dopisywania wyników walidacji do kontekstu.
• Najlepsze hooki są małe, przewidywalne i ostro ograniczone zakresem.
• Automatyzacja ma przyspieszać iterację, a nie odpalać pełne CI po każdym ruchu agenta.

Co dalej

Znasz już mechanikę pre i post akcji. Następny krok to gotowe schematy automatyzacji: które wzorce mają sens w front-endzie, back-endzie i zespołowym workflow, a które wyglądają dobrze tylko na slajdzie.