CLAUDE.md - jak skonfigurować Claude Code żeby znał Twój projekt jak własną kieszeń

Seria Claude Code · JSystems

Claude Code bez pliku CLAUDE.md jest jak nowy programista bez onboardingu - marnuje Twój czas na pytania które mógłby sam znaleźć. Każde zadanie zajmuje 3× dłużej, bo agent nie wie jak działa Twój projekt, jakie masz konwencje, ani jak uruchomić testy.

Jeden dobrze napisany plik zmienia wszystko. Claude zaczyna rozumieć architekturę, zna Twoje zasady nazewnictwa, wie gdzie szukać konfiguracji. Przestajesz powtarzać te same rzeczy w każdym prompcie.

Krok 1 - Zrozum czym jest CLAUDE.md

Wyobraź sobie nowego developera w zespole. Żeby był produktywny, potrzebuje: zrozumieć architekturę projektu, poznać konwencje kodu, wiedzieć jak uruchamiać testy i deploye, znać specyficzne decyzje projektowe i ograniczenia. Bez onboardingu każde zadanie zajmuje 3× dłużej. CLAUDE.md to właśnie onboarding dla Claude Code - bez niego agent działa po omacku.

Claude Code szuka CLAUDE.md w kilku miejscach (hierarchia):

• ~/.claude/CLAUDE.md - globalne ustawienia użytkownika (dla wszystkich projektów)
• ./CLAUDE.md - ustawienia projektu (katalog główny)
• ./src/CLAUDE.md - ustawienia dla podkatalogu

Wolisz nauczyć się tego z doświadczonym trenerem w formie warsztatowej? Szkolenie Claude Code z terminem gwarantowanym -->

Hierarchia w praktyce: jak Claude scala te pliki

Claude Code nie wybiera jednego pliku CLAUDE.md — on je łączy. Przy starcie sesji wczytuje po kolei: plik globalny (~/.claude/CLAUDE.md), plik w katalogu głównym projektu (./CLAUDE.md), a gdy pracuje w podkatalogu — także pliki CLAUDE.md napotkane po drodze w górę drzewa. Wszystkie obowiązują jednocześnie.

Reguły nakładają się addytywnie, a nie „albo-albo”: globalne preferencje (np. „odpowiadaj po polsku”) współgrają z regułami projektu (np. „testy przez pytest”), a te z regułami podkatalogu (np. „w module płatności nigdy nie loguj numerów kart”). Im bliżej pliku, nad którym Claude pracuje, tym bardziej szczegółowa reguła — i to ona wygrywa, gdy dwie się przenikają.

Zagnieżdżone CLAUDE.md — porządek w dużym repo

W większym projekcie albo monorepo jeden plik na wszystko szybko puchnie. Rozwiązaniem są zagnieżdżone pliki CLAUDE.md — osobny w każdym module:

repo/
├─ CLAUDE.md            # zasady wspólne dla całego repo
├─ backend/
│  └─ CLAUDE.md         # konwencje API, baza, migracje
├─ frontend/
│  └─ CLAUDE.md         # komponenty React, design system
└─ infra/
   └─ CLAUDE.md         # Terraform, deploy, sekrety

Plik z podkatalogu Claude wczytuje dopiero wtedy, gdy faktycznie sięga po pliki w tym module — nie obciąża kontekstu, gdy pracujesz gdzie indziej. Dzięki temu reguły trzymasz blisko kodu, którego dotyczą.

Reguła kciuka: w głównym CLAUDE.md zostaw to, co dotyczy wszystkich (komendy, architektura, „czego nie robić”), a szczegóły danego modułu opisz w jego własnym pliku.

Krok 2 - Napisz strukturę CLAUDE.md krok po kroku

Dobry plik CLAUDE.md ma kilka sekcji. Każda z nich odpowiada na inne pytanie które Claude mógłby zadać. Poniższy przykład to szablon dla projektu e-commerce z FastAPI i React - dostosuj do swojego projektu.

Poniższy kod to kompletny przykład pliku CLAUDE.md. Czytaj komentarze - wyjaśniają po co jest każda sekcja i co powinieneś w niej napisać dla swojego projektu:

# Projekt: [Nazwa]

## Architektura
- Backend: FastAPI + PostgreSQL + Redis
- Frontend: React 18 + TypeScript + Zustand
- Deployment: Docker + Kubernetes (GKE)
- Komunikacja: REST API + WebSocket dla real-time

## Konwencje kodu

### Python
- Type hints obowiązkowe wszędzie
- Formatowanie: black + isort
- Docstrings w stylu Google
- Testy: pytest, coverage min 80%

### TypeScript
- Strict mode włączony
- Komponenty jako function components z hooks
- Nazewnictwo: PascalCase dla komponentów, camelCase dla funkcji

## Komendy

### Uruchomienie lokalne
docker-compose up -d
cd backend && uvicorn main:app --reload
cd frontend && npm run dev

### Testy
# Backend
pytest tests/ -v --cov=app
# Frontend
npm test -- --coverage

### Deploy
./scripts/deploy.sh [staging|production]

## Kluczowe decyzje architektoniczne
- Używamy CQRS dla modułu zamówień -  nie mieszaj command i query handlers
- Cache Redis tylko dla danych które mogą być stale -  nigdy dla danych finansowych
- Wszystkie zewnętrzne API calls przez dedicated service layer w /services/
- Baza danych: nie używaj ORM dla raportów -  pisz surowe SQL z pomocą sqlalchemy.text()

## Czego NIE robić
- Nie commituj sekretów -  używaj .env.example
- Nie modyfikuj migracji które są już na produkcji
- Nie dodawaj globalnego state w React -  użyj Zustand store z slice pattern
- Nie używaj `any` w TypeScript -  zawsze zdefiniuj typ

## Kontekst biznesowy
System e-commerce dla B2B. Kluczowe:
- Wielowalutowość (PLN, EUR, USD)
- Ceny netto dla firm, faktury VAT generowane automatycznie
- Terminy płatności 14/30/60 dni -  kluczowe dla modułu fakturowania

Po zapisaniu tego pliku jako CLAUDE.md w głównym katalogu projektu, Claude będzie wczytywał go automatycznie przy każdym starcie sesji.

Krok 3 - Skonfiguruj plik globalny dla wszystkich projektów

Plik globalny (~/.claude/CLAUDE.md) zawiera preferencje które chcesz stosować we wszystkich projektach. Tworzysz go raz - działa zawsze, niezależnie od projektu.

Poniższy kod to przykład pliku globalnego. Ustaw tutaj swoje osobiste preferencje pracy - Claude zastosuje je we wszystkich projektach bez konieczności powtarzania w każdym projekcie:

# Preferencje globalne Claude Code

## Styl kodowania
- Preferuję type hints i explicit types
- Komentarze tylko gdy logika jest nieintuicyjna
- Testy przed implementacją (TDD gdy możliwe)

## Workflow
- Przed dużą zmianą -  pokaż mi plan w punktach
- Zawsze uruchom testy po zmianach
- Przy niejasności -  zapytaj, nie zakładaj

## Języki
- Kod: angielski (zmienne, funkcje, komentarze)
- Komunikacja ze mną: po polsku

Reguła "Przy niejasności - zapytaj, nie zakładaj" jest szczególnie ważna - bez niej Claude może zaimplementować funkcję w zupełnie inny sposób niż myślałeś, a Ty dowiesz się o tym dopiero gdy przejrzysz diff.

/init, # i /memory — twórz i aktualizuj plik bez wysiłku

Nie musisz pisać CLAUDE.md od zera. Claude Code ma trzy skróty, które robią większość roboty:

• /init — w nowym projekcie Claude skanuje repozytorium (strukturę, zależności, skrypty) i generuje startowy CLAUDE.md. Ty tylko go dopracowujesz.
• # na początku wiadomości — to, co napiszesz po krzyżyku, Claude dopisze jako regułę do pamięci, pytając tylko, do którego pliku (projektowego czy globalnego). Idealne, gdy w trakcie pracy pomyślisz „to warto zapamiętać”.
• /memory — otwiera pliki pamięci w edytorze, żebyś mógł je przejrzeć i posprzątać.

Importy @ścieżka — trzymaj plik krótki, szczegóły osobno

CLAUDE.md ma być zwięzły, ale czasem chcesz, żeby Claude znał szczegóły z innego pliku — opis architektury, styleguide, kontrakty API. Zamiast kopiować ich treść, zaimportuj je znakiem @:

# Projekt: Sklep B2B

Szczegóły w osobnych plikach:
@docs/architektura.md
@docs/api-kontrakty.md
@CONTRIBUTING.md

Przy @ścieżka Claude wciąga zawartość wskazanego pliku tak, jakby była częścią CLAUDE.md. Ścieżki mogą być względne (@docs/architektura.md) albo z katalogu domowego (@~/.claude/styl.md). Jeden krótki CLAUDE.md spina rozproszoną dokumentację i nie dubluje jej.

Co jeszcze możesz umieścić w CLAUDE.md

• Schematy bazy danych - kluczowe tabele i relacje (nie cały schemat - to za dużo tokenów)
• API endpoints - lista najważniejszych endpoints i ich kontrakt
• Znane problemy - bugi które są świadome i nie należy ich "naprawiać"
• Zewnętrzne zależności - jak działają integracje z zewnętrznymi systemami
• Osoby odpowiedzialne - kto zna które moduły (gdy Claude ma pytania)

Wersjonuj CLAUDE.md jak kod

CLAUDE.md to nie prywatna notatka — to część projektu. Commituj go do repozytorium, żeby każdy w zespole (i każdy nowy programista) dostał te same reguły automatycznie. Gdy zmieniacie konwencję, poprawka w CLAUDE.md przechodzi przez code review tak samo jak zmiana w kodzie.

• Trzymaj w gicie — wspólne reguły to wspólny plik. Nowy w zespole klonuje repo i Claude od razu zna konwencje.
• Recenzuj zmiany — „dopiszmy regułę X” to pull request, nie ustna umowa. Łatwiej wyłapać sprzeczne wytyczne.
• Prywatne rzeczy osobno — preferencje jednej osoby idą do importowanego, gitignorowanego pliku, nie do wspólnego CLAUDE.md.

Traktuj CLAUDE.md jak żywy dokument

Najlepsze pliki CLAUDE.md nie powstają w jednym posiedzeniu — rosną z czasem. Zasada jest prosta: ilekroć Claude zrobi coś nie tak, nie poprawiaj tylko tej jednej rzeczy — dopisz regułę, żeby nie zrobił tego ponownie.

• Użył print() zamiast loggera? --> dopisz „logowanie tylko przez utils/log.py”.
• Zrefaktorował publiczne API, którego nie wolno ruszać? --> dopisz to do sekcji „Czego NIE robić”.
• Pomylił środowiska? --> opisz, jak nazywają się Twoje gałęzie i środowiska.

Po kilku tygodniach taki plik staje się skondensowaną wiedzą o projekcie, a liczba poprawek, które nanosisz ręcznie, wyraźnie spada. To najtańsza inwestycja w jakość pracy z agentem.

Częste błędy przy pisaniu CLAUDE.md

Trzy błędy które popełniają prawie wszyscy na początku:

• Błąd 1: Za długi plik
  CLAUDE.md jest wczytywany do kontekstu przy każdym wywołaniu. Powyżej 2 000 tokenów zaczynasz tracić miejsce na właściwe zadanie. Bądź zwięzły - jedna linia zamiast trzech zdań. Jeśli masz dużo do opisania, użyj zagnieżdżonych CLAUDE.md w podkatalogach.
• Błąd 2: Nieaktualny plik
  CLAUDE.md który kłamie jest gorszy niż brak. Jeśli napiszesz "używamy PostgreSQL 14" a potem zmigrujesz do 15, Claude będzie działać na podstawie błędnych informacji. Aktualizuj plik przy każdej ważnej zmianie technicznej - warto dodać go do listy rzeczy do zrobienia przy merge request.
• Błąd 3: Za ogólny opis
  "Używamy Pythona" jest bezużyteczne. "Używamy Python 3.11, FastAPI 0.104, async/await wszędzie, pydantic v2 dla walidacji, alembic dla migracji" jest użyteczne. Im bardziej szczegółowy opis technologii, tym lepiej Claude dopasujesz sugestie do Twojego stosu.

Krok 4 - Weryfikuj czy CLAUDE.md działa

Po napisaniu CLAUDE.md zapytaj Claude Code: "Opisz architekturę tego projektu". Jeśli odpowiedź odzwierciedla Twój CLAUDE.md - agent go czyta i rozumie. Jeśli odpowiedź jest ogólna lub błędna - sprawdź czy plik jest we właściwym miejscu i czy składnia Markdown jest poprawna.

Możesz też zadać bardziej szczegółowe pytania: "Jak w tym projekcie uruchamiamy testy?" albo "Jakich rzeczy nie powinienem robić w tym projekcie?". Claude powinien odpowiedzieć dokładnie tym, co wpisałeś w plik.

Gdy masz dobrze napisany CLAUDE.md, każda sesja z Claude Code zaczyna się od stanu "Claude zna Twój projekt" - nie od tłumaczenia podstaw. Oszczędzasz czas, Claude popełnia mniej błędów, a Ty masz więcej przestrzeni na rzeczy które naprawdę wymagają Twojej uwagi. To jedna godzina pracy która zwraca się przy pierwszym użyciu.