Co wpisać do CLAUDE.md, żeby Claude Code działał lepiej

Claude Code

Co wpisać do CLAUDE.md, żeby Claude Code działał lepiej

W skrócie

Założyłeś CLAUDE.md, bo tak radzą wszędzie, ale efekt jest mizerny - Claude Code dalej zgaduje i pyta o oczywistości. Problem prawie zawsze leży w treści: albo plik jest zbyt ogólny ("to jest aplikacja webowa"), albo odwrotnie - ktoś wkleił do niego pół README i zjadł kontekst na rzeczy, które model przeczyta z samego kodu. Dobrze napisany CLAUDE.md działa jak briefing dla nowego członka zespołu, który zna programowanie, ale nie zna Waszego projektu.

Jak to wygląda w praktyce

Widać to na dwa sposoby. Pierwszy: masz plik z jednym zdaniem opisu i asystent nadal działa tak, jakby go nie było - zgaduje polecenia, wybiera nie te biblioteki, łamie Wasze konwencje. Drugi, mniej oczywisty: plik jest ogromny, bo wkleiliście do niego historię projektu, opis architektury i listę wszystkich endpointów, a mimo to Claude gubi najważniejsze reguły. Dzieje się tak, bo istotne instrukcje toną w morzu tekstu, a przy okazji każda sesja zaczyna się od zużycia sporej części kontekstu na wczytanie pliku. Bywa też, że plik zawiera reguły sprzeczne albo nieaktualne ("używamy Yarn"), przez co asystent robi coś, co dawno przestało obowiązywać.

Dlaczego Claude Code tak działa

Cała treść CLAUDE.md trafia do kontekstu na początku każdej sesji - to jego siła i jego ograniczenie. Siła, bo model ma te informacje od pierwszej wiadomości, bez czytania plików. Ograniczenie, bo kontekst jest skończony, a im więcej w nim tekstu, tym drożej kosztuje każda tura i tym łatwiej modelowi przeoczyć konkretną regułę. Dlatego opłaca się wpisywać wyłącznie to, czego Claude nie ustali sam. Struktury katalogów, listy plików czy sygnatury funkcji model odczyta narzędziami w kilka sekund - wpisywanie ich do CLAUDE.md to marnowanie miejsca. Za to konwencji zespołu, poleceń buildu specyficznych dla Waszego setupu czy zakazu ruszania pewnych katalogów nie wyczyta znikąd. To jest właściwa zawartość pliku: wiedza, która istnieje tylko w głowach zespołu.

Jak to rozwiązać krok po kroku

1. Zacznij od poleceń, których model używa najczęściej i najłatwiej się myli: jak zbudować projekt, jak uruchomić testy, jak odpalić linter i formatowanie. Podaj dokładne komendy, na przykład npm run test:unit, a nie ogólnik "uruchom testy".
2. Opisz konwencje kodu, które chcesz wymusić: styl importów, użycie typów, wzorce nazewnicze, format komunikatów commit. To reguły, których Claude nie odgadnie z pojedynczych plików, a które trzymają spójność repozytorium.
3. Wypisz twarde zakazy i ostrzeżenia: katalogi generowane, których nie wolno edytować, pliki konfiguracyjne wymagające ostrożności, obszary "tu nie wchodź bez pytania". Zakazy działają najlepiej, gdy są jednoznaczne i krótkie.
4. Dodaj informacje o środowisku, których nie widać w kodzie: wymaganą wersję języka i menedżera pakietów, sposób uruchamiania lokalnego serwera, ewentualne zmienne środowiskowe potrzebne do startu (bez wartości - tylko że są potrzebne).
5. Zamiast wklejać obszerną dokumentację, linkuj do niej: "reguły API opisane w docs/api.md", "architektura w ARCHITECTURE.md". Claude sięgnie po te pliki, gdy będą potrzebne, a Ty nie zapychasz kontekstu.
6. Na koniec przetnij plik. Przeczytaj go i skreśl wszystko, co model wyczyta z kodu albo co jest oczywiste. Celuj w zwięzłość - lepszy krótki plik z pięcioma trafnymi regułami niż długi, w którym giną najważniejsze.
7. Utrzymuj go żywy. Gdy w trakcie pracy poprawiasz Claude'a w tej samej sprawie po raz drugi, dopisz regułę - w sesji zrobisz to szybko, zaczynając wiadomość od znaku #.

Jak sprawdzić, że zadziałało

Najlepszy test to codzienna praca. Po edycji pliku wydaj kilka typowych poleceń i obserwuj, czy asystent używa Waszych komend i trzyma się konwencji bez przypominania. Jeśli tak - treść jest trafna. Warto też sprawdzić rozmiar: otwórz CLAUDE.md i oceń, czy da się go przeczytać w minutę. Gdy jest dłuższy niż strona-dwie, prawdopodobnie zawiera rzeczy, które można wyciąć albo przenieść do osobnych plików. Komenda /memory pokaże, że plik jest wczytywany, i pozwoli go od razu edytować. Ostateczny sygnał, że dobrze dobrałeś treść, jest ten sam co przy każdej dobrej konfiguracji - asystent przestaje pytać o rzeczy, które opisałeś, a jego domyślne wybory zaczynają pasować do Waszego projektu.

Wroc do listy: 100 najczestszych problemow 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