Dlaczego agenci programujący ignorują instrukcje
Agent ignoruje regułę STOP mimo pliku instrukcji? Sprawdź, czy reguła trafiła do okna kontekstowego, jest jednoznaczna lub nie koliduje z odczytanym kodem.
Dlaczego agenci programujący ignorują instrukcje
Agenci programujący ignorują instrukcje z czterech powodów i żaden z nich nie wynika z nadmiernej uprzejmości użytkownika. Zasada nie znalazła się w oknie kontekstowym. Zasada była zbyt niejasna, aby można było zweryfikować podjęte działanie. Inny element kontekstu był z nią sprzeczny, zazwyczaj kod, który agent przed chwilą odczytał. Ewentualnie zasada jest wczytana, ale znajduje się daleko za bieżącą turą, a agent pracuje w oparciu o dane znajdujące się w pobliżu.
Każda przyczyna wymaga innego rozwiązania, dlatego pierwszym krokiem jest ich rozróżnienie. Wielkie litery i słowo IMPORTANT nie stanowią diagnozy. Poniższe mechanizmy opisano na przykładzie Claude Code, ponieważ jego zachowanie w zakresie wczytywania i kompresji danych jest szczegółowo udokumentowane na październik 2026. Inne narzędzia różnią się szczegółami, lecz w ogólnym zarysie działają w ten sam sposób.
Najpierw dwa terminy. Okno kontekstowe to blok tekstu, który model widzi w danej turze: prompt systemowy, pliki z instrukcjami użytkownika, konwersacja oraz każdy plik odczytany przez agenta. Harness to program otaczający model, który odczytuje pliki z dysku i składa wspomniany blok. Niemal każda skarga w tym tekście dotyczy w rzeczywistości mechanizmu harness, a nie samego modelu.
Plik instrukcji jest wiadomością, a nie ustawieniem
Plik instrukcji nie jest konfiguracją. Żaden element środowiska wykonawczego nie odczytuje CLAUDE.md w celu wymuszenia jego zawartości. Narzędzie odczytuje plik z dysku i wkleja jego tekst do konwersacji. W Claude Code treść ta jest dostarczana jako wiadomość użytkownika umieszczona po systemowym prompcie, co oznacza, że model postrzega te reguły w taki sam sposób, jak każdy inny wprowadzony tekst.
Ma to istotną konsekwencję. Reguły konkurują z każdym innym fragmentem tekstu w oknie na równych prawach. Reguła jest twierdzeniem. Plik, który agent właśnie otworzył, jest dowodem. Gdy te dwa elementy są sprzeczne, dowód często wygrywa, a system nie zgłasza błędu, ponieważ z punktu widzenia modelu nie wydarzyło się nic niewłaściwego.
Oficjalna dokumentacja stwierdza to wprost: pliki instrukcji są traktowane jako kontekst, a nie wymuszona konfiguracja. Aby zablokować działanie niezależnie od decyzji modelu, potrzebny jest mechanizm kontrolny (hook), a nie zdanie. Należy o tym pamiętać. Większość rozwiązań przedstawionych na końcu tego wpisu to właśnie takie mechanizmy zastosowane w konkretnych przypadkach.
Które pliki instrukcji są wczytywane i kiedy
Claude Code przeszukuje drzewo katalogów, zaczynając od folderu, w którym został uruchomiony. Każdy plik CLAUDE.md oraz CLAUDE.local.md, począwszy od katalogu głównego systemu plików aż po bieżący katalog roboczy, jest wczytywany w całości podczas uruchomienia. Pliki te są łączone w tej kolejności, co oznacza, że plik znajdujący się najbliżej miejsca uruchomienia jest odczytywany jako ostatni, a w obrębie jednego katalogu plik .local jest dołączany po pliku głównym.
Pliki w podkatalogach znajdujących się poniżej katalogu roboczego zachowują się inaczej. Nie są one wczytywane podczas uruchomienia. Są wczytywane w momencie, gdy agent odczytuje plik w danym katalogu. To samo dotyczy reguł o zasięgu ścieżki w .claude/rules/, które zawierają pole frontmatter paths:: trafiają one do kontekstu w momencie odczytania pasującego pliku, a nie przy każdym zapytaniu. Od wersji v2.1.309 pliki wczytywane w ten sposób mają również limit rozmiaru na plik (40 000 znaków przy oknie kontekstowym 200K), a agent otrzymuje tylko początek dłuższego pliku, więc reguły znajdujące się pod koniec dużego, zagnieżdżonego pliku mogą nigdy nie trafić do kontekstu.
Ta jedna różnica wyjaśnia znaczną część zgłaszanych błędów. Umieszczasz regułę w packages/api/CLAUDE.md, zadajesz pytanie dotyczące API, a agent odpowiada, nigdy nie otwierając pliku w packages/api/. Reguła nie została zignorowana. Nigdy nie była obecna. Jeśli repozytorium rozdziela wytyczne zgodnie z plikami instrukcji dla poszczególnych pakietów w monorepo, jest to pierwsza rzecz, którą należy sprawdzić w każdym przypadku.
Jeszcze jedna pułapka związana z wczytywaniem dotyczy repozytoriów, które ustandaryzowały użycie AGENTS.md. Od wersji v2.1.277 Claude Code domyślnie odczytuje AGENTS.md jako instrukcje projektu, ale tylko wtedy, gdy w katalogu roboczym lub dowolnym katalogu nadrzędnym nie znajduje się CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md (osobisty plik ~/.claude/CLAUDE.md nie jest brany pod uwagę). Dodanie któregokolwiek z nich, nawet CLAUDE.local.md z osobistymi notatkami, sprawia, że Claude Code odczytuje pliki CLAUDE.md, całkowicie pomijając AGENTS.md. Aby wczytać oba, należy ustawić Project instructions na claude-md-and-agents-md w /config. W wersjach starszych niż v2.1.277 lub w przypadku chęci zachowania CLAUDE.md, rozwiązaniem jest CLAUDE.md, którego pierwsza linia to @AGENTS.md, co powoduje zaimportowanie pliku przy uruchomieniu, wraz z wszelkimi notatkami specyficznymi dla Claude poniżej. Dowiązanie symboliczne (symlink) również działa, jeśli nie ma nic dodatkowego do dodania. Decyzja o tym, co powinno znaleźć się w tym pliku, jest osobnym zagadnieniem, omówionym w rozdzielaniu instrukcji dla agenta od dokumentacji dla ludzi.
Potwierdzenie wczytania pliku przed jego nadpisaniem
Nie należy zmieniać treści pliku, dopóki nie ma pewności, że agent go widzi. Istnieją dwie metody weryfikacji, z których pierwsza jest mniej kosztowna.
Należy wykonać /context wewnątrz sesji. Polecenie to wyświetla bieżące okno z podziałem na kategorie, a lista Memory files zawiera nazwy wszystkich plików instrukcji wczytanych podczas uruchomienia. Plik nieobecny na tej liście nie został wczytany przy starcie, więc wszelkie zmiany w nim nie przyniosą efektu, dopóki nie zostanie on wczytany. Plik zagnieżdżony w podkatalogu nigdy nie pojawi się na tej liście, ponieważ jest wczytywany na żądanie; w momencie wczytania w terminalu pojawia się wiersz Loaded ze ścieżką do tego pliku. /memory wyświetla lokalizacje plików i otwiera je do edycji, w tym pliki, które jeszcze nie istnieją.
W celu uzyskania bardziej szczegółowych informacji należy rejestrować zdarzenia wczytywania. Zdarzenie typu hook InstructionsLoaded jest wyzwalane za każdym razem, gdy CLAUDE.md lub plik reguł trafia do kontekstu, a jego mechanizm dopasowania wskazuje przyczynę wczytania: session_start, nested_traversal, path_glob_match, include lub compact. Należy umieścić poniższy kod w .claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}Hook otrzymuje dane w formacie JSON na standardowe wejście, więc cat dopisuje cały rekord. Podczas pracy należy monitorować plik za pomocą tail -f /tmp/instructions-loaded.log. Kod wyjścia tego zdarzenia jest ignorowany, więc hook może jedynie obserwować, ale nie blokować. Jeśli plik zagnieżdżony nigdy nie pojawia się w dzienniku podczas sesji, w której oczekiwano jego wczytania, należy przerwać edycję. Problem leży w lokalizacji pliku. Wyjątek stanowi AGENTS.md, który Claude Code odczytuje bezpośrednio i nie wyzwala tego zdarzenia, dlatego należy szukać jego ścieżki w /memory. AGENTS.md zaimportowany z CLAUDE.md wyzwala zdarzenie w standardowy sposób.
Wpływ długiej sesji na reguły
Występują tutaj dwa odrębne efekty, które wymagają różnych działań.
Dystans. Do momentu wykonania kompresji (compaction), reguła podana w turze 1 nadal znajduje się w oknie kontekstowym w turze 90, konkurując z 90 turami tekstu, który jest nowszy i bardziej specyficzny dla bieżących działań. Po wykonaniu kompresji reguła wpisana tylko na czacie może w ogóle nie znajdować się w oknie. Dokumentacja Claude Code ostrzega, że instrukcje z wczesnego etapu konwersacji mogą zostać utracone, co stanowi drugi z poniższych efektów. Dystansu nie można skonfigurować, ale można go zmierzyć. Należy uruchomić to samo zadanie w nowej sesji. Jeśli reguła działa poprawnie w nowej sesji, a zawodzi w głębokiej fazie długiej sesji, przyczyną jest dystans lub kompresja.
Kompresja. Gdy okno się zapełnia, mechanizm sterujący podsumowuje dotychczasową konwersację i kontynuuje działanie na podstawie tego podsumowania. Przetrwa to, co podsumowujący uznał za istotne, co nie zawsze jest tożsame z tym, co użytkownik uważa za ważne. Claude Code dokumentuje wyniki dla każdego mechanizmu, a różnice są znaczne. Katalog główny projektu CLAUDE.md oraz reguły bez określonego zakresu są ponownie wczytywane z dysku po kompresji. Pamięć automatyczna (auto memory) jest również ponownie wczytywana z dysku. Reguły z frontmatterem paths: są tracone do momentu ponownego odczytania pasującego pliku. Zagnieżdżone pliki CLAUDE.md w podkatalogach są tracone do momentu odczytania pliku z tego podkatalogu.
Należy uszeregować instrukcje według powyższej tabeli, co pozwoli określić stopień ich trwałości. Reguła wpisana tylko na czacie jest najbardziej nietrwałym elementem sesji: pozostaje w niej tylko wtedy, gdy podsumowanie ją uwzględniło. Reguła w packages/api/CLAUDE.md jest kolejną w kolejności, ponieważ została wczytana raz, usunięta podczas podsumowania i powraca dopiero przy następnym odczycie w danym katalogu. Reguła w pliku głównym projektu jest najbardziej trwała, ponieważ jest ponownie odczytywana z dysku przy każdym wywołaniu.
Jeśli instrukcja musi obowiązywać przez całą sesję, powinna znajdować się w pliku głównym projektu bez frontmattera paths:. Wszystkie inne rozwiązania są kompromisami, które należy stosować świadomie. Zarządzanie zawartością okna kontekstowego omawia /compact z argumentem focus oraz /clear między niepowiązanymi zadaniami; oba te elementy wpływają na częstotliwość, z jaką mechanizm podsumowujący decyduje o tym, jakie były Twoje reguły.
Dlaczego otaczający kod przeważa nad regułą
Jest to błąd najczęściej opisywany przez użytkowników i najrzadziej diagnozowany. Plik konfiguracyjny wskazuje, że dostęp do bazy danych powinien odbywać się przez warstwę repozytorium. Agent tworzy jednak procedurę obsługi, która wywołuje ORM (object relational mapper) bezpośrednio. Decyzja ta nie wynika z ignorowania stylu, lecz z przewagi dowodów.
Reguła opisuje preferencję. Kod natomiast demonstruje rzeczywistość. Gdy agent otwiera trzy pliki w module, który ma edytować, i wszystkie trzy wywołują ORM bezpośrednio, kontekst zawiera jedno abstrakcyjne zdanie po jednej stronie oraz trzy konkretne, aktualne i dopasowane do zadania przykłady po drugiej. Powielanie lokalnego wzorca jest zazwyczaj poprawnym zachowaniem. W tym przypadku jest błędne tylko dlatego, że użytkownik posiada wiedzę, której brakuje kontekstowi: te pliki to kod typu legacy.
Należy zatem uwzględnić to w regule. Reguły, które wskazują własne kontrargumenty, sprawdzają się w pracy z rzeczywistym repozytorium. Reguły wyrażające jedynie ogólną preferencję – nie.
Nowy dostęp do bazy danych musi odbywać się przezapp/repositories/. Pliki wapp/legacy/nadal wywołują ORM bezpośrednio. Jest to stary kod, a nie obowiązujący wzorzec. Nie należy go powielać.
Drugie zdanie wykonuje kluczową pracę. Informuje agenta o tym, co zaraz napotka i jak powinien to zinterpretować, zanim jeszcze dojdzie do analizy. Ta sama metoda naprawcza ma zastosowanie do każdej reguły, której repozytorium jawnie przeczy: stylu commitów, którego historia nie przestrzega, układu testów, który jest ignorowany przez połowę zestawu, czy konwencji importów obowiązującej tylko w nowym kodzie. Wszędzie tam, gdzie kod nie zgadza się z plikiem reguł, należy nazwać tę rozbieżność w samym pliku.
Niejasna reguła jest niemożliwa do zweryfikowania, a zatem nie można jej przestrzegać
„Pisz czysty kod”. „Nie przekombinuj”. „Utrzymuj prostotę”. „Uważaj przy migracjach”. Żadnego z tych zaleceń nie da się przetestować pod kątem konkretnego działania, ani przez agenta, ani przez użytkownika. Agent, który otrzymuje regułę niemożliwą do sprawdzenia względem własnego wyniku, zgaduje, a użytkownik ocenia to zgadnięcie „na wyczucie”.
Oto test, który należy zastosować do każdej linii w pliku. Napisz polecenie powłoki, które zakończy się niezerowym kodem wyjścia, gdy reguła zostanie złamana. Jeśli nie potrafisz napisać takiego polecenia, reguła nie jest sprawdzalna. Porównaj poniższe pary:
- Niesprawdzalne: „Utrzymuj małe funkcje”. Sprawdzalne: „Funkcja dłuższa niż 60 linii musi posiadać komentarz wyjaśniający przyczynę”.
- Niesprawdzalne: „Testuj zmiany”. Sprawdzalne: „Uruchom
npm testi wklej liczbę błędów przed oznaczeniem zadania jako wykonane”. - Niesprawdzalne: „Utrzymuj porządek w plikach”. Sprawdzalne: „Handlery HTTP znajdują się w
src/api/handlers/. Żadne inne pliki nie mogą znajdować się w tym katalogu”. - Niesprawdzalne: „Formatuj kod poprawnie”. Sprawdzalne: „Używaj wcięcia 2 spacji w plikach
.ts”.
„Nie przekombinuj” to reguła, z której ludzie rezygnują najszybciej, ponieważ naprawa nie polega na skróceniu zdania, lecz na jego wydłużeniu: precyzyjne określenie, co faktycznie oznacza najmniejsza działająca zmiana dostarcza agentowi kryteriów, do których może odnieść własny diff.
Rozmiar pliku to ten sam problem w innym wydaniu. Wytyczne Claude Code zalecają mniej niż 200 linii na plik instrukcji i wprost stwierdzają, że dłuższe pliki obniżają skuteczność przestrzegania zasad. Plik o długości 700 linii nie jest bardziej stanowczą instrukcją. To 700 linii twierdzeń, które częściej mogą być ze sobą sprzeczne, a ponadto obciążają okno kontekstowe w każdej turze, co bezpośrednio przekłada się na zużycie tokenów. Strukturyzowanie pliku tak, aby każda reguła znajdowała się pod nagłówkiem, który czytelnik może szybko przejrzeć, zostało omówione w pisaniu pliku instrukcji, na podstawie którego agent może działać. Co więcej, usuń części, które opisują, zamiast instruować: przegląd katalogów, w których znajdują się handlery i modele, to struktura, którą agent może sprawdzić na żądanie z przeanalizowanej mapy repozytorium, zamiast przechowywać ją w oknie kontekstowym w każdej turze.
Jak zdiagnozować problem w dziesięć minut
Należy wykonać poniższe kroki w podanej kolejności. Pominięcie ostatniego etapu prowadzi do tworzenia długich list wykluczających się reguł, które nie działają.
- Potwierdź załadowanie. Uruchom
/contexti przejrzyj listę plików Memory, a w przypadku pliku zagnieżdżonego wyszukaj jego linięLoadedw terminalu. Jeśli pliku nie ma na liście, popraw jego lokalizację i przerwij dalsze czynności. Żaden inny punkt z tej listy nie ma jeszcze zastosowania. - Odtwórz problem w nowej sesji. Rozpocznij nową sesję i wykonaj najmniejsze możliwe zadanie, które powinno wyzwolić regułę. Jeśli reguła działa tutaj, ale zawodzi w długiej sesji, przyczyną jest dystans lub kompresja kontekstu. Jeśli zawodzi również tutaj, problemem jest sama treść reguły.
- Wyeliminuj konkurencję. Wprowadź to samo żądanie w katalogu, którego istniejący kod jest już zgodny z regułą. Jeśli zgodność powróci, oznacza to, że otaczający kod był ważniejszy niż Twoja instrukcja.
- Wyszukaj konflikt. Dwa pliki zawierające sprzeczne wytyczne dotyczące tego samego zachowania to udokumentowany błąd: model może wybrać jeden z nich w sposób arbitralny, nie informując o tym użytkownika.
- Uczyń regułę weryfikowalną i przetestuj ponownie. Przepisz regułę, używając konkretnej ścieżki i warunku. Znaczny wzrost zgodności oznacza, że przyczyną było sformułowanie instrukcji.
Krok 4 sprowadza się do jednego polecenia. Przeszukaj wszystkie źródła instrukcji pod kątem danego tematu, a nie tylko plik, który był edytowany:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/nullZnalezienie trafień w dwóch plikach, które podają sprzeczne informacje, wskazuje na błąd. Usuń jeden z nich. Nie próbuj nadawać im priorytetu poprzez silniejsze sformułowania, ponieważ nie istnieje mechanizm oceny ważności reguł. W wersji Claude Code v2.1.283 lub nowszej, /doctor prompt-audit uruchamia szersze wyszukiwanie w plikach instrukcji, regułach i umiejętnościach, zgłaszając sprzeczności wraz z propozycjami poprawek bez wprowadzania zmian do momentu zatwierdzenia przez użytkownika.
Naprawy w kolejności skuteczności
Każdy poniższy krok jest skuteczniejszy od poprzedniego, ale wymaga większego nakładu pracy przy konfiguracji. Należy zacząć od góry, gdy regułę można łatwo przeformułować. Należy przejść niżej w momencie, gdy reguła staje się na tyle istotna, że sporadyczne błędy są niedopuszczalne.
- Uczyń regułę konkretną. Wskaż ścieżkę, polecenie lub warunek. Dodaj kontrargumenty, które agent znajdzie w repozytorium, zgodnie z wcześniejszymi przykładami. Jest to darmowe i rozwiązuje zaskakująco dużą liczbę przypadków.
- Przenieś regułę bliżej tego, czego dotyczy. Zagnieżdżony
CLAUDE.md, reguła ograniczona do ścieżki w.claude/rules/lub komentarz na początku samego pliku. Reguła dociera do agenta w tym samym momencie, w którym czyta on kod, którego ona dotyczy. Zaakceptuj kompromis: wszystko, co jest ładowane w ten sposób, jest usuwane przy następnej kompresji i powraca przy kolejnym dopasowanym odczycie. - Przenieś egzekwowanie do hooka. Tekst prosi. Hook decyduje. Hooki działają jako kod w ustalonych punktach cyklu życia i mają zastosowanie niezależnie od wniosków modelu.
- Przekaż regułę do deterministycznego narzędzia i usuń tekst. Formatowanie, kolejność importów, długość linii, zakazane importy, format komunikatu commit.
ruff format,prettier --write,eslint, hookpre-commit. Formatter ma rację za każdym razem i kosztuje zero tokenów. Zdanie ma rację w większości przypadków i kosztuje tokeny przy każdej turze.
Krok 3 w całości. Załóżmy, że pliki migracji nigdy nie mogą być edytowane przez agenta. Umieść to w .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}Oraz to w .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0Uruchom chmod +x .claude/hooks/guard-migrations.sh, następnie rozpocznij nową sesję i poproś agenta o edycję pliku w migrations/. Edycja zostanie odrzucona, a Twój komunikat powróci jako powód. Status wyjścia 2 w PreToolUse blokuje wywołanie narzędzia przed jego uruchomieniem, a tekst z stderr jest przekazywany do modelu jako komunikat blokujący. ${CLAUDE_PROJECT_DIR} wskazuje na katalog główny projektu, więc hook działa niezależnie od tego, w jakim katalogu znajduje się agent. Agent nie musi zgadzać się z regułą, pamiętać o niej ani mieć jej w kontekście. Edycja nie następuje.
W przypadku całkowitego zakazu bez logiki, permissions.deny w ustawieniach wykonuje to samo zadanie bez konieczności utrzymywania skryptu, a tryby uprawnień decydują o tym, co zostanie uruchomione bez wcześniejszego pytania. Jeśli instrukcja musi znajdować się na poziomie promptu systemowego, a nie w komunikacie użytkownika, --append-system-prompt umieszcza ją tam, choć jest to flaga startowa, którą trzeba przekazywać przy każdej nowej sesji, co lepiej sprawdza się w skryptach niż w pracy interaktywnej.
Czego nie da się wyeliminować instrukcją
Należy wyraźnie rozróżnić, co zależy od użytkownika, a co od modelu. Rozmieszczenie, sformułowania, konflikty między plikami oraz rozmiar plików to problemy autora, które wymagają jego interwencji. Reszta to zachowanie modelu, którego lepsze sformułowanie poleceń nie wyeliminuje.
Zgoda nie oznacza przestrzegania zasad. Agent potwierdzi regułę, powtórzy ją poprawnie, a dwa wywołania narzędzi później ją złamie. Potwierdzenie nic nie kosztuje i niczego nie gwarantuje. Nie należy traktować go jako rozwiązania ani jako testu.
Niektóre nawyki są trwałe. Dodawanie komentarzy, defensywna obsługa błędów, pisanie podsumowań czy uruchamianie oczywistych kolejnych poleceń. Powracają one nawet przy regule, która ich zabrania, choć z mniejszą częstotliwością. Można zmierzyć własny wskaźnik błędów: należy wykonać to samo zadanie dziesięć razy w nowych sesjach i policzyć naruszenia. Jeśli liczba ta musi wynosić zero, reguła musi zostać usunięta z promptu. Uznanie zadania za ukończone, gdy część pracy jest niedokończona, to ten sam typ nawyku. Naprawa ma charakter strukturalny, a nie werbalny: umiejętność unikania lenistwa zamienia zdanie na drzewo głębokości (Depth Tree) i wymaga od agenta przejścia przez pliki kontrolne, zanim będzie mógł ogłosić zakończenie pracy.
Własna sesja staje się przykładem. Jeśli agent złamał regułę w 12. kroku, a użytkownik pozwolił na to, naruszenie to pozostaje w kontekście jako wzorzec, który jest znacznie świeższy niż sama reguła. Należy korygować naruszenie w momencie jego wystąpienia. Niepoprawione naruszenie uczy agenta zachowania na resztę sesji.
Plik z instrukcjami nie jest barierą bezpieczeństwa. Kształtuje on zachowanie, ale go nie wymusza. Wszystko, gdzie błąd jest kosztowny, jak dane uwierzytelniające czy destrukcyjne polecenia, powinno być objęte uprawnieniami lub hookami. Utrzymywanie sekretów poza zasięgiem agenta stosuje tę samą zasadę do danych: nie należy prosić agenta, aby nie czytał pliku, lecz zadbać o to, by plik nie był dla niego czytelny.
W skrócie: należy potwierdzić wczytanie pliku, uczynić regułę sprawdzalną, umieścić ją obok elementu, którego dotyczy, a gdy wskaźnik błędów nadal jest istotny, usunąć ją z tekstu instrukcji. Reguła, której agent nie może zignorować, to taka, o którą agenta nigdy nie proszono.
FAQ
Dlaczego Claude Code ignoruje mój plik CLAUDE.md?
Przed założeniem, że plik został zignorowany, sprawdź, czy został wczytany. Uruchom /context i przejrzyj listę Memory files; plik, którego nie ma na tej liście, nie został wczytany podczas uruchamiania. Pliki z instrukcjami są dostarczane jako wiadomość użytkownika po systemowym prompcie i są traktowane jako kontekst, a nie wymuszona konfiguracja, dlatego nie ma gwarancji ścisłego przestrzegania zasad. Większość rzeczywistych przypadków wynika z jednej z czterech przyczyn: plik znajduje się w podkatalogu, z którego agent nigdy nie czytał, dwa pliki są ze sobą sprzeczne i model wybrał jeden z nich arbitralnie, reguła jest zbyt niejasna, aby zweryfikować działanie, lub otaczający kod demonstruje zachowanie odwrotne do treści reguły.
Czy edycja pliku z instrukcjami w trakcie sesji wprowadza zmiany?
Nie w przypadku kopii znajdującej się już w konwersacji. Pliki znajdujące się powyżej katalogu roboczego są wczytywane w całości podczas uruchamiania, więc tekst, którym dysponuje model, to tekst z momentu startu. Aby uwzględnić edycję, rozpocznij nową sesję lub poproś agenta o odczytanie pliku za pomocą standardowych narzędzi do obsługi plików, co wprowadzi aktualną wersję do konwersacji jako nową wiadomość. Po operacji CLAUDE.md plik z głównego katalogu projektu jest ponownie odczytywany z dysku, więc nowa wersja pojawia się w tym momencie.
Który plik ma pierwszeństwo, gdy główny CLAUDE.md i zagnieżdżony plik są sprzeczne?
Żaden w sposób niezawodny. Wykryte pliki są łączone w kontekście, zamiast się nadpisywać, w kolejności od głównego katalogu systemu plików w dół do katalogu roboczego, więc plik znajdujący się najbliżej jest po prostu odczytywany jako ostatni. Nie istnieje mechanizm priorytetów rozstrzygający sprzeczności, a dokumentacja Claude Code wskazuje, że sprzeczne reguły mogą być rozstrzygane arbitralnie. Zagnieżdżone pliki należy tworzyć jako uzupełnienia wskazujące ścieżkę, której dotyczą, a sprzeczne zapisy usuwać, zamiast próbować je nadpisywać.
Czy moje instrukcje przetrwają operację /compact?
Zależy to od sposobu ich wczytania. Pliki CLAUDE.md z głównego katalogu projektu, reguły bez określonego zakresu oraz automatyczna pamięć są ponownie wczytywane z dysku po kompaktowaniu. Reguły z frontmatterem paths: oraz zagnieżdżone pliki CLAUDE.md w podkatalogach są tracone do momentu ponownego odczytania pasującego pliku. Wszystko, co zostało wpisane bezpośrednio w czacie, przetrwa tylko wtedy, gdy mechanizm podsumowujący zachowa te informacje. Jeśli reguła musi obowiązywać przez całą sesję, umieść ją w pliku w głównym katalogu projektu bez frontmattera paths:.
Kiedy reguła powinna stać się hookiem zamiast tekstu opisowego?
Gdy weryfikacja jest deterministyczna, a koszt błędu przewyższa koszt napisania krótkiego skryptu. Ograniczenia ścieżek plików, wymagane polecenia przed wykonaniem commitu oraz zabronione wywołania narzędzi spełniają te kryteria. Hook PreToolUse, który kończy działanie ze statusem 2, całkowicie blokuje wywołanie narzędzia i zwraca tekst stderr do modelu jako uzasadnienie, dzięki czemu reguła działa niezależnie od tego, czy znajduje się w kontekście. Wszystko, co może zostać zweryfikowane przez formater lub linter, powinno być obsługiwane przez te narzędzia i całkowicie usunięte z pliku z instrukcjami.