AIDive

Przyłapałem Claude Code na copy-paste. 5 zasad bez wyjątków

AIDive · Opublikowano

Agenty do kodowania

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.

Darmowe zasoby

Źródła

Najczęstsze pytania

Czy Claude Code wymusza zasady z CLAUDE.md?
Nie. Dokumentacja Anthropic mówi, że CLAUDE.md i pliki reguł są ładowane jako kontekst, a nie wymuszona konfiguracja, i że Claude może uznać, że wytyczna go nie dotyczy. Zasada, która nie może mieć wyjątków, należy do hooka, reguły deny lub ustawienia zarządzanego.
Czym jest hook Claude Code?
Skryptem, który Claude Code uruchamia w ustalonym momencie, przed wywołaniem narzędzia lub po nim albo gdy Claude chce zakończyć turę. Gdy skrypt kończy się kodem 2, to, co wypisał na stderr, wraca do Claude'a jako odmowa; skrypt kończący się kodem 0 nigdy nie jest widziany.
Jak powstrzymać Claude Code od kopiowania pomocników?
Hookiem PostToolUse na Edit i Write, który uruchamia detektor duplikacji, taki jak jscpd, na folderze ze źródłami, porównuje liczbę klonów z zapisanym punktem odniesienia i kończy się kodem 2 z miejscem bliźniaka, gdy liczba rośnie. Łapie dokładne kopie, nie przepisanych pomocników.
Jak sprawić, żeby Claude Code uruchamiał testy, zanim powie, że skończył?
Hookiem Stop, który uruchamia typecheck i zestaw testów i kończy się kodem 2 z błędnym wynikiem, dopóki cokolwiek jest czerwone. Sprawdź flagę stop_hook_active i zakończ kodem 0, gdy jest true, żeby hook się nie zapętlił; Claude Code ogranicza pętlę do 8 kolejnych odmów.
Czy Claude Code może wyłączyć własne hooki lub zmienić tsconfig.json?
Nie przy włączonej liście deny. Reguły deny Edit(path) w pliku ustawień na tsconfig.json, konfiguracjach testów i lintera oraz folderze .claude stosuje harness: w naszym teście sed przez Bash na tsconfig.json został odrzucony, zanim model dotknął pliku. Skrypt, który sam otwiera plik, nie jest objęty, a ręcznie nadal można edytować.
Dlaczego mój hook Stop nigdy nie blokuje?
Zwykle dlatego, że kończy się kodem 0. Blokowanie wymaga kodu wyjścia 2 z powodem na stderr; skrypt kończący się na cat z kodem 0 pozwala turze zakończyć się za każdym razem.

Powiązane filmy