CLAUDE.md. Claude czyta go na starcie każdej sesji, ale to nie jest blokada

Trzeci raz w tym tygodniu programista pisze Claude to samo. Testy uruchamiamy przez npm test, a nowe tabele w bazie dodajemy tylko migracją. Claude przeprasza, poprawia i w następnej sesji robi to samo. Takie rzeczy wpisuje się raz do pliku CLAUDE.md.

Każda sesja Claude Code zaczyna się od świeżego kontekstu. To, co padło wczoraj w rozmowie, dziś w nim nie istnieje, chyba że ktoś to zapisał. Anthropic radzi dopisywać coś do CLAUDE.md właśnie wtedy, gdy Claude drugi raz popełnia ten sam błąd albo gdy wpisujecie poprawkę, którą wpisywaliście już w poprzedniej sesji.

Gdzie leży plik CLAUDE.md

CLAUDE.md to zwykły plik Markdown, który Claude Code wczytuje na początku każdej sesji. Może leżeć w kilku miejscach, a każde ma inny zasięg.

Plik projektu leży w głównym folderze jako CLAUDE.md albo .claude/CLAUDE.md. Trafia do repozytorium, więc widzi go cały zespół. Tu wpisuje się polecenia do budowania i testów, konwencje w kodzie i ważne decyzje o architekturze.

Plik użytkownika, ~/.claude/CLAUDE.md, działa we wszystkich Waszych projektach. To miejsce na osobiste przyzwyczajenia. Prywatne notatki do jednego projektu idą do CLAUDE.local.md w głównym folderze, który dopisuje się do .gitignore. Firma może też przez dział IT rozdać jeden wspólny plik na wszystkie komputery.

Pliki z folderu, w którym uruchamiacie Claude Code, i z folderów nad nim wczytują się na starcie. Pliki z podfolderów dochodzą dopiero wtedy, gdy Claude zacznie pracować na plikach w danym podfolderze. Nie nadpisują się nawzajem, tylko są sklejane w jeden kontekst. Czy plik się wczytał, sprawdzicie poleceniem /context na liście Memory files.

To kontekst, a nie ustawienia

To zdanie z dokumentacji Anthropic dobrze zapamiętać. Claude traktuje CLAUDE.md jako kontekst, a nie wymuszoną konfigurację. Treść pliku trafia do modelu jako wiadomość po instrukcjach systemowych. Claude ją czyta i stara się jej trzymać, ale nie ma gwarancji, że zrobi to zawsze, zwłaszcza gdy instrukcje są ogólnikowe albo sobie przeczą.

Z tego wynika prosta zasada. Jeśli coś ma być zablokowane bez względu na to, co uzna Claude, to nie jest zadanie dla CLAUDE.md. Zakaz zmieniania pliku czy uruchamiania polecenia ustawia się w regułach uprawnień w plikach ustawień. Rzeczy, które muszą się dziać w określonym momencie, na przykład formatowanie po każdej edycji, zapisuje się jako hook, czyli polecenie, które Claude Code sam uruchamia przy danym zdarzeniu.

CLAUDE.md jest od wiedzy i zasad pracy. Od zakazów są ustawienia i hooki.

Jak napisać CLAUDE.md, którego Claude się trzyma

Anthropic podaje przykłady. „Używaj wcięć na 2 spacje” zamiast „formatuj kod porządnie”. „Uruchom npm test przed commitem” zamiast „testuj zmiany”. „Handlery API leżą w src/api/handlers/” zamiast „trzymaj porządek w plikach”.

Instrukcja ma być na tyle konkretna, żeby dało się sprawdzić, czy została wykonana. Ta sama zasada działa w zwykłych promptach.

Druga rada dotyczy długości. Dokumentacja zaleca mniej niż 200 linii na plik, bo dłuższy plik zajmuje więcej kontekstu i Claude gorzej się go trzyma. Gdy dwie instrukcje sobie przeczą, Claude może wybrać jedną z nich przypadkowo. Dlatego dobrze grupować zasady pod nagłówkami i co jakiś czas wyrzucać to, co już nieaktualne.

Tak może wyglądać krótki plik dla wymyślonego projektu.

# Panel zamówień

## Polecenia
- `npm install` instaluje zależności
- `npm test` uruchamia testy, puść je przed każdym commitem
- `npm run dev` startuje serwer lokalny

## Zasady
- TypeScript, wcięcia na 2 spacje
- Handlery API leżą w `src/api/handlers/`
- Nowa tabela w bazie tylko przez migrację
- Teksty dla użytkownika tylko przez pliki tłumaczeń w `src/i18n/`

## Bez pytania nie zmieniaj
- plików w `src/legacy/`
- listy zależności w `package.json`

Nie ma tu opisu firmy ani próśb o „dobry, czysty kod”. Claude sam widzi kod. Plik mówi mu tylko to, czego z kodu nie wyczyta.

/init, /memory i importy

Nie trzeba zaczynać od pustej kartki. Polecenie /init przegląda projekt i tworzy pierwszą wersję CLAUDE.md z poleceniami do budowania, testami i konwencjami, które znalazł. Jeśli plik już istnieje, /init proponuje poprawki zamiast go nadpisywać.

Wynik trzeba przeczytać i skrócić, jak każdą instrukcję napisaną przez AI. Pisaliśmy o tym przy powtarzalnych wynikach AI.

/memory otwiera pliki CLAUDE.md do edycji i pozwala włączyć albo wyłączyć automatyczną pamięć. To osobny mechanizm, w którym Claude sam zapisuje notatki z Waszych poprawek.

Dłuższą dokumentację można dołączyć importem, czyli ścieżką po znaku @, na przykład @docs/git.md. Import porządkuje plik, ale nie oszczędza kontekstu, bo zaimportowany plik też wczytuje się na starcie. Zasady dla jednej części projektu lepiej przenieść do folderu .claude/rules/ z polem paths. Taka reguła wczytuje się dopiero wtedy, gdy Claude pracuje na pasujących plikach.

Zacznijcie od /init i wytnijcie z wyniku wszystko, co Claude i tak zobaczy w kodzie. Potem dopisujcie po jednym zdaniu za każdym razem, gdy ten sam błąd wróci drugi raz.