Gdzie znajdują się instrukcje Claude Code: CLAUDE.md, zasady ścieżek lub hooki

Większość zespołów używających Claude Code przechowuje obecnie plik CLAUDE.md, ale niewiele z nich potrafi stwierdzić, czy ten plik faktycznie coś robi. Częstym wzorcem jest plik, który rozrósł się do kilkuset wierszy, przy czym model wykonuje niektóre instrukcje, a inne pomija w milczeniu. Rozwiązaniem rzadko jest lepszy szablon; chodzi raczej o zrozumienie, czym tak naprawdę jest ten plik, oraz o kierowanie każdą instrukcją do mechanizmu, który jest w stanie ją wykonać. Ten przewodnik omawia siedem praktycznych wzorców – od skracania pliku, przez ustalanie zasad na podstawie ścieżki, po przenoszenie wymagań obowiązkowych do elementów typu hooks oraz sprawdzanie tego, co rzeczywiście załadował Claude.

Jeśli zaczynasz od pustego pliku, praktyczny przewodnik dotyczący tworzenia skutecznego pliku CLAUDE.md omawia treść i strukturę. Tutaj nacisk kładziony jest na coś innego: które instrukcje w ogóle powinny znaleźć się w pliku CLAUDE.md oraz gdzie powinien trafić reszta.

CLAUDE.md to kontekst, a nie konfiguracja

Każdy inny problem wynika z tego błędnego założenia. Claude Code wstawia plik do rozmowy jako wiadomość; nie jest on łączony z systemowym promptem, a nic w czasie wykonywania nie wymusza jego przestrzegania. Model go czyta i stara się go realizować. Nie ma żadnych gwarancji poza tym, a szanse na skuteczne działanie maleją jeszcze bardziej, gdy sformułowania są niejasne lub dwie instrukcje kierują w różnych stronach.

Korzystnym modelem myślowym jest notatka przekazująca informacje do wykwalifikowanego kolegi z zespołu, który przegląda ją przy porannej kawie, a następnie angażuje się w rzeczywistą pracę. To, co przetrwa ten proces, to materiał krótki, konkretny i spójny. Dlatego długość, precyzja oraz spójność wewnętrzna są jedynymi rzeczywistymi narzędziami, jakimi dysponujemy, a nie kwestiami stylu.

Zachowaj plik źródłowy poniżej 200 wierszy

Obecna zalecenie polega na utrzymaniu liczby wierszy poniżej około 200. Przekroczenie tego limitu powoduje, że plik zajmuje więcej miejsca w oknie kontekstowym, a przestrzeganie zasad staje się gorsze, a nie lepsze.

To jest sprzeczne z intuicją: im więcej instrukcji, tym mniej z nich jest przestrzeganych. Każdy wiersz konkujuje o tę samą ograniczoną ilość uwagi z każdym innym wierszem oraz z samą rozmową. Weźmy za przykład zespół, którego plik liczył 340 wierszy. Po skróceniu go do około 120 wierszy Claude przestrzegał instrukcji bardziej skutecznie. Żaden z usuniętych wierszy nie był błędny; były to po prostu elementy zbędne, dodane na wierzch istotnych instrukcji.

Istnieje również sztywny limit, choć nie chcesz projektować z myślą o nim: według dokumentacji z czasu pisania tego tekstu pliki większe niż 4 MiB są całkowicie pomijane. Skuteczność działania systemu pogarsza się znacznie przed osiągnięciem takiej wielkości pliku.

Usuń to, co Claude może odkryć w repozytorium

Najskuteczniejsza zasada edycji jest prosta: usuń wszystko, co Claude mógłby odkryć samodzielnie, czytając kod. Jest to zgodne z rekomendacjami narzędzia /doctor w Claude Code, które usuwa strukturę folderów, listy zależności oraz opisy architektury na wysokim poziomie, zachowując jednocześnie potencjalne problemy, uzasadnienia oraz konwencje odbiegające od standardów narzędzia. Innymi słowy, odwraca to zwykłą zawartość tych plików.

Rzeczy do usunięcia:

• Strukturę folderów, ponieważ Claude sam może wylistować katalogi.
• Listę zależności, którą już zawiera plik package.json.
• Opis architektury w formie narracji, który jest mniej dokładny niż kod.

Rzeczy do zachowania:

• Kod, który wygląda jak błąd, ale jest celowy.
• Uzasadnienie odrzucenia oczywistego podejścia.

Każda konwencja, która jest sprzeczna z dokumentacją frameworka.

Polecenia, których nikt sam nie odkryłby.

Dobry test: jeśli kompetentny inżynier z otwartym repozytorium mógłby się tego nauczyć w ciągu dziesięciu minut, należy to pominąć. Jeśli dowie się o tym tylko poprzez uszkodzenie czegoś, należy to zapisać.

Zostawiaj notatki dla ludzi bez żadnych kosztów

Komentarze na poziomie bloku w HTML są usuwane przed tym, jak treść pliku dotrze do kontekstu Claude’a. Dzięki temu możesz adnotować plik dla osób, które go utrzymują, nie wydając żadnych środków modelu – na przykład aby zaznaczyć, dlaczego jakaś sekcja została przeniesiona:

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Twoi koledzy z zespołu widzą historię zmian; model nigdy za to nie płaci.

@imports organizują plik, ale nie przechowują kontekstu

Gdy plik CLAUDE.md staje się zbyt długi, naturalnym rozwiązaniem jest podzielenie go na kilka dokumentów i ich imporcie:

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

To wygląda jak łatwe ładowanie, ale tak nie jest. Pliki importowane są rozpakowywane i ładowane do kontekstu przy uruchomieniu, wraz z plikiem CLAUDE.md, który na nie odwołuje się. Podział 340 wierszy na cztery oddzielne pliki nadal powoduje załadowanie tych samych 340 wierszy.

Importy rzeczywiście mają uzasadnione zastosowania. Pomagają w organizacji i umożliwiają udostępnianie jednego, kanonicznego zestawu instrukcji pomiędzy narzędziami. Jeśli repozytorium już zawiera plik AGENTS.md, jedna linia @AGENTS.md w pliku CLAUDE.md pozwala uniknąć konieczności utrzymywania dwóch różniących się wersji. Po prostu nie oczekuj, że zmniejszą one zużycie kontekstu. W przypadku instrukcji, które powinny być ładowane tylko czasami, potrzebne są reguły skierowane do określonych ścieżek.

Zastosowanie warunkowych reguł za pomocą .claude/rules i ścieżek

Pliki w katalogu .claude/rules/ mogą deklarować pole paths w swoim frontmatterze. To właśnie ta funkcja umożliwia realizację oczekiwań dotyczących importów: reguła o zasięgu globowym pozostaje poza kontekstem, dopóki Claude nie przeczyta lub nie edytuje odpowiadającego pliku. Frontmatter pliku z regułami API może wyglądać w ten sposób:

---
paths:
  - "src/api/**/*.ts"
---

Poniżej frontmatteru znajduje się treść reguły, która zawiera zasady obowiązujące wyłącznie dla tej części struktury, takie jak walidacja danych wejściowych, wspólny format komunikatów o błędach oraz miejsca, gdzie dozwolone jest użycie SQL:

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

Skutkiem tego jest to, że praca frontendu nie musi już opłacać kosztów tokenów związanych z konwencjami API, a praca z API nie musi opłacać kosztów testowania.

W praktyce jest to rozwiązanie problemu zbyt rozbudowanego CLAUDE.md. Podziel treść według tematów, przypisz każdy temat do odpowiednich katalogów i zachowaj plik korzeniowy na wskazówki uniwersalne dla całego projektu. Plik z regułami bez pola paths jest ładowany przy każdej sesji, więc traktuj to jako świadomy wybór, a nie standardową praktykę.

Globs obsługują rozszerzanie za pomocą nawiasów, więc jedna reguła może obejmować kilka rozszerzeń oraz oddzielny wzorzec testowy:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Kroki obowiązkowe powinny znajdować się w hookach

Zdania takie jak „lint przed każdym commitem”, „nie wysyłaj bezpośrednio do main” czy „sformatuj każdy plik po edycji” są częste w CLAUDE.md. W większości przypadków są one przestrzegane, wyjątki zwracają uwagę, a zespoły dochodzą do wniosku, że model nie może być uznawany za wiarygodny.

Jednak to jest udokumentowane zachowanie: CLAUDE.md wpływa na to, co robi Claude, ale nie gwarantuje tego. W przypadku kroku, który musi nastąpić w określonym momencie w cyklu życia sesji, hook uruchamia w tym momencie polecenie w shellu, niezależnie od oceny modelu. Hook PreToolUse może nawet całkowicie zablokować wywołanie narzędzia, czego nie może osiągnąć żaden format Markdown z pogrubieniami czy wielkimi literami.

Praktyczny sposób na kierowanie poszczególnymi rodzajami instrukcji:

• Konwencje, których Claude powinien się generalnie trzymać, znajdują się w pliku CLAUDE.md.
• Zasady dotyczące określonej części kodu umieszcza się w katalogu .claude/rules/ razem z plikami paths.
• Wymagania bez żadnej tolerancji na wyjątki stają się hookami.
• Procedury wieloetapowe, które można powtarzać, stają się umiejętnościami.

Przeniesienie kilku reguł „zawsze” do mechanizmu hooks przynosi podwójną korzyść: wymagania są teraz faktycznie egzekwowane, a plik pozbywa się linijek, które i tak nigdy nie mogły zadziałać, co pozwala skupić się bardziej na instrukcjach, które rzeczywiście mogą być wykorzystane.

Sprawdź, co faktycznie zostało załadowane

Zrób wywołanie /context i sprawdź sekcję plików pamięci, która dokładnie pokazuje, co zostało załadowane przez bieżącą sesję. /memory uzupełnia to, wyświetlając pliki na poziomie użytkownika i projektu oraz umożliwiając ich otwarcie. Razem przekształcają one pytanie „Czy Claude to ignoruje?” z domysłów w coś, co można sprawdzić. Zaskakująco łatwo jest poświęcić czas na dopracowanie sformułowań w pliku, który w ogóle nie jest ładowany.

Sprzeczności pomiędzy połączonymi plikami

Nic nie jest przeplatające; wszystko jest łączone. Począwszy od katalogu roboczego, Claude Code przesuwa się w górę do korzenia systemu plików, zbierając po drodze każdy plik CLAUDE.md, a następnie sortuje je od korzenia w dół. Na każdym poziomie, gdzie znajduje się również plik CLAUDE.local.md, ten plik znajduje się po swoim „bracie” pliku CLAUDE.md. W monorepo dwa pliki mogą łatwo dostarczać sprzecznych wskazówek. W takim przypadku Claude może po prostu wybrać jeden z nich, a ty nie otrzymasz żadnego powiadomienia o konflikcie.

Pliki przodków, których nie prosiłeś

Jeśli plik CLAUDE.md z katalogu nadrzędnego przenika do twoich sesji, ustawienie claudeMdExcludes w twoich lokalnych ustawieniach pomaga pominąć takie pliki za pomocą wzorów globowych.

Co przetrwa kompresję

Plik CLAUDE.md znajdujący się w katalogu głównym projektu jest ponownie odczytywany z dysku i wprowadzany po wywołaniu /compact, dzięki czemu jego instrukcje pozostają w mocy. Wszystko, co powiedziałeś tylko w trakcie rozmowy, zostaje utracone. Jeśli ciągle powtarzasz tę samą korektę po każdej kompresji, jest to wyraźny sygnał, że powinna ona znaleźć się w pliku.

Podstawowy plan

Gdybyś tworzył konfigurację od zera, rozsądny cel wyglądałby tak:

• Katalog główny zawierający plik CLAUDE.md o długości około 120 wierszy, z zawartością dotyczącą tylko tego, co jest prawdziwe we wszystkich przypadkach.
• Wskazówki warunkowe umieszczone w katalogu .claude/rules/ z użyciem wzorców ścieżek.
• Każdy wymóg o charakterze obowiązkowym „zawsze” realizowany poprzez specjalne elementy konfiguracyjne.
• Niczego, czego ktoś mógłby się nauczyć, przeczytawszy repozytorium przez dziesięć minut.
• Szybka weryfikacja za pomocą /context po każdej zmianie.

Pełne informacje, w tym opisy takich funkcji jak automatyczna pamięć, które wymagają osobnego omówienia, znajdują się w dokumentacji dotyczącej pamięci w Claude Code. Zachowanie i ograniczenia mogą ulegać zmianom, więc sprawdź je, gdy coś nie odpowiada temu, co widzisz.

Główne wnioski

• Pisz pliki CLAUDE.md dla kolegi, który je czyta, a nie dla maszyny, która je wykonuje: muszą być krótkie, konkretne i wolne od sprzeczności.
• Krótsze pliki są traktowane bardziej wiarygodnie; usuń wszystko, co baza kodu już przekazuje do Claude.
• Importy przeprowadzają reorganizację treści, ale ładują ją w całości; to reguły zdefiniowane na poziomie ścieżki faktycznie opóźniają ładowanie.
• Wszystko, co musi dziać się za każdym razem, wymaga użycia hooka, ponieważ kontekst może wpływać jedynie na zachowanie.
• Traktuj /context jako swoje źródło prawdy przed dostosowywaniem sformułowań.

Pozycje pokrewne

• Praktyczny przewodnik po stworzeniu skutecznego pliku CLAUDE.md — Poznaj 21 konkretnych, sprawdzalnych zasad służących do uproszczenia zaawansowanego pliku CLAUDE.md, aby Claude Code pozostał niezawodny, przewidywalny i godny zaufania podczas długich sesji.
• Porównanie agentów Frontier AI: Astra, Flash, Fable i Mythos — Analiza wydajności najnowszych wersji modeli GPT, Gemini i Claude przy rzeczywistych zadaniach agencyjnych, takich jak programowanie, przeglądanie internetu i korzystanie z narzędzi, a nie tylko w testach benchmarkowych.

Reverse Prompting: Przekształcanie dobrej sesji LLM w używalny prompt — Dowiedz się, jak wydobyć prompt jednorazowy z udanej rozmowy wieloetapowej z LLM oraz jak technika odwrócenia promptu pozwala przywrócić pierwotne polecenia, gdy masz dostęp tylko do wyników.

Od reguł prozatorskich do mechanicznych bram: Zabezpieczanie zespołu agentów Claude Code — Jak jeden plugin wieloagentowy dla Claude Code zastąpił ignorowane instrukcje dotyczące persony skryptami, hookami oraz haszowanymi dowodami, krok po kroku w kolejnych wersjach, oraz co można przejąć z tego rozwiązania.

Nauka używania Claude Code do kierowania ruchem w monorepo NestJS: reguły, zasady i umiejętności — Jak skonfigurować CLAUDE.md, reguły, umiejętności i uprawnienia, aby Claude Code umieszczał kod we właściwej usłudze NestJS i przestrzegał konwencji zespołu.

Wdrażanie reguł agenta w kodzie: PreToolUse, PostToolUse i Stop Hooks — Dowiedz się, dlaczego autoryzacja agentów LLM powinna znajdować się w hookach deterministycznych do wywoływania narzędzi, jak bezpiecznie odrzucać wywołania oraz jak otoczyć dispatcher bez rekurencji.