Mam w swoim setupie agenta kodującego skill o nazwie careful. To ma być siatka bezpieczeństwa: mówisz coś w stylu “uważaj, to produkcja” i blokuje destrukcyjne komendy do końca sesji, rm -rf, DROP TABLE, force-push, kubectl delete, cała zwyczajowa lista. To jeden z tych mechanizmów, które budujesz raz, czujesz satysfakcję i nigdy więcej do nich nie zaglądasz.

W zeszłym tygodniu naprawiałem zepsuty backup bazy danych na infrastrukturze klienta. Prawdziwa produkcja, prawdziwa stawka. Powiedziałem kilka razy “pamiętaj, dotykasz produkcji” po polsku, w trakcie tej samej sesji. Skill ani razu się nie odpalił. Okazało się, że lista fraz wyzwalających rozpoznawała tylko konkretne sformułowania po angielsku, ktoś (czyli ja) zapisał je tak przy budowaniu skilla i nikt tego potem nie ruszał. Luka między tym, co skill miał robić, a tym co faktycznie robił, siedziała tam od dawna, i znalazłem ją tylko dlatego, że przypadkiem wpisałem złe słowa podczas prawdziwego incydentu, a nie destrukcyjną komendę.

To jest ten typ awarii, o którym jest ten wpis. Konfiguracja agentów AI, reguły, skille, hooki, instrukcje typu CLAUDE.md, rośnie dokładnie tak jak kod. Przyrasta małymi kawałkami, jest kopiowana między projektami, zbiera założenia, których nikt nie zapisał, i gnije dokładnie tak jak gnije nieudokumentowany kod. Tyle że kod ma kompilator i testy, które krzyczą, kiedy zmiana coś psuje. Konfiguracja agenta nie ma nic z tego. Zawodzi po cichu, aż do dnia, w którym to ma znaczenie.

Czym właściwie jest ISA

Ideal State Artifact to jeden plik markdown na projekt albo setup, z trzema częściami.

Cel. Jeden akapit. Po co to w ogóle jest, nie lista funkcji, tylko cel.

Idealny stan docelowy. Kilka punktów opisujących, co jest obserwowalnie prawdziwe, kiedy to działa dobrze. Nie aspiracje, tylko fakty, które można zaobserwować.

Sprawdzalne twierdzenia. Numerowana lista, w której każde twierdzenie nazywa konkretny sposób sprawdzenia zamiast niejasnej nadziei. Nie “skill bezpieczeństwa działa”, tylko coś, co realnie można zweryfikować:

1
2
3
4

3. Kiedy `careful` się odpali, odpowiedź zawiera widoczne potwierdzenie
   przed jakimkolwiek wywołaniem narzędzia. Sprawdź: przejrzyj transkrypty
   ostatnich pięciu sesji pod kątem frazy wyzwalającej, potwierdź że po
   każdej z nich w tym samym obrocie pojawia się tekst potwierdzenia.

Twierdzenia narastają w czasie. Kiedy setup się zmienia, aktualizujesz twierdzenie w miejscu, nie zostawiasz nieaktualnego obok nowego z nadzieją, że przyszły ty zapamięta, które jest aktualne. Twierdzenie, które znowu zrobiło się mgliste, dostaje ostrzejszą wersję, nie jest kasowane.

Całość działa, bo większość ludzi nie potrafi na zimno napisać pełnej specyfikacji tego, co ich setup agenta faktycznie gwarantuje. Prawdziwe wymagania żyją jako niewypowiedziany osąd, rozrzucony po miesiącach momentów “aha, no tak, to miało też robić X”, a nie jako dokument, który ktoś usiadł i napisał. Wyciągnięcie tego osądu z głowy i zapisanie go tak, żeby dało się to sprawdzić, to cała wartość tego ćwiczenia. ISA sama się nie egzekwuje. To dyscyplina, tak samo jak pisanie testów jest dyscypliną. Jeśli nie przeprowadzisz wywiadu i nie zaktualizujesz pliku, kiedy coś się zmienia, masz nieaktualny dokument, który okłamuje cię z większą pewnością siebie niż brak dokumentu w ogóle.

Wywiad

Sposób na napisanie takiego pliku to nie usiąść i spróbować wypisać wszystko naraz. To daje listę rzeczy, które i tak już wiesz, a nie tam jest wartość. Zamiast tego jest to krótki, uporządkowany wywiad: jedno pytanie na raz, każde dostosowane do poprzedniej odpowiedzi, kończący się w momencie, kiedy twierdzenia są wystarczająco konkretne, żeby je sprawdzić, a nie kiedy wyczerpie się jakaś sztywna lista pytań.

Taki wywiad przeprowadzony w tym tygodniu na skillu careful wydobył trzy twierdzenia, których nie napisałbym, patrząc tylko w kod skilla:

  1. Lista fraz wyzwalających musi zawierać sformułowania, których faktycznie używam, w różnych językach, a nie tylko te, które ktoś akurat zapisał przy budowaniu skilla.
  2. Kiedy skill się odpali, odpowiedź musi pokazywać widoczne potwierdzenie. “Zauważę, jeśli się po cichu nie odpali” okazało się fałszem, sprawdzonym w praktyce, a nie założeniem. To, jak faktycznie wiem, że skill działa, to widzenie potwierdzenia, nie brak problemu.
  3. Dokumentacja skilla musi zgadzać się z jego rzeczywistym technicznym działaniem. Okazało się, że careful wyłącza też bezpośrednie narzędzia zapisu plików do końca sesji, efekt uboczny, którego nikt nigdzie nie zapisał, i który zaskoczył osobę utrzymującą skill, czyli mnie.

Żadne z tych trzech nie wynika z czytania kodu. Wynikają z tego, że ktoś na głos nazwał, co konkretnie znaczy “zauważę, jeśli to się zepsuje” i “to działa dobrze”, a potem sprawdził, czy to nadal jest prawda.

Wyszła też czwarta rzecz, której wywiad nie rozwiązał: chcę, żeby ten tryb utrzymywał się automatycznie dla danego projektu między sesjami, zamiast wymagać ponownego wyzwolenia za każdym razem, kiedy otwieram nową sesję. To wymaga strukturalnie innego mechanizmu, hooka przypisanego do projektu zamiast wyzwalacza przypisanego do sesji, i nie da się tego załatać na miejscu. Właściwym ruchem było zapisanie tego wprost jako znaną, nierozwiązaną lukę, zamiast przemilczeć temat albo udawać, że wywiad dał pełną odpowiedź. Ten podział, to jest odpowiedziane kontra to jest realna luka i o tym wiemy, jest częścią tego, co czyni ten dokument wiarygodnym na dłuższą metę. Plik pełen pewnych siebie twierdzeń, który po cichu pomija trudne kawałki, jest gorszy niż taki, który przyznaje, gdzie jest cienki.

Dlaczego to jest lepsze niż czytanie kodu

Można by argumentować, że to niepotrzebne, wystarczy przeczytać kod skilla, kiedy masz wątpliwości. Sam tak zrobiłem najpierw, zanim przeprowadziłem wywiad. Czytanie kodu careful mówi ci, jaka jest aktualna lista fraz wyzwalających i aktualna lista blokowanych komend. Nie mówi ci, że w tej liście brakuje twojego własnego sposobu mówienia, bo kod nie ma zdania na temat tego, jak ty faktycznie mówisz. Nie mówi ci, że “zauważę, jak to się po cichu wywali” to założenie, a nie fakt, bo to założenie siedzi w twojej głowie, nie w pliku. Code review łapie błędy w implementacji. Nie łapie luki między tym, co zakładasz, że coś robi, a tym, czego faktycznie potrzebujesz, bo z punktu widzenia kodu to nie jest błąd. Kod działa dokładnie tak, jak został napisany. Problem w tym, że nikt nigdy nie sprawdził tego, co napisano, z tym, co miano na myśli.

Co z tym zrobić

Napisz jedną ISA dla każdego setupu, na którym ci zależy, nie jeden wielki plik na wszystko. Trzymaj sprawdzalne twierdzenia naprawdę sprawdzalnymi, jeśli twierdzenia nie da się zamienić na grep, odczyt pliku albo konkretny test, to jeszcze nie jest twierdzenie, tylko aspiracja. Powtarzaj wywiad, kiedy coś w setupie się zmienia, nie według kalendarza. I bądź uczciwy w pliku co do tego, co jest rozwiązanym twierdzeniem, a co odłożoną na bok luką. Luka, którą zapisałeś, jest w porządku. Luka, której nie zauważyłeś, to ta, która odpali się, albo nie odpali, podczas kolejnego incydentu.

Jeśli używasz Claude Code, to mapuje się wprost na warstwy konfiguracji, które większość setupów już ma: instrukcje CLAUDE.md, skille, hooki, reguły uprawnień. Żadna z nich nie przychodzi z własnym test runnerem. ISA jest najbliższym odpowiednikiem, jaki masz, i kosztuje popołudnie rozmowy z samym sobą na głos zamiast incydentu produkcyjnego, żeby dowiedzieć się, gdzie założenia się posypały.