Ośmiowarstwowa konfiguracja Claude Code: CLAUDE.md, pamięć, hooki i zasady ograniczające.

Konfiguracja decyduje o stopniu zaufania do odpowiedzi

Każdy może wpisać polecenie do Claude Code, ale to ustawienia otaczające ten proces decydują o tym, czy wynik zasługuje na zaufanie. Poniżej znajduje się szczegółowy opis warstw realistycznej konfiguracji przydatnej do poważnej pracy inżynieryjnej wraz z uzasadnieniem każdej z tych warstw. Nie jest to lista funkcji ani wersja marketingowa. Osiem warstw razem tworzy coś bliższego dobrze skonfigurowanemu narzędziu inżynieryjnemu niż zwykłe okno czatu, które przypadkowo pisze kod.

Warstwa 1: CLAUDE.md w dwóch zakresach

Claude Code czyta pliki CLAUDE.md w kilku zakresach, a rozróżnienie między nimi ma większe znaczenie, niż większość ludzi przypuszcza. Plik osobisty znajdujący się w ~/.claude/CLAUDE.md ma zastosowanie we wszystkich projektach, niezależnie od otwartego repozytorium. Każdy projekt posiada również swój własny plik CLAUDE.md, który jest zapisywany w systemie kontroli wersji, dzięki czemu cały zespół otrzymuje te same instrukcje poprzez system kontroli wersji.

Prosta zasada sprawia, że te dwie kategorie pozostają oddzielone. Wszystko, co dotyczy sposobu pracy osoby, niezależnie od bazy kodu, trafia do pliku globalnego: zasady używania narzędzi, takie jak preferowanie wyszukiwania w systemach analityki kodu zamiast prostego przeszukania za pomocą grep, preferencje i konwencje komunikacyjne, które mają obowiązywać wszędzie. Wszystko, co dotyczy konkretnej bazy kodu, trafia do pliku specyficznego dla danego repozytorium: polecenia budowania, decyzje architektoniczne, konwencje nazewnicze oraz rodzaje błędów, które już pojawiły się w tym projekcie. W każdym innym projekcie takie elementy stanowią zbędny hałas, który bez powodu zabiera kontekst.

Powód do zapisania czegoś jest konkretny. Wyobraź sobie wzorzec błędu, który pojawia się dwa razy w tej samej części projektu. Rozwiązanie wydaje się poprawne i przechodzi przy pobieżnym spojrzeniu, jednak ponownie powoduje ten sam problem, ponieważ podstawowe ograniczenie nigdzie nie zostało zapisane w miejscu widocznym dla osoby zajmującej się projektem. Za pierwszym razem ograniczenie zostaje wyjaśnione w rozmowie i wszyscy przechodzą dalej. Za drugim razem ten sam błąd wymaga tego samego wyjaśnienia. To jest sygnał. Zasada powinna znaleźć się w CLAUDE.md nie dlatego, że może się kiedyś okazać przydatna, ale dlatego, że ten sam problem powodował dwukrotnie te same rozmowy. Gdy jest to konkretna, sprawdzalna zasada, a nie niejasne ostrzeżenie, problem przestaje się powtarzać.

Jeden praktyczny szczegół: treść CLAUDE.md jest dostarczana jako wiadomość od użytkownika i nie jest wbudowana w prompt systemu, więc precyzja jest ważniejsza niż długość. Plik zawierający mniej niż 200 linii konkretnych zasad radzi sobie lepiej niż długi plik z niejasnymi zasadami.

Warstwa 2: auto memory

CLAUDE.md to to, co programista mówi agentowi, natomiast pamięć to to, co agent sam ustala. Pełnią różne funkcje i nie powinny być utożsamiane. Claude Code posiada drugi system – auto memory – który jest budowany dla każdego projektu i przechowywany poza repozytorium; to agent do niego pisze. Zawiera on cztery rodzaje notatek: informacje o roli i preferencjach programisty, korekty oraz opinie już udzielone, aktualny stan projektu, którego nie można wywnioskować z kodu, oraz zewnętrzne odniesienia do informacji znajdujących się poza bazą kodu. Lekki plik MEMORY.md indeksuje wszystko.

Różnica polega na tym, że CLAUDE.md zawiera celowo napisane instrukcje, natomiast pamięć przechowuje kontekst zgromadzony podczas kolejnych sesji pracy, który nigdy nie jest formalnie udokumentowany. Jedno to podręcznik zasad, a drugie przypomina wiedzę instytucjonalną, którą posiada pracownik od dawna zatrudniony w zespole, bez żadnych dokumentów wprowadzających. Trzy przykłady pokazują, co się zmienia:

• Korekta dokonana raz, np. „Nie dotykaj tego pliku bez uprzedniego zapytania”, przechodzi do następnej sesji i nie musi być powtarzana za każdym razem, gdy rozpoczyna się rozmowa.
• Stan projektu niewidoczny w kodzie zostaje zapamiętany: trwająca migracja, celowo odłożona decyzja lub architektura, która wygląda intencjonalnie niepoprawnie z powodu ograniczenia, którego nie pokazuje żaden diff.
• Wskazówki dotyczące miejsca, gdzie znajdują się odpowiedzi, pozostają aktywne – np. który panel sterowania, który zewnętrzny dokument lub który system zawiera informacje, których kod nie może podać.

Żadna z tych rzeczy nie powinna znajdować się w CLAUDE.md, ponieważ żadna z nich nie stanowi egzekwowanego reguły. Są to konteksty, które znikają w momencie zamknięcia sesji.

Warstwa 3: hooki jako celowe utrudnienia

Celowo wprowadzone utrudnienia zupełnie różnią się od tych, z którymi po prostu musimy się mierzyć. Hooki działają w sposób deterministyczny, jako prawdziwe polecenia wiersza poleceń w określonych momentach cyklu życia, co stanowi mocniejszą gwarancję niż nadzieja, że model zwykle pamięta. Hook PreToolUse uruchamia się przed każdym wywołaniem narzędzia i może je całkowicie zatrzymać. Hook Stop uruchamia się, gdy Claude kończy swoją odpowiedź, i może zmusić go do kontynuacji, jeśli pewne warunki jeszcze nie zostały spełnione.

Najbardziej przydatnym wzorcem jest hOOK PreToolUse ograniczony do edycji plików. Zanim edycja zostanie przeprowadzona, wymaga pisemnego opisu faktów: które moduły importują plik, co może ulec uszkodzeniu oraz jaki był rzeczywisty wniosek. Działa jako celowy hamulec dla nieostrożnych zmian, a ta „tarcie” się opłaca, ponieważ interweniuje dokładnie wtedy, gdy potrzebna jest ostrożność. W odróżnieniu od ludzkiej uwagi, hOOK nie ignoruje ani nie przyspiesza przetwarzania czterdziestej edycji w długiej sesji.

Drugi haczyk zarządza dyscypliną wyjścia, utrzymując odpowiedzi zwięzłe, usuwając zbędne informacje i unikając wyrażeń niejednoznacznych, które pojawiają się podczas dłuższych rozmów. Chodzi tu mniej o bezpieczeństwo, a bardziej o unikanie marnowania czasu na nieistotne treści. Trzeci haczyk monitoruje stan kontekstu, zachęcając do skondensowania informacji w naturalnym momencie, a nie arbitralnie. Haczyk PreCompact lub SessionStart powiązany z zdarzeniami skondensowania może wyświetlić streszczenie, gdy rozmowa faktycznie osiągnie punkt zakończenia, dzięki czemu nie zostanie przerwana w trakcie myśli.

Czy ta dodatkowa regulacja się opłaca? W przypadku zabezpieczeń edycji plików – bez wątpienia, ponieważ zapobiega prawdziwym błędom, zanim te przeradzą się w poważne problemy. Haczyki związane z zwięzłością i kontekstem służą bardziej do dostosowania komfortu czytania niż do ochrony, ale przynoszą korzyści po prawidłowym ustawieniu.

Warstwa 4: graf wiedzy o kodzie jest lepszy od grep

Grep pokazuje, gdzie występuje dana sekwencja, ale nie to, co ją wywołuje, co ona sama wywołuje ani co się psuje, gdy się zmienia. Klasyczne badanie polega na pętli: wyszukiwanie terminu, otwieranie pliku, sprawdzanie tego, co ten plik importuje, otwieranie również tego pliku i tak dalej, aż powstanie pełny obraz sytuacji. To działa, ale powoli, i wymaga wielu wywołań narzędzi do odbudowy modelu mentalnego opartego na faktach strukturalnych, które nie powinny być ponownie odkrywane siłą brutalną przy każdej sesji.

Węzeł wiedzy z uprzednio utworzonym indeksem zmienia zasady funkcjonowania systemu. Jedno zapytanie zwraca odpowiedni źródło wraz z rzeczywistymi ścieżkami połączeń: kto do niego dzwoni, do kogo on dzwoni oraz jak długa jest łańcuch zależności. Informacje te są uzyskiwane przy jednej próbie zamiast poprzez wiele wyszukiwań, dzięki czemu jest mniej cykli przesyłania danych i od razu dostępny pełniejszy obraz sytuacji, ponieważ szczegóły ścieżek połączeń, których grep nigdy by nie ujawnił, po prostu są dostępne w wyniku. Oficjalna dokumentacja Claude Code przedstawia podobne argumenty dotyczące wtyczek do analityki kodu, wskazując, że duże bazy kodu typowanego znacznie korzystają z zapytań uwzględniających strukturę w porównaniu z dopasowywaniem tekstu, gdzie powtarzające się cykle wyszukiwania i czytania szybko stają się kosztowne.

Warstwa 5: weryfikacja na rzeczywistym urządzeniu

Ważne jest to, czy zmiana działa na urządzeniu, czy jest jedynie skompilowana – to dwa różne stwierdzenia. W przypadku Flutter tego warstwy używa się najczęściej. Ponowne tworzenie projektu od zera w celu sprawdzenia drobnej modyfikacji interfejsu jest marnotrawstwem zasobów, gdy dostępna jest połączenie z aplikacją działającą na rzeczywistym sprzęcie, a to połączenie może wypełnić luki, do których generacja kodu nie ma dostępu. Dostarcza ono możliwości robienia zrzutów ekranu, przewijania się po interfejsie oraz inspekcji żywego drzewa interfejsu. Claude Code teraz prawidłowo obsługuje te funkcje, oferując dostęp do symulatora iOS oraz funkcje użyteczne na komputerze, które mogą zweryfikować wersję natywną aplikacji, odtworzyć błąd w układzie lub przetestować działanie interfejsu w symulatorze w porównaniu z tym, co jest wyświetlane.

Podłączenie się do VM Dart w celu szybkiego ładowania i restartu zmienia proces z domyślania się, odbudowywania, czekania i sprawdzania na domyślanie się, ładowanie i sprawdzanie. To szybsze i pozwala uniknąć częstego błędu: traktowania udanego skompilowania jako dowodu na skuteczność poprawki. Skompilowanie projektu oraz poprawne działanie na sprzęcie to dwa różne kryteria, a nawyk polegający wyłącznie na odbudowie nie pozwala ich odróżnić. Uruchomienie aplikacji na urządzeniu daje jednoznaczną odpowiedź na to pytanie.

Warstwa 6: ładowanie narzędzi tylko w razie potrzeby

Każde narzędzie znajdujące się w kontekście, niezależnie od tego, czy jest używane, czy nie, obciąża każdy etap pracy, a nie tylko te, w których jest wykorzystywane. Dlatego nie wszystko ładowuje się domyślnie – to świadoma decyzja projektowa. Specjalistyczne narzędzia, takie jak automatyzacja przeglądarek, rzadziej spotykane serwery MCP oraz wszystko, co jest używane sporadycznie, ładowane są na żądanie i nie zajmują kontekstu przez całą sesję.

Efekt ten nasila się w trakcie długiej sesji, ponieważ każda definicja narzędzia kosztuje tokeny przy każdej turze, niezależnie od tego, czy ta tura jej używa, czy nie. Funkcja wyszukiwania narzędzi MCP w Claude Code ma na celu rozwiązanie tego problemu. Serwery mogą zapisać się do funkcji odkrywania na żądanie zamiast wcześniej ładować wszystkie definicje na początku sesji, co zapewnia efektywność sesji trwającej kilka godzin i unika obciążenia niepotrzebnym kontekstem, który nigdy nie jest używany, ale nadal generuje koszty.

Warstwa 7: używaj pakietowanych procesów pracy, których naprawdę potrzebujesz

Claude Code dostarcza obszerny ekosystem pakietowanych procesów pracy, w tym przeglądy kodu, przeglądy bezpieczeństwa, narzędzia do weryfikacji specyficzne dla określonych frameworków oraz agenty do planowania i wykonywania zadań. Każde z nich można wywołać wyraźnie, dzięki czemu ta sama logika nie musi być budowana na nowo przy każdej sesji. Duża biblioteka ma małe znaczenie, jeśli używane są tylko trzy pozycje, więc dokładna statystyka faktycznego wykorzystania jest lepsza niż lista całego katalogu.

Trzy z nich są używane regularnie. Najpierw przeprowadzana jest ogólna weryfikacja kodu przed jakimkolwiek znaczącym połączeniem zmian. Recenzent skupiony na bezpieczeństwie sprawdza wszystko, co dotyczy autoryzacji lub obsługi danych. Specjalny podagent ds. planowania zajmuje się zadaniami na tyle dużymi, że bezpośrednie przejście do implementacji pominęłoby rzeczywiste przemyślenia architektoniczne. Te trzy rozwiązania obejmują niemal wszystkie wyraźne wezwania.

Większość recenzentów specyficznych dla określonych frameworków, używanych w nieaktywnych środowiskach, pozostaje nieużywana, podobnie jak bardziej ekskluzywne wzory podagentów zaprojektowane do dużych, równoległych zadań badawczych. To nie są słabe narzędzia – codzienna praca po prostu nie wymaga tak szerokiego zakresu analiz, a używanie narzędzi przewyższających potrzeby stanowi stratę zasobów. Ich wartość polega na znajomości trzech lub czterech narzędzi, które można polegać na nich w sposób niezawodny, bez poczucia obowiązku używania pozostałych tylko dlatego, że istnieją.

Warstwa 8: potwierdzenie poprzez odwracalność

Szybkość jest uznawana za atut tylko wtedy, gdy wynik pozostaje wiarygodny, a gdy zaufanie się zmniejsza, to właśnie szybkość powoduje szkodę. Nawet gdy wszystkie warstwy są aktywne, niektóre działania wymagają zawsze wyraźnej potwierdzenia: destruktywne operacje w Git, operacje push oraz wszystko, co jest naprawdę nieodwracalne. Żaden poziom automatyzacji nie daje prawa do pominięcia tej zasady, ponieważ błąd w tym przypadku oznacza nie koniecznie ponowne wykonywanie pracy, lecz naprawę szkód, które mogą okazać się nie do naprawienia.

Równowaga zależy od tego, na ile dana akcja jest odwracalna, a nie od tego, jak ryzykowna wydaje się zadanie. Duży refaktoryzacja dziesiątek plików wymaga dużo wysiłku, ale dzięki zarządzaniu wersjami pozostaje w pełni odwracalna, więc może być realizowana przy mniejszej kontroli. Jedno polecenie git push --force nie wymaga praktycznie żadnego wysiłku, ale może być trwale nieodwracalne, dlatego zawsze powinno być zabronione, bez względu na to, jak rutynowe wydaje się to działanie. Wysiłek i ryzyko znajdują się na różnych osiach, a ich łączenie prowadzi do tego, że zbyt duża swoboda jest przyznawana niewłaściwym działaniom.

Wybór między natychmiastowym działaniem a zapytaniem o zgodę nie polega na regulowaniu jednego parametru. To decyzja dotycząca konkretnego typu akcji, podjęta z góry i nigdy nie podnoszona ponownie w momencie, gdy zmęczenie sprawia, że prośba o potwierdzenie wydaje się irytującą przeszkodą.

Co dają te warstwy

Żadna z ośmiu warstw nie wyróżnia się sama w sobie. CLAUDE.md to plik tekstu prostego, a hook to polecenie w shellu, które uruchamia się we właściwym momencie. Razem sprawiają, że Claude Code przestaje być szybkim maszynistą pozbawionym trwałego kontekstu i jakiejkolwiek możliwości cofnięcia działań, a staje się narzędziem z pamięcią, zasadami bezpieczeństwa, wiedzą o strukturze bazy kodu oraz możliwością rzeczywistej weryfikacji urządzenia.

Sama konfiguracja nie jest najciekawszą częścią – interesujące są uzasadnienia za każdą warstwą. Każdy, kto używa Claude Code bez żadnej z tych konfiguracji, nie powinien próbować dodać wszystkich ośmiu naraz. Zacznij od prawdziwego pliku CLAUDE.md stworzonego w oparciu o błędy, które już dwukrotnie się zdarzyły, a następnie rozwijaj dalej.

Literatura pokrewna

• Praktyczne notatki: Claude Code Agent Teams: Praktyczny przewodnik po budowie zespołu — Krok po kroku instrukcja dotycząca Praktycznych notatek: Claude Code Agent Teams: Praktyczny przewodnik po budowie zespołu: kontrakty, sprawdzania oraz miejsca na kod do wstawienia dla zespołów stosujących ten wzorzec.
• Praktyczne notatki: Przestań obserwować swojego agenta kodującego: Buduj system, któremu możesz ufać — Krok po kroku instrukcja dotycząca Praktycznych notatek: Przestań obserwować swojego agenta kodującego: Buduj system, któremu możesz ufać: kontrakty, sprawdzania oraz miejsca na kod do wstawienia dla zespołów stosujących ten wzorzec.