CLAUDE.md to plik, od którego zależy, czy praca z Claude Code przypomina współpracę z kimś, kto zna projekt, czy codzienne tłumaczenie wszystkiego od nowa. Każda nowa rozmowa z Claude zaczyna się z pustą głową. CLAUDE.md to kartka z wiedzą o projekcie, którą Claude czyta na starcie każdej sesji, zanim cokolwiek zrobi. W tym tekście pokazuję, jak ten plik stworzyć, co w nim zapisać, czego tam nie trzymać i jak działa jego uzupełnienie: auto-pamięć, którą Claude prowadzi sam.
Jeśli nie wiesz jeszcze, czym jest Claude Code, zacznij od artykułu agent AI a czat, w którym CLAUDE.md jest pierwszą z sześciu warstw robiących z asystenta specjalistę.
Dlaczego CLAUDE.md to najważniejszy plik w projekcie?
Bez CLAUDE.md za każdym razem tłumaczysz od nowa: czym jest projekt, jak nazywacie klientów, czego nie ruszać, jakim tonem pisać. Ten sam wykład w poniedziałek, wtorek i środę.
Z CLAUDE.md piszesz to raz. Każda kolejna sesja, Twoja i kolegi z zespołu, startuje z tą wiedzą. Plik leży w projekcie, więc wiedza zostaje przy pracy, a nie w Twojej głowie. Dla mnie to jedno z kryteriów, dla których w ogóle postawiłem na Claude Code: wracam do projektu po trzech tygodniach i nie muszę sobie niczego przypominać. Plik pamięta.
Najlepiej oddaje to analogia, której używam na szkoleniach. Zatrudniasz kogoś świetnego, kto każdego ranka ma amnezję. CLAUDE.md to kartka, którą ta osoba czyta przy kawie, zanim usiądzie do biurka. Onboarding nowego pracownika, zapisany raz. Dlatego ten plik jest ważniejszy niż jakakolwiek sztuczka z pisaniem poleceń.
Technicznie to zwykły plik tekstowy CLAUDE.md w głównym folderze projektu, napisany w markdownie. Otwierasz go i edytujesz jak notatkę.
Jak stworzyć CLAUDE.md, nie pisząc go od zera?
Nie musisz zaczynać od pustej kartki. Wpisz w Claude Code komendę:
/initClaude przejrzy folder i sam napisze pierwszą wersję pliku z tym, co odkrył. Jeśli CLAUDE.md już istnieje, zaproponuje ulepszenia zamiast go nadpisać.
Potem zrób rzecz, której wiele osób nie robi: przeczytaj ten plik i popraw go. Claude opisze to, co widać w plikach. Nie wie jednak tego, co masz w głowie, i właśnie to jest najcenniejsze. Jak /init wpisuje się w pierwszy dzień pracy z narzędziem, opisałem w artykule Claude Code od zera.
Co wpisać do CLAUDE.md?
- czym jest projekt i dla kogo
- zasady, których nie widać w plikach, na przykład „klientów nazywamy imieniem, nie nazwą firmy”
- rzeczy, których nie wolno ruszać
- ton i język materiałów
- wszystko, co poprawiasz Claude drugi raz
Ostatni punkt jest najważniejszy, bo to jedyny nawyk, który naprawdę buduje ten plik. Poprawiasz drugi raz to samo? Wpisz to do CLAUDE.md, a nie do rozmowy. Poprawka w rozmowie zniknie razem z nią. Poprawka w pliku zostaje na zawsze.
Jak można ułożyć taki plik?
Nie ma jednego wzoru i dobrze, bo CLAUDE.md powinien odzwierciedlać to, jak Ty pracujesz. Mogę pokazać ogólny układ, który sprawdza się u mnie, jako punkt wyjścia:
- Czym jest projekt - dwa, trzy zdania: co to jest, dla kogo, na jakim etapie
- Jak pracujemy - kto pracuje z Claude, czego oczekuje, czego nie trzeba mu tłumaczyć
- Zasady krytyczne - krótka lista rzeczy, których nie wolno złamać
- Mapa dokumentacji - który plik przeczytać przed jaką pracą, zamiast wklejać całą wiedzę do CLAUDE.md
- Sposób pracy - jak zapisujemy zmiany i jak je publikujemy
- Od czego zacząć sesję - na przykład „przeczytaj plan prac i powiedz, gdzie skończyliśmy”
- Rzeczy mniej ważne - na samym końcu
Dwie zasady z tego układu warto przenieść do każdego projektu. Pierwsza: najważniejsze rzeczy na górze, najmniej ważne na końcu. Druga: mapa dokumentacji zamiast dokumentacji. CLAUDE.md mówi, gdzie leży wiedza, a szczegóły siedzą w osobnych plikach.
Jeśli masz kilka projektów, możesz też położyć jeden CLAUDE.md w folderze, który zawiera je wszystkie, a osobne pliki w każdym projekcie. Claude Code czyta plik z folderu, w którym pracuje, i pliki z folderów nad nim. Zasady wspólne dla wszystkich projektów piszesz więc raz.
Czego nie wpisywać do CLAUDE.md?
- tego, co Claude sam widzi w plikach, na przykład spisu folderów czy listy dokumentów
- haseł, kluczy i danych osobowych, bo plik trafia do repozytorium i widzi go cały zespół
- liczb, które szybko się zdezaktualizują - to, co da się sprawdzić, niech Claude sprawdza za każdym razem, a nie czyta z pliku sprzed miesiąca
- długich procedur - te idą do osobnych plików albo do skilli, które ładują się dopiero wtedy, gdy są potrzebne. Tak działają moje skille do promptów dla modeli wideo i obrazu, których wersją w przeglądarce jest generator promptów
Zakaz wpisywania liczb brzmi jak drobiazg, a to pułapka łatwa do przeoczenia. Liczba zapisana w CLAUDE.md wygląda na fakt, więc Claude traktuje ją jak fakt, także wtedy, gdy dawno przestała być prawdziwa.
Ile linii powinien mieć CLAUDE.md?
Dokumentacja Claude Code zaleca, żeby plik miał poniżej 200 linii. Dłuższy zajmuje więcej pamięci sesji i, paradoksalnie, jest gorzej przestrzegany. Każda linia CLAUDE.md jedzie z każdą rozmową, więc długi plik zjada też limit, o czym piszę w artykule o limitach Claude Code.
Moja praktyka jest mniej rygorystyczna. Trzymam się okolic 500 linii i pilnuję, żeby najmniej ważne rzeczy były na końcu. Najważniejsze jest co innego: regularny przegląd. Plik, do którego tylko się dopisuje, puchnie niezauważenie. Raz na jakiś czas warto go przeczytać od początku, wyrzucić to, co się zdezaktualizowało, i przenieść szczegóły do osobnych plików.
Warto też wiedzieć, czym ten plik jest, a czym nie jest. CLAUDE.md to kontekst, a nie twarda blokada. Claude traktuje zapisane tam zasady poważnie, ale jeśli czegoś nie wolno zrobić pod żadnym pozorem, pilnuje się tego hookiem, czyli skryptem-bezpiecznikiem, który uruchamia się zawsze w określonym momencie. Im więcej zasad w pliku i im bardziej się ze sobą gryzą, tym większa szansa, że któraś zostanie pominięta.
Przy większych projektach pomaga folder .claude/rules/. Zamiast jednego wielkiego pliku trzymasz tam kilka mniejszych, każdy na jeden temat. Zasady ogólne wczytują się na starcie każdej sesji, tak jak CLAUDE.md. Zasady przypisane do konkretnych plików wczytują się dopiero wtedy, gdy Claude nad takimi plikami pracuje.
Jak dopisywać do CLAUDE.md w trakcie pracy?
Nie musisz otwierać pliku ręcznie. Wystarczy powiedzieć w rozmowie: „dopisz to do CLAUDE.md”. Komenda /memory otwiera pliki pamięci do edycji, gdy chcesz coś poprawić sam.
Uwaga na jedno rozróżnienie. Polecenie „zapamiętaj to” nie trafia do CLAUDE.md, tylko do auto-pamięci. Jeśli zasada ma obowiązywać cały zespół, poproś wprost o dopisanie do CLAUDE.md.
Auto-pamięć, czyli drugi zeszyt, który Claude prowadzi sam
Obok pliku, który piszesz Ty, działa drugi zeszyt. Claude prowadzi go sam: zapisuje Twoje poprawki i preferencje, żeby nie powtarzać tego samego błędu.
| CLAUDE.md | Auto-pamięć | |
|---|---|---|
| Kto pisze | Ty | Claude |
| Co zawiera | zasady i instrukcje | wnioski z Twoich poprawek |
| Gdzie leży | w projekcie, widzi go zespół | na Twoim komputerze, tylko Ty |
| Czy trafia do repozytorium | tak | nie |
Auto-pamięć też wczytuje się na starcie każdej sesji, a dokładnie jej spis treści. Działa osobno dla każdego projektu i nie przechodzi na inne komputery. Kiedy Claude coś zapisze albo odczyta, zobaczysz komunikat w rodzaju „Saved 2 memories”. Notatki przejrzysz komendą /memory. To zwykłe pliki tekstowe, więc możesz je poprawiać i usuwać.
Notatka to zdjęcie z konkretnego dnia. Jeśli projekt się zmienił, stara notatka może wprowadzać w błąd. Sam miałem notatkę sprzed dwóch miesięcy, która twierdziła coś, co przestało być prawdą. Dlatego raz na jakiś czas warto do nich zajrzeć.
Zasada podziału jest prosta: zasada dla całego zespołu idzie do CLAUDE.md, Twoja osobista preferencja może zostać w auto-pamięci. Jeśli chcesz, żeby coś obowiązywało kolegę, musi trafić do pliku w projekcie.
Wiedza, która zostaje przy pracy
CLAUDE.md to najprostsza warstwa Claude Code i zarazem ta, która daje najwięcej. Nie wymaga żadnej techniki, tylko nawyku: wszystko, co poprawiasz drugi raz, zapisujesz tam, gdzie przeczyta to każda kolejna sesja. Układaj go pod swój sposób pracy, trzymaj najważniejsze na górze i co jakiś czas przeczytaj go od początku.
Jeśli chcesz, żeby Twój zespół zbudował dobre CLAUDE.md dla swoich projektów, zobacz szkolenia AI dla firm albo umów się na konsultacje.