Claude Code a monorepo - jak nawigować po dużym repo

Claude Code

Claude Code a monorepo - jak nawigować po dużym repo

W skrócie

Monorepozytorium to jedno repozytorium mieszczące wiele projektów albo pakietów naraz - frontend, backend, biblioteki współdzielone, infrastrukturę. Claude Code, narzędzie CLI od Anthropic do programowania z AI, radzi sobie z takim układem, ale wymaga trochę pomocy z Twojej strony. W małym projekcie narzędzie ogarnia całość bez wysiłku; w monorepozytorium z tysiącami plików samo błądzenie po drzewie robi się wolne i drogie. Kilka prostych nawyków sprawia, że narzędzie od razu trafia tam, gdzie trzeba, zamiast przeczesywać wszystko.

Jak to wygląda w praktyce

Prosisz o zmianę w jednym module, a Claude Code przeszukuje pół repozytorium, zaglądając do pakietów, które z zadaniem nie mają związku. Odpowiedzi przychodzą wolniej, bo narzędzie mieli mnóstwo nieistotnych plików, a kontekst zapełnia się treścią spoza Twojego modułu. Bywa, że narzędzie odwołuje się do konwencji z innego pakietu (bo trafiło na jego pliki), przez co proponuje rozwiązania niepasujące do tej części kodu, nad którą pracujesz. Ogólne wrażenie jest takie, że w dużym repozytorium narzędzie traci ostrość, którą miało w małym projekcie.

Dlaczego Claude Code tak działa

Claude Code nie dostaje gotowej mapy Twojego monorepozytorium - orientuje się w nim na bieżąco, czytając strukturę katalogów i wyszukując pliki narzędziami do przeszukiwania. W małym projekcie to nic nie kosztuje. W ogromnym drzewie każde szerokie wyszukiwanie oznacza przejrzenie wielu plików i wciągnięcie ich fragmentów do skończonego okna kontekstu. Jeśli nie zawęzisz obszaru, narzędzie działa domyślnie szeroko: skanuje więcej, niż potrzeba, i miesza konwencje różnych pakietów. Pomaga tu mechanizm zagnieżdżonych plików pamięci: gdy pracujesz z poziomu konkretnego podkatalogu, Claude Code wczytuje pliki CLAUDE.md wzdłuż ścieżki od korzenia do tego katalogu - więc instrukcje danego pakietu wchodzą do kontekstu tylko wtedy, gdy faktycznie w nim jesteś. To Ty decydujesz, jak wąsko albo szeroko narzędzie patrzy, przez to, skąd je uruchamiasz i jak precyzyjnie wskazujesz cel.

Jak to rozwiązać krok po kroku

1. Uruchamiaj Claude Code z katalogu modułu, nad którym pracujesz, a nie z korzenia całego monorepozytorium. Dzięki temu narzędzie skupia się na tym poddrzewie i wczytuje właściwe instrukcje.
2. Dodaj zagnieżdżone pliki CLAUDE.md w poszczególnych pakietach, z konwencjami i komendami danego modułu. Wczytają się dopiero przy pracy w tym pakiecie, więc nie obciążają kontekstu przy innych zadaniach.
3. W korzeniowym CLAUDE.md zostaw tylko rzeczy wspólne dla całego repozytorium i krótki opis, gdzie co leży - taka mapa pomaga narzędziu od razu skierować się we właściwe miejsce.
4. Wskazuj konkretne ścieżki i pliki, zamiast liczyć wyłącznie na przeszukiwanie. Podanie katalogu docelowego oszczędza narzędziu szerokiego skanu i przyspiesza pracę.
5. Trzymaj zadanie w granicach jednego modułu, kiedy to możliwe. Jeśli zmiana dotyka kilku pakietów, prowadź ją świadomie krok po kroku, a nie jako jedno rozmyte polecenie na całe repozytorium.
6. Zadbaj, by .gitignore wykluczał to, co i tak nieistotne (katalogi zależności, artefakty budowania) - dzięki temu narzędzie nie traci czasu na przeszukiwanie śmieci.
7. Przy przejściu do innego modułu rozważ wyczyszczenie kontekstu (/clear), żeby nie ciągnąć za sobą plików i konwencji z poprzedniego pakietu.

Jak sprawdzić, że zadziałało

Uruchom narzędzie z katalogu modułu i sprawdź poleceniem /memory, czy wczytany jest właściwy plik CLAUDE.md tego pakietu, a nie instrukcje z niepowiązanych modułów. Praktyczny dowód to zachowanie przy zadaniu: jeśli narzędzie od razu sięga do plików Twojego modułu i nie błądzi po całym drzewie, zawężenie zadziałało. Zwróć uwagę na czas i trafność - po podaniu konkretnych ścieżek odpowiedzi powinny przychodzić szybciej i dotyczyć właściwego pakietu, bez podpierania się konwencjami z innej części repozytorium. Gdy narzędzie nadal wciąga niepotrzebne moduły, wróć do dwóch dźwigni: uruchamiania z właściwego katalogu i wskazywania ścieżek wprost.

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