/ CZYM TO NAPRAWDĘ JEST
CLAUDE.md siedzi w system prompcie
Większość programistów wpada w CLAUDE.md jak w README. „Krótki opis projektu, sekcja getting-started, paragraf o filozofii zespołu." Potem się dziwią, że Claude wraca z propozycjami patternów, które jasno wykluczyli, podpowiada komendy nieprzystające do ich stacka albo gubi się przy buildzie.
Claude Code wkleja CLAUDE.md do system promptu przy każdej turze rozmowy. To zmienia wszystko. README pisze się dla człowieka, który raz przeskanuje plik i potem o nim zapomni. CLAUDE.md piszesz dla modelu, który czyta go na zimno przy każdej odpowiedzi i na jego podstawie wybiera, jak się zachować. To są dwa zupełnie różne formaty pisania i ich pomylenie jest najczęstszą przyczyną frustracji.
/ PIĘĆ SEKCJI
Co siedzi w dobrze napisanym pliku
Po osiemnastu miesiącach intensywnej pracy z Claude Code (NeuraGrowth plus kilka mniejszych projektów) te same pięć sekcji wraca do każdego CLAUDE.md i każda z nich faktycznie zarabia swoje miejsce w kontekście. Reszta wylądowała na śmietniku.
- Tożsamość projektu (3 do 5 linijek). Jedno zdanie o tym, czym ten kod JEST, jedno o tym, czym NIE JEST (świeży projekt vs. fork vs. kontynuacja starego), plus cel deploya. Z tym Claude przestaje proponować rozwiązania na inny stack niż twój.
- Stack (tabela). Framework, runtime, package manager, baza, deploy. Maksymalnie pięć wierszy. Zero marketingowej waty („błyskawiczny", „najnowocześniejszy"). Model wie, co to Next.js.
- Repo i deploy (konkretne komendy). Adres remote, model brancha, komenda deploya. Jeśli deploy wymaga trzech komend pod rząd, wpisz wszystkie trzy, nie akapit „deploy idzie przez CI". Model nie kliknie w CI, on dosłownie potrzebuje stringa do uruchomienia.
- Zasady (5 do 7 punktów). Twarde ograniczenia: czego nigdy nie robić, co preferować, jaki jest house style. Każda zasada to jedna linijka. Bez akapitów. Jeśli zasada nie mieści się w linijce, to są dwie zasady, nie jedna.
- Lista „nie rób tego" (3 do 6 punktów). Anty-lista. Jawne zakazy na wzorce, po które Claude inaczej sięgnie odruchowo: „nie przypinaj wymagań ==", „nie dodawaj docstringów do wewnętrznych helperów", „nie sugeruj pytest fixtures, używamy unittest". Ta sekcja zwraca się dziesięciokrotnie.
/ CO WYRZUCIĆ
Pięć rzeczy, które są niemal w każdym pliku, a być nie powinny
To są wzorce, które wycinam przy każdym audycie CLAUDE.md. Technicznie nie są błędne, są po prostu szumem: zjadają tokeny i rozcieńczają sygnał, który Claude naprawdę wykorzystuje.
- Prozaiczny akapit „o projekcie". Claude przeczyta opis z package.json, docstringa głównego modułu i wykazu route'ów. Trzyzdaniowe streszczenie w CLAUDE.md powtarza to, co model już ma w zasięgu grepa.
- Diagramy ASCII art. Tokeny wydane na strukturę wizualną, której model nie umie wykorzystać do decyzji. Zamień to na płaską listę: „request flow: klient → middleware → handler → baza".
- Instrukcja instalacji. Jeśli to `npm install && npm run dev`, nie ma czego wpisywać. Jeśli to coś więcej, napisz `scripts/setup.sh` i odeślij do niego jedną linijką.
- Contributing guidelines. Plik CONTRIBUTING.md istnieje dokładnie po to. CLAUDE.md czyta Claude, nie zewnętrzny kontrybutor z GitHuba.
- Daty „last updated". Git już to śledzi. Data wpisana w treść pliku zgnije w tydzień i zacznie kłamać.
/ CO DODAĆ
Dwie sekcje, których brakuje większości plików
Oprócz pięcioodcinkowego kręgosłupa, dwa dodatkowe bloki dobrze się sprawdzają w projektach z jakąkolwiek nietrywialną logiką domenową.
- Słownik nazw specyficznych dla projektu. Jeśli w twoim kodzie „manifest" znaczy coś innego niż web manifest, „publisher" nie jest publisherem z JS-a, a „run" to twój własny pojęcie domenowe, wpisz jednolinijkową definicję. Inaczej Claude przy każdej turze importuje zły model mentalny.
- Częste pomyłki do unikania. Bieżący notes rzeczy, które ugryzły cię dwa razy. „Nie inicjalizuj poola DB asynchronicznie w workerze, daemon forkuje przed startem pętli zdarzeń, twórz przy pierwszym requeście." Jedno zdanie na pozycję. To jest dokładnie ta sekcja, gdzie siedzi największa wartość projektowa.
/ RYTM UTRZYMANIA
CLAUDE.md sam się nie aktualizuje
Każdy CLAUDE.md dryfuje. Stack się zmienia, konwencje się przesuwają, zasada, która liczyła się sześć miesięcy temu, jest dziś oczywista dla każdego, kto czyta kod. A zasada, którą potrzebowałeś dwa tygodnie temu, jeszcze nie weszła do pliku.
Lekarstwo to piętnastominutowy audyt raz w miesiącu. Otwórz CLAUDE.md, przeczytaj go na zimno i zadaj trzy pytania: czy coś tutaj jest już nieaktualne? czy coś jest tak oczywiste, że mogę to wywalić? co musiałem powiedzieć Claude'owi w tym miesiącu, a powinno być tutaj? Trzecie pytanie jest najbardziej produktywne, prowadź notatkę poprawek, które przekazywałeś Claude'owi w czacie, i raz w miesiącu wyłuskaj z niej wzorce do CLAUDE.md.
/ DŁUGOŚĆ
Ile linii ma mieć ten plik
Większość produkcyjnych CLAUDE.md, które widzę, ląduje na sześćdziesięciu do stu osiemdziesięciu linijkach, kiedy rytm audytu już się przyjmie. Poniżej sześćdziesięciu, prawdopodobnie liczysz, że model wykombinuje coś, co konsekwentnie myli. Powyżej stu osiemdziesięciu, zacząłeś się powtarzać albo opisywać rzeczy, które Claude przeczyta z samego kodu.
Sweet spot to: gęsto, deklaratywnie, skanowalnie z jednego rzutu okiem. Jeśli musisz przewijać, żeby znaleźć komendę deploya, to nie długość jest problemem, tylko kolejność sekcji.
/ NA KONIEC
CLAUDE.md to najtańsze narzędzie, jakie masz
Dobrze nastrojony CLAUDE.md ratuje więcej czasu modelu niż jakakolwiek inna pojedyncza interwencja. To jedyny element infrastruktury, który spłaca się w każdej turze każdej rozmowy, w nieskończoność, dopóki go nie usuniesz. Większość zespołów traktuje go jak nudny obowiązek. Traktowanie go jak część system promptu, i przycinanie zgodnie z tą logiką, zwraca się sto razy.