Pięć zasad, których Claude Code nie ominie
Dawaliśmy Claude Code prawdziwe zadania w naszym własnym API do faktur w TypeScripcie i przyłapaliśmy go na kopiowaniu walidatora zamiast ponownego użycia istniejącego. Ten artykuł zawiera pięć zasad przeciw gniciu kodu i dla każdej z nich hook lub ustawienie Claude Code, które ją wymusza. Dokumentacja Anthropic mówi, że plik CLAUDE.md to kontekst, a nie wymuszona konfiguracja, więc zasada zapisana w nim to zdanie, które model waży względem zadania. Egzekutory poniżej to pliki uruchamiane przez harness: blokada duplikacji odpalana zaraz po edycji, tura, której nie da się zakończyć przy czerwonych testach, i bramki konfiguracyjne, których agent nie może ruszyć.
Zasada, którą piszesz, i kontrola, którą uruchamia harness
Hook Claude Code to mały skrypt, który uruchamia sam Claude Code w ustalonym momencie, przed wywołaniem narzędzia lub po nim. Gdy skrypt kończy się kodem błędu, to, co wypisał, wraca do Claude'a jako odmowa. Najlepsze praktyki Anthropic dzielą instrukcje na dwa rodzaje: te, które piszesz, a model czyta (prompt, plik CLAUDE.md, skill), i te, które konfigurujesz, a harness wykonuje (hook, reguła deny, ustawienie zarządzane). Dokumentacja pamięci mówi, że CLAUDE.md służy do wytycznych i że Claude może uznać, że wytyczna go nie dotyczy.
Sprawdziliśmy ten podział na małym API do faktur bez żadnych zapisanych zasad, prosząc Claude'a o harmonogramy cykliczne i eksport CSV raportu zaległości. Claude wrócił na zielono: typecheck przechodzi, wszystkie testy przechodzą. Detektor duplikacji pokazał co innego: parser faktur został skopiowany linia w linię do nowego parsera harmonogramów, a wyszukiwanie klienta z handlera do nowego handlera.
| Konfiguracja | Funkcje | Znalezione dokładne klony | Testy przechodzące |
|---|---|---|---|
| Zasady zapisane prozą w CLAUDE.md | 1 | 0 | 45 |
| Bez zapisanych zasad | 1, potem druga na wierzchu | 3, nadal 3 | 47, potem 55 |
Klony pozostały niewidoczne w raporcie Claude'a przy obu funkcjach. Każdy egzekutor z tego artykułu mieści się w jednym pliku ustawień w folderze .claude, z blokiem hooków i listą deny.
Zasada pierwsza: użyj, zanim napiszesz
Egzekutorem jest hook PostToolUse na narzędziach Edit i Write. Skrypt odczytuje ścieżkę edytowanego pliku z wejścia, uruchamia jscpd na folderze ze źródłami i porównuje liczbę klonów z punktem odniesienia zapisanym w repozytorium, żeby stara duplikacja nie blokowała dzisiejszej pracy. Gdy liczba rośnie, skrypt wypisuje zasadę oraz miejsce bliźniaka i kończy się kodem 2. Dokumentacja hooków mówi, że po wykonaniu narzędzia kod wyjścia 2 pokazuje komunikat Claude'owi, a skrypt kończący się kodem 0 nigdy nie jest widziany, cokolwiek wypisze.
Przy powtórce funkcji harmonogramów z zainstalowanym hookiem Claude napisał nowy handler i hook odpalił od razu, wskazując wyszukiwanie klienta w handlerze faktur jako bliźniaka. Następna linia Claude'a mówiła, że sprawdzenie jest teraz w obu handlerach i że przeniesie je do repozytorium klientów jako jedną metodę wywoływaną z obu miejsc. Na końcu detektor był czysty, a wspólne sprawdzenie żyło w jednym miejscu.
Ograniczenia: jscpd łapie dokładną kopię, a nie pomocnika napisanego od nowa, a hook uruchamiany po edycji nie może jej cofnąć. Daje informację zwrotną.
Zasada druga: żadnego modułu, o który nikt nie prosił
Egzekutorem jest hook PreToolUse na narzędziu Write. Skrypt sprawdza tylko jedno: czy ścieżka leży w folderze ze źródłami i czy plik jeszcze nie istnieje. Jeśli tak, wypisuje decyzję JSON z wartością ask i powodem, a Claude Code zamienia ją w prośbę o zgodę. Dokumentacja hooków podaje cztery możliwe decyzje hooka PreToolUse: allow, deny, ask lub defer.
Przy powtórce Claude Code zatrzymywał się i pytał przed każdym nowym modułem funkcji harmonogramów. Funkcja wymagała modułu harmonogramu, magazynu i handlera, jak reszta repozytorium, więc każdy z nich został zatwierdzony. Późniejsza prośba o przeniesienie pomocników CSV do nowego modułu utils wywołała ten sam komunikat i została odrzucona: Claude Code odrzucił oba zapisy z tej partii, tura skończyła się bez zapisania czegokolwiek, a Claude nie próbował ponownie.
Dwa ograniczenia w wersji, którą uruchamialiśmy, 2.1.294: komunikat pokazuje nazwę pliku, a powód trafia do transkrypcji Claude'a, nie do okna dialogowego; a plik utworzony poleceniem powłoki nie jest wywołaniem narzędzia Write, więc omija ten hook.
Zasada trzecia: konwencje to lint, a nie proza
Egzekutorem jest linter projektu, uruchamiany hookiem na każdym edytowanym pliku. Konwencje (aliasy typów zamiast interfejsów, żadnych enumów, żadnego any, warstwa domeny bez wejścia i wyjścia) przechodzą z prozy do konfiguracji ESLint: reguła restricted syntax odrzuca interfejs lub enum komunikatem projektu, a reguła restricted imports trzyma dostęp do plików poza folderem domeny. Hook PostToolUse na Edit i Write uruchamia ESLint na pliku, który właśnie się zmienił, i kończy się kodem 2 przy błędzie, więc naruszenie dociera do Claude'a w dokładnie tej linii.
Słowa konwencji zostają w pliku reguł w .claude/rules/ z nagłówkiem paths, który ładuje plik tylko wtedy, gdy Claude dotyka tego folderu. Dokumentacja pamięci mówi, że reguła ograniczona do ścieżek ładuje się, gdy Claude czyta, zapisuje lub edytuje pasujący plik, i ostrzega, że nagłówek, który się nie parsuje, sprawia, że reguła ładuje się wszędzie.
Poproszony o zamianę unii statusów na enum i typu na interfejs, Claude niczego nie edytował. Powiedział, że refaktoryzacja złamałaby własne reguły projektu, wskazał konfigurację lintera i hook, który oznaczyłby zmianę, i zaproponował zamiast tego obiekt const. Poproszony o funkcję świąt, która kusiła odczytem pliku w domenie, przekazał listę z zewnątrz, bo domena nie może robić wejścia ani wyjścia. Hook nie musiał nawet odpalić. Karmiony ręcznie złym plikiem, zwrócił błędy w ich liniach i odmowę.
Zasada czwarta: skończone znaczy, że kontrole przeszły
Egzekutorem jest hook Stop, skrypt uruchamiany, gdy Claude chce zakończyć turę, który może odpowiedzieć "jeszcze nie". Skrypt uruchamia typecheck i zestaw testów; gdy cokolwiek jest czerwone, wypisuje błędny wynik i kończy się kodem 2. Porównuje też liczbę przechodzących testów z zapisanym punktem odniesienia, więc zestaw, który wygląda na zielony, bo usunięto test, i tak liczy się jako czerwony. Sprawdza flagę stop_hook_active opisaną w dokumentacji, równą true, gdy Claude już kontynuuje z powodu hooka, i w takim przypadku kończy się kodem 0, żeby hook nigdy się nie zapętlił.
Grając pośpiesznego programistę, poprosiliśmy o szybką zmianę nazwy pola raportu i kazaliśmy Claude'owi nie uruchamiać testów. Claude zrobił edycję poleceniem powłoki, powiedział, że zestaw teraz padnie, i spróbował zakończyć turę. Hook uruchomił testy i odmówił komunikatem "Rule 4: tests fail. Not done yet.", po którym poszły błędne asercje. Następna linia Claude'a mówiła, że stop hook projektu wymaga zielonych testów, więc zaktualizuje nieaktualne oczekiwania. Testy zostały na miejscu.
Dokumentacja ogranicza pętlę do 8 kolejnych odmów, po których tura i tak się kończy. Test przepisany tak, by przechodził, nie zostanie złapany; usunięty tak. Jedna pułapka: szeroko udostępniany wątek skarżył się, że Claude ignoruje stop hooki, a skrypt w nim kończył się kodem 0, więc harness niczego nie blokował. Kodem blokującym jest 2, z powodem na kanale błędów.
Zasada piąta: agent nie poluzuje własnych bramek
Każda z powyższych kontroli ma skrót: wyłączyć strict w konfiguracji kompilatora, wykluczyć padający test w konfiguracji narzędzia testowego, usunąć hook z pliku ustawień. Egzekutorem jest lista deny w bloku uprawnień pliku ustawień, jedna linia Edit(...) na plik: konfiguracja kompilatora, konfiguracja testów, konfiguracja lintera i wszystko w folderze .claude. Dokumentacja uprawnień mówi, że reguły deny są oceniane jako pierwsze, a reguła allow nie może wyciąć wyjątku z reguły deny.
Poproszony o usunięcie stop hooka, bo spowalnia pracę, Claude przeczytał ustawienia i nie próbował: powiedział, że plik ma regułę deny na folder .claude, że mógłby ją obejść poleceniem powłoki i że zrobienie tego ominęłoby ochronę, którą zespół celowo ustawił. Poproszony o wyłączenie strict, odmówił na podstawie zapisanej reguły i zamiast tego uruchomił typecheck z flagą. Gdy kazaliśmy mimo to zmienić plik, Claude sięgnął po polecenie powłoki na pliku, a harness odpowiedział, że zgoda na użycie tego polecenia została odrzucona. Odpowiedź Claude'a brzmiała, że nie próbował innego obejścia, bo to zniweczyłoby to, co postawiło blokadę.
Ograniczenie jest również udokumentowane: reguła deny nie obejmuje skryptu, który sam otwiera plik, a plik wciąż można edytować ręcznie. O to właśnie chodzi.
Którą zasadę zainstalować najpierw
Każda zasada to plik, który kopiujesz, a nie zdanie, które masz nadzieję, że Claude przeczyta. Przy zasadach jako prozie jedna funkcja nie złamała żadnej z nich; przy braku jakichkolwiek zapisanych następne funkcje zostawiły trzy dokładne klony, które zostały; przy włączonych egzekutorach każdy z nich odrzucił prawdziwą edycję.
| Jeśli instalujesz jedną rzecz | Dlaczego |
|---|---|
| Hook Stop | Najwięcej ochrony za najmniej konfiguracji |
| Potem lista deny | Cztery linie w pliku ustawień |
| Nic | Na jednorazowym prototypie |
Gdy zestaw testów trwa minuty, zostaw w hooku szybką część, a resztę przenieś do pipeline'u. Uczciwe ograniczenie pochodzi z długiego zgłoszenia w repozytorium Claude Code: hook wymusza to, co może pokazać wywołanie narzędzia, a to, czy abstrakcja jest właściwa, pozostaje decyzją człowieka. Własna reguła kciuka z dokumentacji: jeśli ciągle dodajesz nacisk do linii w CLAUDE.md, a Claude wciąż ją pomija, ta linia należy do hooka.
AIDive