Claude Code w monorepo: jak ograniczać kontekst i zachować dokładność

Dlaczego duże monorepo obniżają dokładność Claude\n\nClaude Code w monorepo może zachowywać się nieprzewidywalnie z prostego powodu: repo jest większe niż to, co model może utrzymać w „pamięci roboczej” naraz.\n\n„Kontekst” to zestaw plików, fragmentów, notatek i instrukcji, które pokazano Claude'owi dla tego zadania, plus to, co z nich może wnioskować. Gdy brakuje kluczowych szczegółów, Claude wypełnia luki przypuszczeniami. W dużym repo zdarza się to częściej.\n\nPojawiają się trzy powtarzające się tryby błędów:\n\nPo pierwsze — brakujące pliki. Zmiana, która wydaje się bezpieczna w jednym folderze, może w rzeczywistości zależeć od współdzielonego typu, zasady konfiguracji lub kroku build zdefiniowanego gdzie indziej. Jeśli ta zależność nie jest w kontekście, Claude może pewnie edytować niewłaściwe miejsce albo zatrzymać się zbyt wcześnie, bo nie widzi prawdziwego źródła prawdy.\n\nPo drugie — fałszywe podobieństwo. Monorepo często zawierają wiele pakietów o podobnym wyglądzie: dwa moduły auth, trzy klienty API albo kilka aplikacji React z podobnymi strukturami folderów. Claude może mieszać wzorce między nimi, zaktualizować helper w złym pakiecie lub zaimportować z „prawie właściwej” nazwy modułu.\n\nPo trzecie — dryf czasowy. Duże bazy kodu mają zwykle stare i nowe sposoby robienia tego samego zadania. Jeśli Claude widzi tylko starsze pliki, może skopiować przestarzałe wzorce (przestarzałe opcje konfiguracji, legacy API), choć zespół przeszedł dalej.\n\nPrzykład z życia: poprosisz o małą zmianę w UI płatności, a Claude edytuje współdzielony komponent payments używany przez inne aplikacje, bo nie widział opakowania specyficznego dla danej aplikacji, które powinno zostać zmienione.\n\nCelem nie jest pokazanie Claude'owi całego monorepo. Celem jest dostarczenie mniejszych, przemyślanych wejść, które nadal odpowiadają na pytanie: pakiet, który zmieniasz, jego bezpośrednie zależności i jednen lub dwa „źródła prawdy” dla typów i konfiguracji. Wskaż też obszary „nie dotykać” (inne aplikacje, infra, pliki generowane) i potwierdź, który pakiet jest właścicielem zachowania.\n\n## Zacznij od zdefiniowania zadania, nie repo\n\nDokładność zależy mniej od tego, ile kodu wkleisz, a bardziej od tego, jak jasno opiszesz zadanie.\n\nZacznij od rezultatu, którego oczekujesz: konkretnej poprawki, refaktoru lub odpowiedzi. „Pytanie o kod” może być ogólne. Prośba o „wprowadzenie zmiany” wymaga granic, wejść i kryteriów sukcesu.\n\nPrzed udostępnieniem czegokolwiek, napisz jedno zdanie kończące tę frazę: „Po skończeniu powinienem móc…”. Na przykład: „uruchomić testy jednostkowe pakietu X bez błędów” albo „zobaczyć nowe pole w odpowiedzi API dla endpointu Y”. To zdanie staje się gwiazdą północną, gdy repo jest ogromne.\n\nDla zmian udostępnij najmniejszy zestaw artefaktów, który może udowodnić poprawność zmiany: punkty wejścia, odpowiednie typy/interfejsy lub schemat, jeden nieudany test albo krok repro z oczekiwanym rezultatem oraz wszelką konfigurację wpływającą na tę ścieżkę (routing, feature flagi, build lub lint). Jeśli to pomaga, dodaj krótki mapę folderów pakietu, aby Claude zrozumiał, do czego służy każdy katalog.\n\nBądź wyraźny co do tego, czego nie trzeba przeglądać. Napisz: „Ignoruj pliki generowane, foldery vendor, pliki build, snapshoty i lockfile, chyba że poproszę.” To zapobiega marnowaniu czasu i edycjom miejsc, których nie przejrzysz.\n\nUstal także oczekiwania co do niepewności. Poproś Claude'a, by oznaczał założenia i nieznane zamiast zgadywać. Na przykład: „Jeśli nie widzisz, gdzie ta funkcja jest wywoływana, powiedz to i zaproponuj 2 sposoby jej zlokalizowania.”\n\n## Wyznacz jasne granice, których Claude nie powinien przekraczać\n\nW dużym monorepo dokładność spada, gdy model zaczyna „pomocniczo” wciągać pobliski kod, który nie jest częścią zadania. Naprawa jest prosta: zdefiniuj, co jest w zakresie, a co poza nim, zanim poprosisz o zmiany.\n\nZacznij od granicy odpowiadającej organizacji repo: pakiet, serwis, aplikacja lub biblioteka współdzielona. Jeśli zmiana to „aktualizacja UI checkout”, granicą jest prawdopodobnie jeden pakiet aplikacji, a nie każde miejsce, gdzie występuje słowo „checkout”.\n\nSygnalizatory pomagające Claude'owi pozostać w miejscu to konwencje folderów (apps/, services/, packages/, libs/), manifesty pakietów (eksporty i zależności), publiczne punkty wejścia (pliki index, eksportowane komponenty, handlery) i testy (często ujawniają oczekiwaną powierzchnię). README wewnątrz folderu może być najszybszym markerem granicy.\n\nGranice działają najlepiej, gdy nazwiesz mosty między nimi. Wymień konkretne interfejsy, których Claude może dotykać, a traktuj wszystko inne jako poza zakresem. Typowe mosty to kontrakty HTTP API, tematy i payloady zdarzeń, współdzielone typy lub mały zestaw eksportowanych funkcji.\n\nRównież wskaż strefy „nie dotykać” zawsze, gdy zmiana nie ma ich obejmować. Typowe to konfiguracje infrastruktury i wdrożeń, logika bezpieczeństwa i autoryzacji, rozliczenia i płatności, migracje danych i schematy produkcyjne oraz biblioteki współdzielone używane przez wiele zespołów.\n\nSzczegół, który pomaga w promptcie:\n\n„Wprowadzaj zmiany tylko w packages/cart/ i jego testach. Możesz czytać shared types w packages/types/, ale ich nie modyfikuj. Nie edytuj infra, auth ani billing.”\n\n## Jak pisać użyteczne lokalne podsumowania\n\nDokładność rośnie, gdy dostarczysz małą, stabilną mapę obszaru, który chcesz zmienić. „Lokalne podsumowanie” to ta mapa: na tyle krótkie, by przeczytać szybko, na tyle konkretne, by zapobiec zgadywaniu.\n\nUtrzymuj każde podsumowanie w 10–20 liniach. Pisz tak, jakbyś przekazywał kod nowemu koledze, który musi dotknąć tylko tej granicy, nie całego repo. Używaj prostego języka i prawdziwych nazw z kodu: folderów, pakietów, eksportowanych funkcji.\n\nUżyteczne lokalne podsumowanie odpowiada na pięć pytań:\n\n- Do czego służy ten pakiet/serwis i do czego nie służy (zakres)\n- Gdzie zaczyna się praca (punkty wejścia jak pliki, trasy, komendy lub komponenty)\n- Co można bezpiecznie wywołać z zewnątrz (publiczne API, eksporty, zdarzenia, endpointy)\n- Od czego zależy (bazy danych, kolejki, cache, konfiguracja, usługi zewnętrzne)\n- Jakie zasady tu obowiązują (wzorce nazewnictwa, styl błędów, logowanie, sposób pisania testów)\n\nDodaj jedną linię „gotchas”. To miejsce na zapobieganie kosztownym pomyłkom: ukryte cache, feature flagi, kroki migracji i wszystko, co może psuć się bez śladu.\n\nOto zwięzły szablon, który możesz skopiować:\n\n```text

Local summary: <package/service name> Purpose: <1 sentence> Scope: <what to touch> | Not: <what not to change> Entry points: <files/routes/commands> Public surface: <exports/endpoints/events> Data sources: <tables/collections/queues/caches> Conventions: errors=<how>, logging=<how>, tests=<where/how> Gotchas: <flags/caching/migrations/edge cases>

\nNastępnie trzymaj pętlę krótką:\n\n1. Mapa: „Ta zmiana jest ograniczona do CartPage i ikon ui-kit. Bez edycji checkout/auth.”\n2. Założenia: wymagaj listy założeń i poczekaj na potwierdzenie.\n3. Prośby o pliki: zatwierdź tylko kilka plików, których naprawdę potrzebuje (, , ikony ui-kit, ui-kit index).\n4. Plan: potwierdź, że mieści się w granicach.\n5. Edycje: zrób najmniejszy diff, potem poproś o zaktualizowane testy.\n\nPo zmianie udokumentuj ją, by przyszły kontekst pozostał mały:\n\n- Zaktualizuj oba lokalne podsumowania o nowy eksport i dokładne pliki, które dotknięto.\n- Dodaj krótki komentarz w nagłówku strony koszyka: co robi przycisk i gdzie obsługiwany jest stan.\n- Zanotuj polecenia testów, które przeszły (i wszelkie snapshoty zaktualizowane).\n\n## Następne kroki: jak uczynić to powtarzalnym dla zespołu\n\nJeśli działa dobrze dla jednej osoby, ale nie dla reszty zespołu, brakujący element to zwykle powtarzalność. Uczyń „dobrą higienę kontekstową” domyślną, nie osobistym nawykiem.\n\n### Zamień najlepsze prompt’y w szablon zespołowy\n\nZapisz jeden szkielet promptu, który każdy może skopiować i wypełnić. Trzymaj go krótko, ale surowo. Uwzględnij cel (co oznacza „skończone”), dozwolony zakres, twarde granice (i dlaczego), lokalne podsumowanie oraz kontrakt wyjściowy (najpierw plan, potem diff i testy).\n\n### Utrzymuj podsumowania aktualne lekkim rytuałem\n\nPomiń wielkie comiesięczne przeglądy, które nikt nie robi. Dołącz aktualizacje podsumowania do normalnej pracy: gdy zmiana zmienia zachowanie, zależności lub API, zaktualizuj lokalne podsumowanie w tym samym PR.\n\nProsta zasada: jeśli kolega zapytałby „gdzie to leży?” albo „co na tym polega?”, podsumowanie jest przestarzałe.\n\nJeśli wolisz workflow oparty na chacie, Koder.ai może pomóc uczynić iteracje bezpieczniejszymi. Planning mode pomaga uzgodnić zakres i granice zanim zaczną się edycje, a snapshoty z możliwością rollbacku pozwalają próbować zmian bez utknięcia, gdy przypuszczenie okaże się błędne.