Zainicjuj swój pierwszy projekt

Plik CLAUDE.md to trwały brief projektu, który Claude Code automatycznie ładuje na początku każdej sesji, ujmując konwencje stosu, polecenia build i test oraz wzorce, które inaczej trzeba by tłumaczyć za każdym razem. Mieści się w hierarchii pamięci: projekt, użytkownik i pliki modularne, wspiera importy @path do dzielenia dużych plików oraz aktualizuje się przez workflow /init, /memory i #.

Wrzucasz Claude Code do swojego repo i prosisz o drobną zmianę. Wybiera zły menedżer pakietów, generuje komponent ignorujący twoje konwencje katalogów i znów dopytuje, którego runnera testów używasz — po raz kolejny. Z modelem nie ma nic nie tak; on po prostu nie ma pojęcia, co znaczy “sposób, w jaki robimy rzeczy tutaj”. Plik CLAUDE.md to naprawia: to trwały brief projektu, który Claude czyta na początku każdej sesji, więc przestaje zgadywać i zaczyna dopasowywać się do twojego stosu.

Co wyniesiesz z konfiguracji CLAUDE.md

• CLAUDE.md, który ujmuje twój stos, polecenia build/test/lint i konwencje, które Claude ciągle łamie
• Hierarchię pamięci (projekt, użytkownik i modularne .claude/rules/) oraz kiedy używać której
• Prawdziwą składnię importów @path do podzielenia rozdętego CLAUDE.md na skoncentrowane pliki
• Workflow /init, /memory i # do utrzymywania pamięci na bieżąco podczas kodowania
• Prompty do skopiowania, które sprawią, że Claude sam napisze i przerefaktoruje swoje pliki pamięci

Zrozumienie plików CLAUDE.md

Czym jest CLAUDE.md?

CLAUDE.md to specjalny plik, który Claude Code automatycznie ładuje do kontekstu. Pomyśl o nim jak o trwałej pamięci, która pomaga Claude zrozumieć specyficzne potrzeby twojego projektu, standardy kodowania i powszechne przepływy pracy.

Kluczowe korzyści:

• Trwały kontekst między sesjami
• Wiedza zespołowa do udostępniania, zapisana w kontroli wersji
• Automatycznie ładowany przy uruchamianiu
• Hierarchiczny dla złożonych projektów

Szybki start

1. Przejdź do swojego projektu

   cd your-awesome-project

2. Uruchom Claude Code

   claude

3. Zainicjuj CLAUDE.md

   /init

4. Przejrzyj i dostosuj Claude przeanalizuje twój projekt i wygeneruje dostosowany plik CLAUDE.md

/init daje ci punkt wyjścia, ale bywa generyczny. Najszybszy sposób, by uzyskać CLAUDE.md faktycznie odzwierciedlający twój projekt, to kazać Claude przeprowadzić audyt repo i napisać go na podstawie dowodów:

Wskazówka

Prompt do skopiowania, aby napisać CLAUDE.md na podstawie twojego prawdziwego repo:

Read package.json, the test/lint config, and the top-level directories.
Then draft a CLAUDE.md for this project that captures:

1. The stack and runtime (frameworks, language version, package manager)
2. The exact build, test, lint, and type-check commands (copy them verbatim
   from package.json scripts -- do NOT invent commands you cannot verify)
3. The 3-5 conventions you can infer from the existing code (file layout,
   naming, component/module patterns)
4. Any gotchas you notice (generated files, required env vars, monorepo quirks)

Keep it under 150 lines. Flag anything you are unsure about instead of guessing.

Struktura pliku CLAUDE.md

Podstawowy szablon

CLAUDE.md

# Przegląd projektu
Krótki opis tego, co robi ten projekt i jaki jest jego główny cel.

# Architektura
- Frontend: React z TypeScript
- Backend: Node.js z Express
- Baza danych: PostgreSQL
- Zarządzanie stanem: Redux Toolkit

# Kluczowe katalogi
- `src/`: Główny kod źródłowy
- `src/components/`: Komponenty React
- `src/api/`: Kod klienta API
- `src/utils/`: Funkcje narzędziowe
- `tests/`: Pliki testów

# Powszechne polecenia
- `npm run dev`: Uruchom serwer deweloperski
- `npm run build`: Zbuduj dla produkcji
- `npm test`: Uruchom pakiet testów
- `npm run lint`: Uruchom linter
- `npm run type-check`: Sprawdź typy TypeScript

# Styl kodu
- Używaj TypeScript dla wszystkich nowych plików
- Preferuj komponenty funkcyjne z hookami
- Używaj opisowych nazw zmiennych
- Pisz testy dla nowych funkcji
- Podążaj za istniejącymi wzorcami w kodzie

# Ważne uwagi
- Zmienne środowiskowe są w `.env.example`
- Zawsze uruchamiaj testy przed commitowaniem
- Używaj gałęzi funkcjonalnych do nowej pracy
- Dokumentacja API w `/docs/api.md`

# Aktualne cele sprintu
- [ ] Zaimplementuj uwierzytelnianie użytkownika
- [ ] Dodaj walidację danych do formularzy
- [ ] Popraw obsługę błędów

Zaawansowany przykład

Złożony przykład CLAUDE.md

# Platforma e-commerce

## Kontekst projektu
Wielodostępna platforma e-commerce SaaS obsługująca operacje B2B i B2C.
Zbudowana z architekturą mikrousług, wdrożona na AWS ECS.

## Stos technologiczny
### Frontend
- Next.js 16 z App Router
- TypeScript w trybie strict
- Tailwind CSS + shadcn/ui
- React Query do pobierania danych
- Zustand do zarządzania stanem

### Usługi backendowe
- API Gateway: Kong
- Usługa użytkowników: Node.js + Express + TypeORM
- Usługa produktów: Go + Gin + GORM
- Usługa zamówień: Python + FastAPI + SQLAlchemy
- Usługa płatności: Java + Spring Boot

### Infrastruktura
- AWS ECS do orkiestracji kontenerów
- PostgreSQL (RDS) dla danych relacyjnych
- Redis do cachowania i sesji
- ElasticSearch do wyszukiwania produktów
- S3 do przechowywania mediów

## Przepływ pracy deweloperskiej

### Rozwój lokalny
```bash
# Uruchom wszystkie usługi
docker-compose up

# Uruchom konkretną usługę
docker-compose up user-service

# Uruchom migracje
npm run migrate:up

# Zasiej dane testowe
npm run seed:dev
```

### Strategia testowania
- Testy jednostkowe: Jest dla JS/TS, Go test, pytest
- Testy integracyjne: Supertest + Docker
- Testy E2E: Playwright
- Min. pokrycie: 80% dla nowego kodu

### Przepływ pracy Git
1. Utwórz gałąź funkcjonalną z develop
2. Format nazwy: feature/JIRA-123-krotki-opis
3. Format commit: "type(scope): opis"
4. Otwórz PR przeciwko develop
5. Wymagaj 2 zatwierdzeń + przechodzącego CI

## Wzorce API

### Punkty końcowe REST
- GET /api/v1/resources - Lista z paginacją
- GET /api/v1/resources/:id - Pojedynczy zasób
- POST /api/v1/resources - Utwórz nowy
- PUT /api/v1/resources/:id - Pełna aktualizacja
- PATCH /api/v1/resources/:id - Częściowa aktualizacja
- DELETE /api/v1/resources/:id - Usuwanie miękkie

### Powszechne nagłówki
- Authorization: Bearer {token}
- X-Tenant-ID: {tenantId}
- X-Request-ID: {uuid}

## Kwestie bezpieczeństwa
- Wszystkie punkty końcowe wymagają uwierzytelniania oprócz /health
- Używaj zapytań sparametryzowanych aby zapobiec wstrzyknięciu SQL
- Waliduj wszystkie wejścia schematami Joi/Zod
- Ograniczenie prędkości: 100 żąd/min na użytkownika
- CORS skonfigurowany tylko dla konkretnych domen

## Wytyczne wydajności
- Zapytania do bazy danych muszą używać indeksów
- Implementuj paginację dla punktów końcowych list
- Cachuj żądania GET w Redis (5 min TTL)
- Ładuj leniwie obrazy i komponenty
- Budżet rozmiaru pakietu: 200KB dla początkowego ładowania

## Znane problemy
- Webhooki płatności czasem przekraczają limit czasu - logika ponawiania w miejscu
- Indeksowanie wyszukiwania ma 2-3 minutowe opóźnienie
- Niektóre starsze punkty końcowe używają camelCase zamiast snake_case

## Monitorowanie i debugowanie
- Logi: CloudWatch (wyszukaj po X-Request-ID)
- APM: DataDog (user-service.datadog.dashboard)
- Błędy: Sentry (filtruj po usłudze + env)
- Lokalne debugowanie: Patrz /docs/debugging.md

Hierarchia pamięci

Claude Code obsługuje wiele lokalizacji pamięci dla różnych zakresów:

Pamięć projektu

Lokalizacja: ./CLAUDE.md

Instrukcje zespołowe współdzielone w kontroli wersji:

• Decyzje architektoniczne
• Standardy kodowania
• Polecenia budowania
• Wzorce API

# Edytuj podczas sesji
/memory

# Lub dodaj szybkie notatki
# Zawsze używaj async/await zamiast callbacków

Pamięć użytkownika

Lokalizacja: ~/.claude/CLAUDE.md

Osobiste preferencje dla wszystkich projektów:

• Twój styl kodowania
• Preferowane narzędzia
• Osobiste skróty
• Ustawienia IDE

# Moje preferencje
- Używaj 2-spacjowego wcięcia
- Preferuj const nad let
- Zawsze destrukturyzuj importy
- Formatuj przy zapisywaniu

Pamięć modułu

Lokalizacja: ./frontend/CLAUDE.md, ./backend/CLAUDE.md

Kontekst specyficzny dla modułu w podkatalogach:

• Wzorce komponentów
• Dokumentacja usług
• Zależności modułu
• Lokalne polecenia

Modularne reguły

Lokalizacja: ./.claude/rules/*.md

Reguły dotyczące konkretnych tematów, zapisane w kontroli wersji, które utrzymują główny CLAUDE.md szczupłym. Każdy plik może wskazać ścieżki, do których się stosuje, za pomocą pola paths we frontmatterze — listy YAML wzorców glob:

---
paths:
  - "src/app/api/**"
---
- Validate every request body with a Zod schema
- Return errors as { error: string } with the right status code

Używaj ich dla wytycznych specyficznych dla języka lub obszaru, aby ładowały się tylko wtedy, gdy Claude dotyka pasujących plików. Reguły bez pola paths ładują się bezwarunkowo.

Gdy ciągle łapiesz Claude na łamaniu tej samej konwencji w jednym obszarze kodu, zakoduj ją jako regułę o określonym zakresie, zamiast się powtarzać:

Wskazówka

Prompt do skopiowania, aby dodać regułę zależną od ścieżki w .claude/rules/:

Create a rule file at .claude/rules/api.md that applies to src/app/api/**.

Add frontmatter with a `paths` field (a YAML list of glob patterns), then list
the conventions every API route in this repo must follow -- infer them by reading
two or three existing routes first (auth handling, validation library, error
shape, status codes). Only include rules you can back up with existing code.

Dynamiczne aktualizacje pamięci

Używanie klawisza

Najszybszy sposób dodawania wspomnień podczas kodowania:

1. Wpisz # po którym następuje twoja notatka

   # Metoda UserService.authenticate wymaga ważnego tokenu JWT

2. Wybierz lokalizację pamięci Claude poprosi cię o wybranie miejsca zapisu:

   • Pamięć projektu (./CLAUDE.md)
   • Pamięć użytkownika (~/.claude/CLAUDE.md)

3. Kontynuuj pracę Pamięć jest natychmiast dostępna

Powszechne użycia klawisza

Szybkie wzorce pamięci

# Polecenie budowania to 'npm run build:prod' dla produkcji

# Klucze API są w Vault, nie w plikach .env

# Zawsze uruchamiaj migracje przed uruchomieniem aplikacji

# Funkcja calculateTax ma znany błąd z liczbami dziesiętnymi

# Preferuj kompozycję nad dziedziczeniem w tym kodzie

# Skontaktuj się z @john w sprawie zmian schematu bazy danych

Importy CLAUDE.md

Dla dużych projektów utrzymuj główny CLAUDE.md mały i wciągaj skoncentrowane pliki za pomocą dyrektywy @path/to/import. Zwykłe listy punktów z gołymi ścieżkami nie robią nic — tylko prefiks @ faktycznie importuje plik.

CLAUDE.md z importami @path

# Główna konfiguracja projektu

Zobacz @README.md, aby poznać przegląd projektu, oraz @package.json, aby zobaczyć dostępne polecenia.

## Architektura
Wysokopoziomowy projekt systemu i zasady znajdują się tutaj...

## Szczegółowe konwencje
- Konwencje frontendu @frontend/CLAUDE.md
- Konwencje backendu @backend/CLAUDE.md
- Runbooki infrastruktury @infra/CLAUDE.md
- Reguły testowania @tests/CLAUDE.md

Importy akceptują zarówno ścieżki względne, jak i bezwzględne. Ścieżki względne rozwiązują się względem pliku, który dokonuje importu, a nie twojego katalogu roboczego, a dyrektywy @ wewnątrz ogrodzonych bloków kodu są ignorowane, więc przykłady takie jak ten pozostają bezczynne. Dla osobistych instrukcji, które chcesz współdzielić między worktree’ami gita, importuj z katalogu domowego (na przykład @~/.claude/my-conventions.md).

Notatka

Rzadko potrzebujesz importów tylko po to, by dotrzeć do podkatalogów. Claude Code ładuje w całości każdy CLAUDE.md w hierarchii katalogów powyżej twojego katalogu roboczego przy starcie, a pliki CLAUDE.md w katalogach podrzędnych ładuje na żądanie, gdy Claude po raz pierwszy czyta w nich plik. Używaj importów do komponowania skoncentrowanych plików, a nie do wymuszania działania odkrywania.

Gdy główny CLAUDE.md przekroczy kilkaset linii, pozwól Claude zająć się podziałem za ciebie:

Wskazówka

Prompt do skopiowania, aby przerefaktorować rozdęty CLAUDE.md na importy:

Our CLAUDE.md has grown too long. Refactor it without losing any rules:

1. Group the content into themes (architecture, frontend, backend, testing,
   conventions).
2. Move each group into its own file under the matching directory, or into
   .claude/rules/ when it is a cross-cutting rule.
3. Replace the moved sections in the root CLAUDE.md with @path imports.
4. Keep the root file as a short index: project overview + the imports.

Show me the new file tree and the rewritten root CLAUDE.md before you write anything.

Przykłady specyficzne dla projektów

Projekt React/Next.js

# Aplikacja e-commerce Next.js

## Struktura projektu
- App Router (nie Pages Router)
- Komponenty serwera domyślnie
- Komponenty klienta tylko gdy potrzebne
- Trasy API w /app/api

## Zarządzanie stanem
- Stan serwera: React Query + Komponenty serwera
- Stan klienta: Zustand dla globalnego, useState dla lokalnego
- Stan formularza: React Hook Form + Zod

## Podejście do stylowania
- Tailwind CSS dla narzędzi
- Moduły CSS dla złożonych komponentów
- Framer Motion dla animacji
- Projekt responsywny-pierwsz

## Wzorce komponentów
```tsx
// Preferuj ten wzorzec dla komponentów
export function ComponentName({ prop1, prop2 }: Props) {
// Hooki na górze
// Wczesne zwroty dla przypadków skrajnych
// Główne renderowanie
}
```

## Pobieranie danych
- Używaj komponentów serwera dla początkowych danych
- React Query dla aktualizacji po stronie klienta
- Loading.tsx dla granic suspense
- Error.tsx dla granic błędów

Projekt Python/Django

# Django REST API

## Standardy projektu
- Python 3.11+ z podpowiedziami typów
- Black do formatowania (długość linii 88)
- isort dla importów
- pytest do testowania

## Wzorce Django
- Widoki oparte na klasach dla CRUD
- Widoki oparte na funkcjach dla złożonej logiki
- Serializery obsługują całą walidację
- Menedżerowie dla złożonych zapytań

## Wytyczne bazy danych
- Zawsze używaj migracji
- Nigdy nie edytuj migracji po wdrożeniu
- Używaj select_related/prefetch_related
- Indeksuj klucze obce i pola filtrów

## Konwencje API
- URL-e RESTful (/api/v1/users/)
- camelCase dla JSON (użyj djangorestframework-camel-case)
- Paginacja na wszystkich punktach końcowych list
- Standardowy format błędów

## Wymagania testowe
- Test jednostkowy całej logiki biznesowej
- Test integracyjny wszystkich punktów końcowych
- Używaj factory_boy dla danych testowych
- Mockuj usługi zewnętrzne

DevOps/Infrastruktura

# Infrastruktura jako kod

## Konwencje Terraform
- Moduły w katalogu /modules
- Środowiska w /environments
- Stan w S3 z blokadą DynamoDB
- Zawsze uruchamiaj plan przed apply

## Wzorce Kubernetes
- Jedna przestrzeń nazw na środowisko
- ConfigMaps dla konfiguracji
- Secrets dla wrażliwych danych
- HPA dla autoskalowania
- PDB dla dostępności

## Pipeline CI/CD
1. Lint (terraform fmt -check)
2. Walidacja (terraform validate)
3. Skan bezpieczeństwa (tfsec)
4. Plan (zapisz plik planu)
5. Ręczne zatwierdzenie dla prod
6. Apply

## Konfiguracja monitorowania
- Prometheus dla metryk
- Grafana dla wizualizacji
- Alert przy naruszeniach SLI
- Runbooki w /docs/runbooks

Najlepsze praktyki

Najlepsze praktyki CLAUDE.md

1. Bądź konkretny: “Używaj 2-spacjowego wcięcia” nie “formatuj ładnie”
2. Dołączaj przykłady: Pokaż rzeczywiste wzorce kodu, które chcesz stosować
3. Bądź aktualny: Aktualizuj w miarę ewolucji projektu
4. Dokumentuj pułapki: Znane problemy, obejścia i przypadki brzegowe
5. Linkuj zasoby: Referencje do dokumentacji, wiki i narzędzi
6. Używaj struktury: Organizuj z jasnymi nagłówkami i sekcjami
7. Utrzymuj skanowalność: Używaj punktów i bloków kodu
8. Kontrola wersji: Śledź zmiany aby zrozumieć ewolucję

Optymalizacja dla dużych baz kodu

Organizacja hierarchiczna

projekt/
├── CLAUDE.md                 # Kontekst główny
├── frontend/
│   ├── CLAUDE.md            # Specyficzny dla frontendu
│   └── components/
│       └── CLAUDE.md        # Wzorce komponentów
├── backend/
│   ├── CLAUDE.md            # Specyficzny dla backendu
│   └── services/
│       └── CLAUDE.md        # Wzorce usług
└── infrastructure/
    └── CLAUDE.md            # Kontekst DevOps

Efektywność tokenów

Zarządzanie rozmiarem kontekstu

Pliki CLAUDE.md zużywają tokeny z okna kontekstowego Claude. Utrzymuj je skoncentrowane:

• Staraj się o 200-500 linii na plik
• Używaj importów dla organizacji modularnej
• Usuwaj przestarzałe informacje
• Skupiaj się na wzorcach, nie wyczerpujących listach

Współpraca zespołowa

Ustanawianie standardów zespołowych

1. Utwórz początkowy CLAUDE.md razem

   • Przeprowadź sesję zespołową aby uzgodnić zawartość
   • Udokumentuj istniejące konwencje
   • Wyjaśnij niejednoznaczne wzorce

2. Przeglądaj w pull requestach

   • Traktuj zmiany CLAUDE.md jak kod
   • Wymagaj zatwierdzenia zespołu dla aktualizacji
   • Prowadź historię dlaczego zmiany zostały wprowadzone

3. Regularna konserwacja

   • Przeglądaj kwartalnie
   • Usuwaj przestarzałe informacje
   • Dodawaj nowe wzorce w miarę ich pojawiania się

4. Narzędzie onboardingu

   • Nowi deweloperzy czytają CLAUDE.md jako pierwsi
   • Używaj go podczas przeglądów kodu
   • Referencuj go w dyskusjach

Rozwiązywanie problemów

CLAUDE.md się nie ładuje

Objawy: Claude nie wydaje się świadomy kontekstu twojego projektu

Rozwiązania:

1. Sprawdź czy nazwa pliku to dokładnie CLAUDE.md (wrażliwy na wielkość liter)
2. Sprawdź lokalizację pliku (główny katalog projektu)
3. Uruchom ponownie sesję Claude Code
4. Uruchom /memory aby zweryfikować zawartość

Konfliktujące instrukcje

Objawy: Claude podąża za starymi wzorcami pomimo aktualizacji

Rozwiązania:

1. Wyczyść konwersację z /clear
2. Sprawdź czy są wielokrotne pliki CLAUDE.md
3. Sprawdź czy ścieżki importów są poprawne
4. Używaj bardziej konkretnego języka (“ZAWSZE”, “NIGDY”)

Problemy z limitem tokenów

Objawy: Claude wspomina o limitach okna kontekstowego

Rozwiązania:

1. Podziel duże CLAUDE.md na moduły
2. Usuń rozwlekłe sekcje
3. Używaj zwięzłych punktów
4. Skupiaj się na wzorcach nad przykładami

Dokąd pójść po skonfigurowaniu CLAUDE.md

Integracja IDE Połącz Claude Code z VS Code, JetBrains i innymi edytorami

Przepływ pracy deweloperskiej Naucz się optymalnego przepływu pracy od planowania do implementacji

Szybka referencja

Polecenie	Cel
/init	Wygeneruj początkowy CLAUDE.md
/memory	Edytuj pliki pamięci
#	Dodaj szybką notatkę pamięci
/clear	Wyczyść kontekst konwersacji
@CLAUDE.md	Referencja pamięci w promptach

Pamiętaj: Dobrze stworzony plik CLAUDE.md to jak posiadanie idealnej dokumentacji, która nigdy się nie gubi i jest zawsze dostępna dokładnie wtedy, gdy Claude jej potrzebuje.