CLAUDE.md — najlepsze praktyki (z pełnym przykładem)

CLAUDE.md to najdroższy plik w twoim repozytorium. Nie w bajtach. W powtórzeniach. Cokolwiek tam wrzucisz, jest wczytywane do kontekstu Claude'a na starcie każdej sesji i jedzie dalej z każdą pojedynczą wiadomością, którą potem wyślesz. Rozdęty CLAUDE.md to podatek, który płacisz setki razy dziennie, w ogóle tego nie zauważając.

W SkillProof testujemy setupy Claude'a zawodowo i przeczytaliśmy już więcej plików CLAUDE.md, niż chcielibyśmy przyznać. Większość z nich robi to źle w ten sam sposób: traktują plik jak wysypisko wszystkiego, co autor kiedykolwiek chciał przekazać Claude'owi. Filozofia kodowania, preferencje tonu, pełny style guide, trzy akapity o ostrożności. Wszystko to załadowane, cały czas, przy każdym requeście — łącznie z tym, w którym poprosiłeś Claude'a o zmianę nazwy zmiennej.

Ten przewodnik to nasza próba naprawienia tego. Do czego CLAUDE.md naprawdę służy, kompletny przykład z komentarzami do zaadaptowania, co przenieść do skilli i arytmetyka, która wyjaśnia, czemu to wszystko w ogóle ma znaczenie.

Czym jest CLAUDE.md i kiedy się ładuje

CLAUDE.md to plik pamięci projektu w Claude Code. Gdy startujesz sesję w katalogu, Claude Code idzie w górę od katalogu roboczego, szukając plików CLAUDE.md, i ładuje znalezione do kontekstu systemowego. Twój globalny plik w ~/.claude/CLAUDE.md też się ładuje, w każdym projekcie. Pliki w podkatalogach ładują się, gdy Claude pracuje z plikami w tych podkatalogach.

Część, którą ludzie przegapiają: to nie jest jednorazowy odczyt. Modele językowe są bezstanowe, więc pełny kontekst, łącznie z twoim CLAUDE.md, jest wysyłany z każdym requestem w rozmowie. Zadaj czterdzieści pytań w sesji, a plik zostanie przesłany czterdzieści razy. Prompt caching łagodzi koszt w dolarach — do konkretnych liczb jeszcze dojdziemy — ale nic nie łagodzi kosztu uwagi. Każdy token w CLAUDE.md to token konkurujący z twoim właściwym kodem o skupienie modelu.

To cena. Kupuje ci coś realnego: Claude zaczyna każdą sesję, znając już twoje komendy builda, dziwactwa architektury i miny w codebase. Nikt nie musi wklejać „używamy pnpm, nie npm" po raz dziewiąty. Pytanie nigdy nie brzmi, czy mieć CLAUDE.md. Brzmi: co zasługuje w nim na miejsce.

Złota zasada: fakty w CLAUDE.md, zachowania w skillach

Oto teza całego artykułu i jedyny filtr, który naprawia większość złych plików:

CLAUDE.md jest na fakty o tym projekcie. Skille są na zachowania wielokrotnego użytku.

Fakt o tym projekcie: „ceny przechowujemy jako liczby całkowite w centach". Claude nie jest w stanie tego zgadnąć. Żadna ilość ogólnej inteligencji nie wywiedzie tego z powietrza, a pomyłka psuje dane. To należy do CLAUDE.md, załadowane na stałe, bo jest istotne przy niemal każdej zmianie dotykającej pieniędzy.

Zachowanie wielokrotnego użytku: „przy code review najpierw sprawdź obsługę błędów, potem bezpieczeństwo, potem nazewnictwo". To nie jest fakt o twoim projekcie. To procedura, dotyczy każdego projektu, jakiego kiedykolwiek dotkniesz, i jest istotna tylko wtedy, gdy faktycznie robisz review. Wrzuć ją do CLAUDE.md, a płacisz za nią przy każdym commit message, każdej poprawce CSS, każdym „co robi ta funkcja". Wrzuć ją do skilla, a kosztuje cię jedną linijkę metadanych aż do chwili, gdy review naprawdę się dzieje — wtedy pełne instrukcje ładują się na żądanie.

Większość ludzi upycha wszystko w CLAUDE.md, bo to plik, o którym wiedzą. Jest pod ręką, ewidentnie działa, a koszt jest niewidzialny, bo żadna faktura nie mówi „zapłaciłeś za swój style guide 4000 razy w tym miesiącu". Ale koszt jest realny, a podział staje się niemal mechaniczny, gdy o dowolną instrukcję zadasz dwa pytania. Czy jest prawdziwa tylko dla tego projektu? Czy jest istotna dla większości requestów? Dwa razy „tak": CLAUDE.md. Wszystko inne: skill albo kosz.

Jest też drugi powód podziału, niemający nic wspólnego z tokenami. Instrukcje w pliku ładowanym zawsze konkurują ze sobą. Widzieliśmy CLAUDE.md na 2000 słów, w którym naprawdę ważna zasada („nigdy nie odpalaj db:push na stagingu") siedziała w jedenastym akapicie, pod wykładem o czystym kodzie. Claude podchodzi do długich list instrukcji tak jak ludzie: ostre punkty rozmywają się w wypełniaczu wokół nich. Krótkie pliki są słuchane. Długie pliki są przelatywane wzrokiem.

Przykład CLAUDE.md z komentarzami dla średniej wielkości aplikacji webowej

Oto kompletny przykład dla fikcyjnego, ale realistycznego sklepu na Next.js. Komentarze wyjaśniają, czemu każda sekcja zasługuje na stałe miejsce w kontekście. Wychodzi około 350 słów, z grubsza 500 tokenów, i twierdzimy, że nie ma tu nic do wycięcia.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Zauważ, czego tu nie ma. Żadnego „pisz czysty, łatwy w utrzymaniu kod". Żadnych instrukcji tonu. Żadnego tłumaczenia, czym jest Next.js. Żadnych reguł lintu, które linter i tak egzekwuje mechanicznie. Każda linijka to albo komenda, którą Claude wykona, albo fakt, którego nie może wywnioskować, albo granica, której przekroczenie kosztuje realne pieniądze lub realne godziny.

Co przenieść do skilli

Jeśli twój obecny CLAUDE.md ma 1500 słów, nadmiar zwykle wpada w kilka rozpoznawalnych kubełków, a każdy kubełek ma dom w kształcie skilla. Kilka przykładów z naszego własnego katalogu — wszystkie zainstalowane i przetestowane na czystych maszynach, zanim je dodaliśmy:

Ceremonia gita. Nazewnictwo branchy, format commit message, szablony opisów PR, kiedy squashować. To zachowanie, identyczne we wszystkich twoich projektach i istotne tylko wtedy, gdy faktycznie commitujesz. Skill git-workflow, który testowaliśmy, obsługuje dokładnie ten zakres, a wyniesienie go z CLAUDE.md oszczędza zwykle 200–400 słów tekstu ładowanego zawsze.

Checklisty review. Instrukcje typu „gdy proszę o review, sprawdź X, potem Y" to klasyczny dziki lokator CLAUDE.md. Są długie, proceduralne i uśpione przez 95% czasu. code-review-checklist ładuje swoją checklistę tylko wtedy, gdy review faktycznie się dzieje — i o to cały format skilli.

Dyscyplina debugowania. Instrukcje w rodzaju „zreprodukuj przed naprawą, postaw hipotezę, zweryfikuj po" opisują metodologię, nie twój projekt. systematic-debugging pakuje tę metodologię i trzyma się z dala od kontekstu, gdy robisz cokolwiek innego niż gonienie buga.

Zasada ogólna: jeśli mógłbyś skopiować akapit do CLAUDE.md innego projektu bez edycji, to nie jest fakt o twoim projekcie i nie powinien tam mieszkać. Wyodrębnij go. Napisanie własnego skilla zajmuje około dwudziestu minut z naszym przewodnikiem i to najbardziej opłacalne dwadzieścia minut dostępne każdemu, czyj CLAUDE.md przekroczył jeden ekran.

Antywzorce, które ciągle widzimy

Przeglądamy mnóstwo setupów i te same pięć porażek wraca jak bumerang.

Powieść. CLAUDE.md na 3000 słów, czytający się jak podręcznik inżynierii. Ktoś miał złe doświadczenie, dodał akapit, miał kolejne, dodał kolejny — i nigdy nic nie skasował. Plik tylko rośnie. Poza kosztem tokenów takie pliki grzebią dwie zasady, które naprawdę się liczą, pod dwudziestoma, które się nie liczą, a posłuszeństwo Claude'a wobec wszystkich spada razem.

Nieaktualne komendy. Plik mówi npm run test:unit, skrypt przemianowano na pnpm test osiem miesięcy temu, i teraz Claude z pełnym przekonaniem odpala komendę, która pada, czyta błąd, grzebie w package.json i jakoś się pozbiera. W każdej sesji. Płacisz za złą dokumentację, a potem płacisz drugi raz za to, żeby Claude ją obszedł. Błędny CLAUDE.md jest gorszy niż brak CLAUDE.md, bo Claude mu ufa.

Zduplikowane reguły lintu. „Pojedyncze cudzysłowy. Zero nieużywanych zmiennych. Maks 100 znaków w linii." Twój config ESLinta już to egzekwuje mechanicznie, z lepszym pokryciem, niż uwaga LLM-a kiedykolwiek zapewni. Powtarzanie prozą reguł egzekwowanych maszynowo to czyste marnotrawstwo. Jeden wyjątek: reguły, których tooling nie złapie, jak „nie importuj z src/legacy" — te naprawdę trzeba zapisać.

Sekcja „bądź pomocny". „Pisz czysty kod. Myśl uważnie przed zmianami. Bądź dokładny, ale zwięzły." Jakąś wariację tego widzimy w mniej więcej połowie plików, które przeglądamy, i nie robi ona nic. Claude i tak się stara. Instrukcje oparte na vibe'ach, bez testowalnej treści, to pierwsza rzecz do skasowania, a ich jedyny mierzalny efekt to spalone tokeny.

Autobiografia. Długie opisy tego, co robi produkt, kim są użytkownicy, misja firmy. Czasami jeden fakt produktowy ma znaczenie dla decyzji w kodzie („nasi użytkownicy siedzą na wolnych łączach na wsi, rozmiar bundle'a to realne ograniczenie"). Zostaw to jedno zdanie. Wytnij pitch deck.

Matematyka tokenów

Zróbmy arytmetykę, którą wszyscy pomijają, bo to właśnie liczby zrobiły z nas minimalistów.

CLAUDE.md na 3000 słów to z grubsza 4000 tokenów. Jedzie z każdym requestem, więc robocza sesja na 40 wiadomości przesyła go 40 razy: 160 000 tokenów inputu w jednej sesji, które są twoim plikiem pamięci, a nie kodem czy rozmową. Pracuj pięć sesji dziennie, a przerzucasz 800 000 tokenów CLAUDE.md dziennie. W 22-dniowym miesiącu — około 17,6 miliona.

Prompt caching ratuje większość kosztu w dolarach i bądźmy co do tego uczciwi. Cache'owany input na Sonnecie kosztuje jedną dziesiątą ceny bazowej, więc te 17,6 mln tokenów to parę dolarów miesięcznie przy ciepłym cache'u, bliżej 50 $, gdy cache nie trzyma. Irytujące, nie rujnujące.

Kosztem, którego caching nie ratuje, jest kontekst. Okno kontekstowe Claude Code jest skończone, a długie sesje i tak kończą się kompakcją, w której rozmowa jest streszczana i detale przepadają. Stały lokator na 4000 tokenów oznacza, że w kompakcję wpadasz wcześniej, w każdej sesji, na zawsze. Degraduje też uwagę na długo przed twardym limitem: modele mierzalnie lepiej wykonują instrukcje, gdy konkuruje ich mniej. Różnica między plikiem na 500 tokenów a plikiem na 4000 to nie 3500 tokenów. To pytanie, czy model wciąż przejmuje się twoją zasadą „nigdy nie dotykaj stagingu" przy wiadomości 35.

Przelicz te same liczby na odchudzonym przykładzie powyżej: 500 tokenów, 40 wiadomości, pięć sesji, 22 dni. Około 2,2 mln tokenów miesięcznie, jedna ósma wersji rozdętej, a ważne zasady stoją w niezatłoczonym pokoju. Szerszy playbook cięcia kosztów opisaliśmy w przewodniku po kosztach tokenów, a odchudzanie CLAUDE.md to w nim konsekwentnie najtańsza wygrana.

Projektowy vs globalny: podział na ~/.claude/CLAUDE.md

Masz dwa pliki, a problemy zaczynają się, gdy treść trafia do niewłaściwego.

~/.claude/CLAUDE.md jest globalny. Ładuje się w każdym projekcie, więc może zawierać tylko rzeczy prawdziwe wszędzie: „we wszystkich prywatnych projektach używam pnpm", „odpowiadaj po angielsku, nawet gdy moje prompty są czasem po rosyjsku", „nigdy nie commituj bez wyraźnej prośby". Trzymaj go poniżej dziesięciu linijek. Każda linijka tutaj mnoży się przez całą twoją pracę, więc jej budżet powinien być najciaśniejszy.

<project>/CLAUDE.md to plik projektowy, wrzucony do gita, współdzielony z zespołem i CI. Fakty o tym codebase, w kształcie przykładu powyżej. Ponieważ jest współdzielony, osobiste preferencje do niego nie należą; od tego jest CLAUDE.local.md albo plik globalny.

Pliki CLAUDE.md w podkatalogach to niedoceniany środkowy poziom. packages/api/CLAUDE.md z faktami specyficznymi dla API ładuje się tylko wtedy, gdy Claude dotyka tej paczki. Jeśli plik główny twojego monorepo ma sekcje dotyczące jednego workspace'a, zepchnięcie ich poziom niżej to darmowa oszczędność tokenów przy zerowej utracie informacji.

Jedno przekonanie warte uśmiercenia: umieszczenie czegoś w więcej niż jednym z tych plików nie sprawia, że Claude słucha tego mocniej. Sprawia tylko, że plik jest dłuższy. Wybierz jeden dom na jeden fakt.

Jak utrzymać go świeżym

CLAUDE.md gnije szybciej niż zwykła dokumentacja, bo gdy jest błędny, nic nie psuje się w widoczny sposób. Testy padają głośno. Nieaktualny plik pamięci po cichu zwodzi model, model po cichu się pozbiera, a ty po cichu płacisz za jedno i drugie.

Nasz rytuał jest nudny i zajmuje dziesięć minut w miesiącu. Otwórz plik. Każdą komendę faktycznie uruchom. Przy każdym stwierdzonym fakcie zapytaj, czy nadal jest prawdziwy i czy Claude pomylił się w tym miesiącu przez niego. Skasuj przynajmniej jedną linijkę; zawsze jakaś jest, a jeśli nie możesz jej znaleźć, twoje standardy „zasługiwania na miejsce" się obsunęły. Potem sprawdź długość: jeden ekran to cel, dwa ekrany to sufit, a powyżej już nie edytujesz — wyodrębniasz do skilli.

Najlepszym wyzwalaczem aktualizacji nie jest jednak kalendarz. Jest nim moment, w którym Claude robi coś źle, bo plik go zmylił. Napraw plik jednym tchem razem z kodem. Traktuj bugi w CLAUDE.md jak bugi, bo mają tę samą charakterystykę nawrotów: nienaprawione, wracają w następnej sesji.

FAQ

Jak długi powinien być CLAUDE.md?

Poniżej 500 słów dla większości projektów, poniżej 1000 dla naprawdę skomplikowanego monorepo. Nasz roboczy test: jeśli nie mieści się na jednym ekranie, coś w nim jest zachowaniem udającym fakt i to coś należy do skilla. Przykład z tego artykułu ma około 350 słów i pokrywa realną, średniej wielkości aplikację.

Czym różni się CLAUDE.md od skilla?

Sposobem ładowania. CLAUDE.md ładuje się w całości, zawsze, przy każdym requeście. Skill wystawia tylko jednolinijkowy opis, aż zadanie do niego pasuje — wtedy ładuje się na żądanie. CLAUDE.md powinien więc trzymać fakty potrzebne stale, a skille — procedury potrzebne okazjonalnie. Mechanikę opisuje nasz przewodnik po skillach.

Czy commitować CLAUDE.md do gita?

Tak. To współdzielona dokumentacja, a sesje Claude'a twoich kolegów z zespołu korzystają z tych samych faktów co twoje. Osobiste preferencje trzymaj w CLAUDE.local.md (w gitignore) albo w pliku globalnym, zamiast narzucać je zespołowi.

Czy mogę używać zagnieżdżonych plików CLAUDE.md w podkatalogach?

Tak, a w monorepo wręcz powinieneś. Claude Code ładuje plik podkatalogu, gdy pracuje z plikami w nim. Plik główny dostaje fakty ogólnorepozytoryjne, packages/api/CLAUDE.md — fakty o API, a projekty jednopaczkowe mogą całkiem pominąć zagnieżdżanie.

Czy odchudzenie CLAUDE.md naprawdę zmienia zachowanie Claude'a, czy tylko koszt?

Jedno i drugie, a zachowanie to większa wygrana. Wykonywanie instrukcji degraduje się wraz z ich liczbą; krótki plik z pięcioma ostrymi zasadami jest słuchany pewniej niż długi z trzydziestoma. Oszczędność tokenów to część mierzalna — nasze rankingi efektywności śledzą, które skille pomagają tam najbardziej — ale poprawę posłuszeństwa zauważysz pierwszą.

Ostatnia opinia: najlepsze pliki CLAUDE.md, jakie widzieliśmy, były wszystkie edytowane przez kasowanie. Nikt nie pisze świetnego pierwszego dnia. Piszesz przeciętny, patrzysz, gdzie Claude się potyka, dodajesz fakt, który by temu zapobiegł, i wycinasz linijkę wypełniacza, żeby za niego zapłacić. Sześć tygodni tego bije każdy szablon, łącznie z naszym.