Zagnieżdżone CLAUDE.md per katalog - jak działają

Claude Code

Zagnieżdżone CLAUDE.md per katalog - jak działają

W skrócie

Plik CLAUDE.md to notatnik, z którego Claude Code - narzędzie CLI od Anthropic do programowania z AI - wczytuje wiedzę o Twoim projekcie: konwencje, komendy, rzeczy, o których ma pamiętać. W małym repozytorium wystarcza jeden taki plik w korzeniu. W większym projekcie, zwłaszcza z wieloma modułami, jeden plik puchnie i miesza sprawy, które nie mają ze sobą nic wspólnego. Dobra wiadomość: Claude Code obsługuje zagnieżdżone pliki CLAUDE.md - osobne dla poszczególnych katalogów - i wczytuje je w przewidywalny sposób. Wystarczy zrozumieć, kiedy który plik wchodzi do kontekstu.

Jak to wygląda w praktyce

Twój korzeniowy CLAUDE.md rozrasta się do ściany tekstu: reguły frontendu, backendu, skryptów i infrastruktury w jednym miejscu. Pracując nad jednym modułem, ładujesz do kontekstu instrukcje wszystkich pozostałych, których wcale nie potrzebujesz. Bywa i tak, że wpisujesz szczegółową regułę dotyczącą jednego podkatalogu, a ona myli narzędzie przy pracy nad zupełnie innym fragmentem kodu. Albo odwrotnie: umieszczasz notatkę głęboko w podkatalogu i dziwisz się, że narzędzie jej nie zna, kiedy pracujesz z korzenia repozytorium. To wszystko efekt niezrozumienia, po które pliki i kiedy Claude Code faktycznie sięga.

Dlaczego Claude Code tak działa

Claude Code nie przeszukuje całego drzewa katalogów w poszukiwaniu każdego CLAUDE.md. Zamiast tego, startując pracę w danym katalogu, idzie ścieżką od korzenia repozytorium w dół aż do tego katalogu i po drodze wczytuje każdy napotkany CLAUDE.md. To tak zwane przechodzenie zagnieżdżone: plik z korzenia wchodzi zawsze, a pliki z podkatalogów - tylko gdy pracujesz w tym podkatalogu albo poniżej. Do tego dochodzą inne poziomy pamięci: Twój prywatny plik użytkownika w ~/.claude/CLAUDE.md (wspólny dla wszystkich projektów), pliki projektu w repozytorium oraz pliki zarządzane przez organizację. Dodatkowo w każdym CLAUDE.md możesz odwołać się do innego pliku dyrektywą importu (zapisem z @) - jego treść zostaje wtedy doklejona w miejscu odwołania. Dzięki temu instrukcje ładują się warstwami: od ogólnych na górze do coraz bardziej szczegółowych, im głębiej w drzewie pracujesz.

Jak to rozwiązać krok po kroku

1. Zostaw w korzeniowym CLAUDE.md tylko to, co dotyczy całego projektu: ogólne konwencje, sposób uruchamiania, zasady wspólne dla wszystkich modułów. Wytnij stamtąd szczegóły przypisane do konkretnych katalogów.
2. W każdym istotnym podkatalogu (na przykład frontend/, backend/, infra/) utwórz własny CLAUDE.md z instrukcjami dotyczącymi wyłącznie tego modułu. Te pliki wczytają się dopiero, gdy zaczniesz pracę w tym poddrzewie.
3. Trzymaj wiedzę jak najbliżej kodu, którego dotyczy. Reguła o testach backendu powinna leżeć w katalogu backendu, a nie w korzeniu - inaczej obciąża kontekst przy pracy nad czymkolwiek innym.
4. Gdy kilka plików ma współdzielić ten sam fragment (na przykład wspólny standard commitów), wydziel go do osobnego pliku i wciągnij importem przez zapis z @, zamiast kopiować treść w wielu miejscach.
5. Rzeczy prywatne, których nie chcesz narzucać zespołowi ani commitować, wpisz do swojego pliku użytkownika w ~/.claude/CLAUDE.md - obowiązuje we wszystkich projektach i nie trafia do repozytorium.
6. Po każdej zmianie zacznij pracę w konkretnym podkatalogu i sprawdź, czy właściwe instrukcje faktycznie się wczytały (patrz sekcja poniżej). Dopiero wtedy uznaj podział za działający.

Jak sprawdzić, że zadziałało

Uruchom Claude Code z poziomu wybranego podkatalogu i użyj polecenia /memory - pokaże listę plików pamięci, które narzędzie aktualnie wczytało. Powinieneś zobaczyć zarówno korzeniowy CLAUDE.md, jak i ten z podkatalogu, w którym jesteś, a nie pliki z sąsiednich, niepowiązanych modułów. Dla pewności zadaj pytanie, na które odpowiedź jest tylko w instrukcji modułu (na przykład o lokalną komendę tego katalogu) - trafna odpowiedź potwierdza, że plik wszedł do kontekstu. Następnie przejdź do innego podkatalogu i powtórz: instrukcja poprzedniego modułu nie powinna już być wczytana. Taki test wprost pokazuje, że zagnieżdżone pliki ładują się wzdłuż ścieżki, a nie wszystkie naraz.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5