Dlaczego agent AI ignoruje instrukcje w kodzie

Dlaczego agenci programistyczni ignorują instrukcje

Agenci programistyczni ignorują instrukcje z czterech powodów, z których żaden nie wynika z braku 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ę zbyt daleko od bieżącej tury, a agent pracuje w oparciu o informacje znajdujące się najbliżej.

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 sierpień 2026. Inne narzędzia różnią się szczegółami, ale w ogólnym zarysie działają w ten sam sposób.

Najpierw dwa terminy. Okno kontekstowe (context window) to blok tekstu, który model widzi w danej turze: prompt systemowy, pliki z instrukcjami, konwersacja oraz każdy plik odczytany przez agenta. Harness to program otaczający model, czyli komponent, który odczytuje pliki z dysku i składa wspomniany blok. Prawie 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 głównego katalogu systemu plików aż do katalogu roboczego, jest wczytywany w całości podczas startu. Pliki 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 poniżej katalogu roboczego zachowują się inaczej. Nie są one wczytywane podczas startu. Są wczytywane w momencie, gdy agent odczytuje plik znajdujący się w danym katalogu. To samo dotyczy reguł o zasięgu ścieżki w .claude/rules/, które zawierają pole paths: w nagłówku (frontmatter): wchodzą one do kontekstu w momencie odczytania pasującego pliku, a nie przy każdej turze konwersacji.

Ta jedna różnica wyjaśnia znaczną część zgłaszanych błędów. Umieszczasz regułę w packages/api/CLAUDE.md, zadajesz pytanie o API, a agent odpowiada, nie otwierając żadnego pliku w packages/api/. Reguła nie została zignorowana. Nigdy nie była obecna w kontekście. 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.

Istnieje jeszcze jedna pułapka związana z wczytywaniem, będąca najczęstszą przyczyną sytuacji, w których „agent zignorował moje instrukcje”: Claude Code odczytuje CLAUDE.md, a nie AGENTS.md. Repozytorium, które ustandaryzowało użycie AGENTS.md i nie posiada CLAUDE.md, nie dostarcza Claude Code żadnych danych do wczytania. Obsługiwanym rozwiązaniem jest plik CLAUDE.md, którego pierwsza linia to @AGENTS.md, co powoduje zaimportowanie pliku podczas startu wraz z wszelkimi uwagami specyficznymi dla Claude poniżej. Dowiązanie symboliczne (symlink) również działa, jeśli nie ma potrzeby dodawania dodatkowej treści. Decyzja o tym, co powinno znaleźć się w tym pliku, jest odrębną kwestią, omówioną w rozdzielaniu instrukcji dla agenta od dokumentacji dla ludzi.

Potwierdzenie wczytania pliku przed jego nadpisaniem

Nie należy modyfikować treści, dopóki nie ma pewności, że agent widzi dany plik. Istnieją dwie metody weryfikacji, z których pierwsza jest mniej obciążająca.

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, które zostały faktycznie wczytane. Plik nieobecny na tej liście nie znajduje się w konwersacji, więc wszelkie zmiany w nim wprowadzone nie przyniosą efektu. /memory wyświetla lokalizacje plików i otwiera je do edycji, w tym również te, 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 ładunek w formacie JSON na standardowe wejście, więc cat dopisuje cały rekord do pliku. Należy monitorować go za pomocą tail -f /tmp/instructions-loaded.log podczas pracy. Kod wyjścia tego zdarzenia jest ignorowany, co oznacza, że hook może jedynie obserwować, ale nie blokować operacji. Jeśli zagnieżdżony plik nie pojawia się w dzienniku podczas sesji, w której powinien zostać wczytany, należy przerwać edycję. Problem leży w lokalizacji pliku.

Wpływ długiej sesji na reguły

Występują tutaj dwa odrębne efekty, które wymagają różnych działań.

Dystans. Reguła podana w pierwszej turze nadal znajduje się w oknie kontekstowym w turze 90, ale konkuruje teraz z 90 turami tekstu, który jest nowszy i bardziej dopasowany do bieżących działań. Nie można tego wyeliminować poprzez konfigurację, ale można to zmierzyć. Należy wykonać to samo zadanie w nowej sesji. Jeśli reguła działa poprawnie w nowej sesji, a zawodzi w długiej, przyczyną jest dystans.

Kompakcja. Gdy okno się zapełnia, mechanizm podsumowuje dotychczasową konwersację i kontynuuje pracę na podstawie tego podsumowania. Przetrwa to, co podsumowujący uznał za istotne, co nie zawsze pokrywa się z priorytetami użytkownika. Claude Code dokumentuje wynik dla każdego mechanizmu, a różnice są znaczne. Reguły z katalogu głównego projektu CLAUDE.md oraz reguły bez określonego zakresu są ponownie wczytywane z dysku po kompakcji. Pamięć automatyczna (auto memory) jest ponownie wczytywana z dysku. Reguły z nagłówkiem paths: są tracone do momentu ponownego odczytania pasującego pliku. Zagnieżdżone pliki CLAUDE.md w podkatalogach są tracone do momentu ponownego odczytania pliku z tego podkatalogu.

Należy uszeregować instrukcje zgodnie z tą tabelą, aby określić ich podatność na utratę. Reguła wpisana tylko na czacie jest najbardziej nietrwałym elementem sesji: utrzymuje się tylko wtedy, gdy podsumowanie ją zachowało. Reguła w packages/api/CLAUDE.md jest kolejną w kolejności, ponieważ została wczytana raz, podsumowana i powraca dopiero przy następnym odczycie w danym katalogu. Reguła w pliku głównym projektu jest najbardziej trwała, ponieważ jest wczytywana 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 nagłówka paths:. Wszystkie inne rozwiązania to kompromisy, które należy stosować świadomie. Zarządzanie zawartością okna kontekstowego omawia /compact z argumentem focus oraz /clear między niezwiązanymi zadaniami; oba te elementy zmieniają 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ę przez app/repositories/. Pliki w app/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 test i 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

Wykonaj poniższe kroki w podanej kolejności. Pomijanie kroków i przechodzenie od razu do ostatniego to najczęstsza przyczyna powstawania długich list wykluczających się reguł, które nadal nie działają.

1. Potwierdź załadowanie. Uruchom /context i przejrzyj listę plików Memory. Jeśli pliku nie ma na liście, popraw jego lokalizację i przerwij dalsze działania. Żaden inny punkt z tej listy nie ma jeszcze zastosowania.
2. Odtwórz problem w nowej sesji. Rozpocznij nową sesję i wykonaj najmniejsze możliwe zadanie, które powinno wyzwolić regułę. Jeśli problem występuje tutaj, oznacza to, że błąd leży w samej regule. Jeśli reguła działa w nowej sesji, a zawodzi w długiej, przyczyną jest dystans lub kompresja danych.
3. Wyeliminuj konkurencję. Wymuś tę samą zmianę w katalogu, w którym istniejący kod jest już zgodny z regułą. Jeśli zgodność powróci, oznacza to, że otaczający kod był sprzeczny z Twoją instrukcją.
4. Wyszukaj konflikt. Dwa pliki zawierające odmienne wytyczne dla tego samego zachowania to udokumentowany błąd: model może wybrać dowolną z nich, nie informując o tym użytkownika.
5. 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 nieprecyzyjne sformułowanie.

Krok 4 to jedno polecenie. Przeszukaj wszystkie źródła instrukcji pod kątem danego tematu, a nie tylko plik, który aktualnie edytujesz:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

Znalezienie trafień w dwóch plikach, które zawierają sprzeczne informacje, wskazuje na błąd. Usuń jeden z nich. Nie próbuj nadawać im priorytetów poprzez silniejsze sformułowania, ponieważ nie istnieje mechanizm oceny ważności reguł.

Naprawy w kolejności od najskuteczniejszych

Każdy kolejny krok poniżej ma większą skuteczność niż poprzedni, 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.

1. 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 bezpłatne i rozwiązuje zaskakująco dużą liczbę przypadków.
2. 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 pojawia się wtedy w tym samym momencie, w którym czytany jest kod, którego dotyczy. Zaakceptuj kompromis: wszystko, co jest wczytywane w ten sposób, jest usuwane przy następnej kompresji i powraca przy kolejnym dopasowanym odczycie.
3. Przenieś egzekwowanie do hooka. Tekst prosi. Hook decyduje. Hooki działają jako kod w ustalonych punktach cyklu życia i są stosowane niezależnie od tego, do jakich wniosków dojdzie model.
4. Przekaż regułę do deterministycznego narzędzia i usuń tekst. Formatowanie, kolejność importów, długość linii, zabronione importy, format wiadomości commit. ruff format, prettier --write, eslint, hook pre-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 iteracji.

Krok 3 w szczegółach. 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 0

Uruchom chmod +x .claude/hooks/guard-migrations.sh, następnie rozpocznij nową sesję i poproś agenta o edycję pliku w migrations/. Edycja zostanie odrzucona, a Twoja wiadomość wróci jako powód. Kod wyjścia 2 w PreToolUse blokuje wywołanie narzędzia, zanim zostanie ono uruchomione, a tekst ze 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 system prompt, a nie w wiadomości użytkownika, --append-system-prompt umieszcza ją tam, choć musi być przekazywana przy każdym wywołaniu, 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?

Sprawdź, czy plik został wczytany, zanim założysz, że jest ignorowany. Uruchom /context i przejrzyj listę Memory files; plik, którego tam nie ma, nie znajduje się w konwersacji. 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, do którego agent nigdy nie zaglądał, 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 przeciwne do treści reguły.

Czy edycja pliku z instrukcjami w trakcie sesji coś zmienia?

Nie dla kopii, która już znajduje się w konwersacji. Pliki znajdujące się powyżej katalogu roboczego są wczytywane w całości podczas uruchomienia, więc tekst, którym dysponuje model, pochodzi 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 bieżącą wersję do konwersacji jako nową wiadomość. Po kompresji (compaction) 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ą ze sobą sprzeczne?

Żaden w sposób niezawodny. Wykryte pliki są łączone w kontekście, zamiast się wzajemnie nadpisywać, w kolejności od głównego katalogu systemu plików aż 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 stwierdza, że sprzeczne reguły mogą być rozstrzygane arbitralnie. Zagnieżdżone pliki należy tworzyć jako uzupełnienia, które wskazują ścieżkę, której dotyczą, a sprzeczne zapisy należy usuwać, zamiast próbować je nadpisywać.

Czy moje instrukcje przetrwają polecenie /compact?

Zależy to od sposobu ich wczytania. Reguły z głównego katalogu projektu CLAUDE.md, reguły bez określonego zakresu oraz automatyczna pamięć są ponownie wstrzykiwane z dysku po kompresji. Reguły z frontmatter paths: oraz zagnieżdżone pliki CLAUDE.md w podkatalogach są tracone do momentu ponownego odczytania pasującego pliku. Wszystko, co wpisano bezpośrednio w czacie, przetrwa tylko wtedy, gdy mechanizm podsumowujący (summariser) zachowa te informacje. Jeśli reguła musi obowiązywać przez całą sesję, umieść ją w pliku w głównym katalogu projektu bez frontmatter paths:.

Kiedy reguła powinna stać się hookiem zamiast tekstu opisowego?

Gdy weryfikacja jest deterministyczna, a koszt pominięcia reguły jest wyższy niż koszt napisania krótkiego skryptu. Ograniczenia ścieżek plików, wymagane polecenia przed wykonaniem commit oraz zabronione wywołania narzędzi kwalifikują się do tego rozwiązania. Hook PreToolUse, który kończy się statusem 2, blokuje wywołanie narzędzia i zwraca tekst stderr do modelu jako powód, więc reguła działa niezależnie od tego, czy znajduje się w kontekście. Wszystko, co może zostać rozstrzygnięte przez formater lub linter, powinno być obsługiwane przez te narzędzia i całkowicie usunięte z pliku z instrukcjami.