CLAUDE.md — najbardziej niedoceniana funkcja Claude Code
Plik CLAUDE.md to trwała pamięć Twojego projektu dla Claude Code. Jak go napisać, żeby działał, i dlaczego długość ma krytyczne znaczenie.
Większość użytkowników Claude Code tygodniami powtarza Claude’owi te same rzeczy: jakich konwencji używa projekt, jakiego frameworka nie wolno mieszać z innym, jak nazywać pliki testów. Przy każdej nowej sesji — od nowa. To jest właśnie problem, który rozwiązuje CLAUDE.md.
Czym jest CLAUDE.md
CLAUDE.md to zwykły plik tekstowy w formacie Markdown, umieszczony w katalogu głównym projektu. Claude Code automatycznie go wczytuje na początku każdej sesji — bez żadnych dodatkowych poleceń. To, co wpiszesz do tego pliku, staje się trwałym kontekstem, który Claude zna zanim padnie pierwsze pytanie.
Społeczność nazywa go „najbardziej niedocenianą dźwignią w całym narzędziu”. Nie bez powodu — różnica między projektem z dobrze napisanym CLAUDE.md a projektem bez niego jest widoczna od pierwszej minuty sesji.
Co warto wpisać do CLAUDE.md
Dobry CLAUDE.md odpowiada na pytania, których nie da się wywnioskować z samego kodu:
Architektura i struktura projektu. src/api/ to warstwa kontrolerów, src/services/ to logika biznesowa — nigdy odwrotnie. Claude nie będzie zgadywał, gdzie umieścić nową funkcję.
Konwencje, których nie widać w kodzie. Testy zawsze w __tests__/ obok testowanego pliku. Nazwy zmiennych po angielsku, komentarze po polsku. Async/await zamiast .then().
Czego nie robić. Nie używamy biblioteki X (zastąpiona przez Y). Nie modyfikujemy plików w src/generated/ — są automatycznie generowane. Nie commitujemy do main bezpośrednio.
Kontekst techniczny. Node.js 22, PostgreSQL 16, deployment na Railway. Ta informacja zmienia dobór rozwiązań przy każdym zadaniu.
Styl komunikacji. Jeśli chcesz krótkich odpowiedzi bez wyjaśnień — napisz to. Jeśli wolisz step-by-step z uzasadnieniami — też.
Reguła 200 linii
I tu pojawia się jeden z gorętszych sporów w społeczności: jak długi powinien być CLAUDE.md?
Odpowiedź, na którą wskazuje większość doświadczonych użytkowników: poniżej 200 linii. I nie jest to arbitralna liczba.
CLAUDE.md jest wczytywany do okna kontekstowego przy każdej turze rozmowy. Każda linia kosztuje tokeny — przez całą sesję, przy każdym zapytaniu. Zbyt długi CLAUDE.md to zjawisko nazywane context rot: plik tak obszerny, że sam zjada przestrzeń, którą miał chronić.
Widziano pliki CLAUDE.md liczące 800, 1000 linii. Efekt jest paradoksalny — Claude dostaje tyle instrukcji naraz, że część z nich zaczyna być ignorowana lub koliduje z innymi.
Jak pisać, żeby działało
Kilka zasad, które odróżniają CLAUDE.md używany przez zaawansowanych od przypadkowego:
Konkret zamiast ogółu. Nie „piszemy czysty kod" — tylko „każda funkcja ma maksymalnie 40 linii, wyjątki wymagają komentarza". Pierwsze nic nie zmienia. Drugie Claude stosuje dosłownie.
Reguły zamiast próśb. „Zawsze uruchom testy przed commitem" to instrukcja. „Byłoby miło, gdybyś uruchamiał testy" — nie jest.
Aktualność. CLAUDE.md to żywy dokument. Jeśli zmieniacie stack — aktualizujcie plik. Nieaktualne informacje są gorsze niż brak informacji, bo Claude będzie na nich polegał.
Hierarchia ważności. Najważniejsze rzeczy na górze — Claude czyta od początku i przy długich plikach koniec może mieć mniejszą wagę.
CLAUDE.md kontra instrukcja w każdej sesji
Pytanie, które pojawia się regularnie: po co plik, skoro można zacząć sesję od wklejenia kontekstu?
Powody są dwa. Po pierwsze — nie zapomnisz. Przy dziesiątej sesji w tygodniu nikt nie pamięta, żeby za każdym razem tłumaczyć architekturę. Po drugie — CLAUDE.md działa też dla subagentów i równoległych sesji, które nie mają dostępu do historii głównego czatu. Jeden plik, wszędzie działa.
Zrób go raz, dobrze — i zapomnij o powtarzaniu tych samych instrukcji.