Poradnik CLAUDE.md

Napisz wlasciwy plik CLAUDE.md

CLAUDE.md to plik, ktory ksztaltuje sposob, w jaki Claude rozumie Twój projekt. Dobrze napisany oznacza mniej poprawek, lepszy kod i agentów, ktorzy faktycznie wiedza, nad czym pracuja.

Ten poradnik przeprowadzi Cie przez kazda sekcje pliku CLAUDE.md: od deklaracji stosu technologicznego po wskazowki dla poszczegolnych agentów. Postepuj krok po kroku i stworz własny plik.

Czym jest CLAUDE.md?

CLAUDE.md to plik Markdown umieszczony w katalogu glownym projektu. Gdy Claude Code rozpoczyna sesje, czyta ten plik jako pierwszy. Wszystko w nim staje sie czescia kontekstu Claude: Twój stos technologiczny, struktura plików, konwencje zespolu i wszelkie konkretne instrukcje, ktorych ma przestrzegac kazdy agent.

Traktuj to jako dokument briefingowy. Bez niego Claude musi zgadywac, jak zorganizowany jest Twój projekt. Z dobrym plikiem CLAUDE.md Claude juz wie, gdzie co sie znajduje, jakich wzorcow uzywac i czego unikac. Różnica w jakosci wynikow jest znaczaca.

“10 minut pracy nad CLAUDE.md oszczedza godziny poprawiania kodu wygenerowanego przez AI, ktory nie pasuje do wzorcow Twojego projektu.”

Na podstawie obserwacji setek projektów Claude Code

Slaby vs. dobry CLAUDE.md

Struktura i dokladnosc pliku CLAUDE.md bezposrednio wplywaja na jakosc pracy Claude w Twojej bazie kodu.

Slaby CLAUDE.md

✗Ogolnikowe instrukcje typu "stosuj najlepsze praktyki" bez konkretow
✗Brak mapy plików, wiec Claude zgaduje, gdzie umiescic nowy kod
✗Brak konwencji kodowania; styl wynikow zmienia sie miedzy sesjami
✗Brak komend do budowania i testowania, co prowadzi do blednych sugestii

Dobry CLAUDE.md

✓Jawnie podany stos z wersjami: React 19, Vite 6, Zustand 5, Tailwind 4
✓Czytelna mapa plików z kluczowymi katalogami i ich przeznaczeniem
✓Udokumentowane konwencje nazewnictwa, obsluga bledow i preferencje stylu
✓Komendy build, test i dev gotowe do skopiowania i uruchomienia

6 kluczowych sekcji

Dobrze skonstruowany plik CLAUDE.md obejmuje te szesc obszarow. Kazdy dostarcza Claude konkretnych informacji, z ktorymi moze natychmiast pracowac.

Deklaracja stosu technologicznego

Wymien jawnie swoje frameworki, biblioteki i ich wersje. Podaj menedzera pakietow, wersje Node i wszelkie wymagania środowiska uruchomieniowego. Claude uzywa tego do generowania kompatybilnego kodu bez zgadywania.

Mapa struktury plików

Opisz kluczowe katalogi i co sie w kazdym znajduje. Komponenty, store, serwisy, trasy API, typy. Krótki diagram drzewa z jednoliniowym opisem kazdego folderu sprawdza sie dobrze.

Konwencje kodowania

Udokumentuj konwencje nazewnictwa (camelCase dla plików, PascalCase dla komponentow), podejscie do obslugi bledow, kolejnosc importow i wszelkie reguly specyficzne dla projektu. Dzieki temu wyniki Claude pozostaja spojne z istniejacym kodem.

Komendy budowania i testowania

Dolacz komendy dev, build, test i lint. Gdy Claude musi cos zweryfikowac lub zaproponowac skrypt, uzyje dokladnie tych komend, ktorych oczekuje Twój projekt.

Wskazowki dla rol agentów

Jesli uzywasz wielu agentów (QA, Frontend, Backend, DevOps), dodaj sekcje opisujaca, na czym powinna skupic sie kazda rola. Jest to szczegolnie przydatne przy konfiguracji wieloagentowej AgentsRoom.

Obszary do unikania

Powiedz Claude, czego NIE robic. Nie modyfikowac plików konfiguracyjnych, nie zmieniac systemu autoryzacji, nie refaktoryzowac warstwy bazy danych. Jawne granice zapobiegaja niepozadanym zmianom ze strony agentów.

Stworz CLAUDE.md w 4 krokach

Nie musisz pisac wszystkiego naraz. Zacznij od podstaw i rozszerzaj w miare odkrywania, co Claude musi wiedziec.

Przeanalizuj projekt

Otwórz package.json i wymien kazdy framework, biblioteke i narzędzie uzywane w projekcie. Zapisz wersje. Sprawdz wymagania środowiska (wersja Node, wersja Python, baza danych). Z tego powstanie sekcja stosu technologicznego.

package.json + wersje środowiska + baza danych

Zmapuj drzewo plików

Zrob szybki przegląd drzewa katalogu src. Zidentyfikuj foldery najwyzszego poziomu i napisz jednoliniowy opis kazdego z nich. Skup sie na lokalizacji komponentow, store, serwisow, typow i tras API.

Drzewo src/ z opisami przeznaczenia

Udokumentuj konwencje

Przejrzyj istniejacy kod i zanotuj wzorce: jak nazywasz pliki, jak obslugujesz bledy, jak strukturyzujesz importy, czy uzywasz default czy named exports. Zapisz je jako krótkie reguly.

Nazewnictwo, importy, obsluga bledow, eksporty

Dodaj sekcje dla agentów

Jesli pracujesz ze specjalistycznymi agentami, dodaj obszary fokusa dla kazdej roli. Agent Frontend powinien znac Twoja biblioteke komponentow. Agent DevOps powinien znac pipeline wdrozen. Agent QA powinien znac framework testowy.

Obszary fokusa i unikania dla kazdej roli

Dlaczego AgentsRoom dla CLAUDE.md?

AgentsRoom zostal zbudowany z CLAUDE.md jako centralnym elementem, nie dodatkiem.

Wbudowany edytor CLAUDE.md

Edytuj CLAUDE.md bezposrednio w AgentsRoom z podswietlaniem skladni i automatycznym zapisem. Bez przełączania do edytora tekstu czy IDE.

Podglad na zywo dla kazdego agenta

Obserwuj w czasie rzeczywistym, jak kazdy agent interpretuje Twój CLAUDE.md. Śledź wyjscie terminala, aby upewnic sie, ze agenci przestrzegaja konwencji i respektuja obszary do unikania.

Kontekst na projekt

Kazdy projekt w AgentsRoom ma własny plik CLAUDE.md. Przelaczaj sie miedzy projektami, a kazdy agent automatycznie zaladuje odpowiedni plik kontekstowy dla danej bazy kodu.

Integracja rol agentów

14 rol agentów w AgentsRoom jest bezposrednio powiazanych z sekcjami CLAUDE.md. Zdefiniuj obszary fokusa i unikania dla kazdej roli, a kazdy agent pobierze dokladnie te instrukcje, ktore sa dla niego przeznaczone.

Watch what your CLAUDE.md does to Claude Code token usage

CLAUDE.md is prepended to every Claude turn. A bloated CLAUDE.md silently inflates Claude Code token usage on every message. AgentsRoom puts a per-session token meter on each agent so you can see exactly how much your CLAUDE.md is costing you, with a live cache hit rate to confirm it stays cached.

See the Claude Code token usage tracker

FAQ dotyczacy CLAUDE.md

Gdzie umiescic plik CLAUDE.md?+

Umiesc go w katalogu glownym projektu, obok package.json lub odpowiedniego pliku konfiguracyjnego. Claude Code odczytuje go automatycznie przy rozpoczeciu sesji w tym katalogu. Mozesz tez tworzyc zagniezdzone pliki CLAUDE.md w podkatalogach dla bardziej szczegolowego kontekstu.

Jaka powinna byc dlugosc pliku CLAUDE.md?+

Nie ma scislego limitu, ale celuj w 50 do 300 linii. Obejmij podstawy: stos technologiczny, strukture plików, konwencje i komendy. Zbyt krótki plik oznacza brak kontekstu dla Claude. Zbyt dlugi ryzykuje rozmycie waznych czesci niepotrzebnym szumem.

Czy CLAUDE.md dziala ze wszystkimi modelami Claude?+

Tak. CLAUDE.md jest odczytywany przez Claude Code niezaleznie od wybranego modelu (Opus, Sonnet lub Haiku). Wszystkie modele korzystaja z jawnego kontekstu projektu, choc wieksze modele jak Opus moga przyswajac i stosowac bardziej szczegolowe instrukcje.

Czy powinienem dodac CLAUDE.md do kontroli wersji?+

Tak, jesli chodzi o wspolne instrukcje projektu. Twój zespol skorzysta na spojnym zachowaniu AI u wszystkich deweloperow. Dla osobistych preferencji AgentsRoom obsluguje prywatne konfigurację agentów, ktore sa automatycznie dodawane do gitignore.

Czy moge uzywac CLAUDE.md z wieloma agentami?+

Oczywiscie. W AgentsRoom kazdy agent w projekcie czyta ten sam CLAUDE.md. Mozesz dodac sekcje specyficzne dla rol (np. notatki dla agenta QA w odroznieniu od agenta Frontend), aby kazdy specjalista otrzymal ukierunkowane instrukcje.

Jak czesto aktualizowac CLAUDE.md?+

Aktualizuj go przy kazdej zmianie struktury lub konwencji projektu. Dodales nowy framework? Zaktualizuj stos technologiczny. Zmieniles uklad katalogow? Zaktualizuj mape plików. Nieaktualny CLAUDE.md prowadzi do nieaktualnych sugestii.