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 trenerem? Szkolenie Claude Code z terminem gwarantowanym →

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.

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)

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.