Zainicjuj swój pierwszy projekt

Plik CLAUDE.md jest trwałym briefem projektu ładowanym przez Claude Code na początku sesji. Zapisuje zweryfikowane polecenia build i test, konwencje oraz granice bezpieczeństwa, których agent nie powinien odgadywać. Może działać na poziomie projektu i użytkownika, odsyłać do modularnych instrukcji oraz być przeglądany i poprawiany razem z kodem.

Ten przewodnik prowadzi przez konfigurację Claude Code w nowym lub istniejącym repozytorium: utworzenie trwałego pliku pamięci, reguł modularnych i weryfikację kontekstu między sesjami. Pełną orkiestrację cyklu opisuje etap Design.

Gdy wrzucasz Claude Code do repozytorium bez kontekstu i prosisz o drobną zmianę, model może wybrać zły menedżer pakietów, wygenerować komponent ignorujący konwencje katalogów lub ponownie pytać o runner testów. Plik CLAUDE.md eliminuje zgadywanie: służy jako trwały brief projektu odczytywany na początku każdej sesji, wymuszając przestrzeganie standardów zespołu.

Rezultat konfiguracji

• Skonfigurujesz plik CLAUDE.md zawierający opis stosu oraz polecenia build, test i lint.
• Wykorzystasz hierarchię pamięci (projekt, użytkownik oraz modularne .claude/rules/).
• Podzielisz duży plik CLAUDE.md na mniejsze moduły za pomocą składni importów @path.
• Utrzymasz pamięć na bieżąco podczas pracy dzięki poleceniom /init, /memory i #.
• Zastosujesz prompty zlecające Claude audyt repozytorium i wygenerowanie plików reguł.

Rola pliku CLAUDE.md

Czym jest CLAUDE.md?

CLAUDE.md to plik Markdown, który Claude Code ładuje do kontekstu przy starcie sesji. Działa jako trwała pamięć, pomagając modelowi zrozumieć wymagania projektu, standardy kodowania i typowe procedury.

Kluczowe korzyści:

• Zapewnia trwały kontekst w kolejnych sesjach.
• Przechowuje wiedzę zespołu w systemie kontroli wersji.
• Ładuje się automatycznie przy uruchomieniu.
• Umożliwia hierarchiczną organizację w złożonych repozytoriach.

Szybki start

Aby zainicjalizować Claude Code w projekcie, wykonaj następujące kroki:

1. Przejdź do katalogu projektu:

   cd REPOSITORY_PATH

   Zastąp REPOSITORY_PATH ścieżką do swojego lokalnego repozytorium git.

2. Uruchom Claude Code:

   claude

3. Zainicjalizuj plik CLAUDE.md:

   /init

4. Przejrzyj i dostosuj wygenerowaną konfigurację. Claude przeanalizuje projekt i wygeneruje wstępny plik CLAUDE.md.

Polecenie /init tworzy szablon początkowy, jednak precyzyjniejsze instrukcje uzyskasz, zlecając audyt kodu. Aby wygenerować CLAUDE.md na podstawie faktycznego repozytorium, uruchom w Claude Code następujący prompt:

Wskazówka

Prompt do wygenerowania CLAUDE.md na podstawie repozytorium:

Read package.json, the test and lint configurations, 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 or 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

Poniższy szablon stanowi punkt wyjścia dla projektów o małej i średniej skali:

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

Dla złożonych systemów wielousługowych uwzględnij przepływy uruchomieniowe, wzorce API i konfigurację obserwowalności:

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 wielopoziomowe zakresy pamięci pozwalające na uporządkowanie instrukcji:

Pamięć projektu

Lokalizacja: ./CLAUDE.md

Zawiera instrukcje zespołowe śledzone w kontroli wersji:

• Decyzje architektoniczne i wzorce frameworka
• Standardy kodowania i reguły formatowania
• Polecenia budowania, testów i weryfikacji typów
• Wzorce API i obsługi błędów

# Edytuj plik pamięci podczas aktywnej sesji
/memory

# Zapisz szybką notatkę
# Always use async/await instead of callbacks

Pamięć użytkownika

Lokalizacja: ~/.claude/CLAUDE.md

Zawiera osobiste preferencje programisty stosowane we wszystkich projektach:

• Indywidualny styl formatowania
• Preferowane narzędzia terminalowe
• Skróty klawiszowe
• Nadpisania lokalnego środowiska

# 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

Zawiera kontekst specyficzny dla danego podkatalogu:

• Wzorce komponentów i bibliotek UI
• Architektura usług i konwencje bazy danych
• Zależności modułu i pakiety wewnętrzne
• Lokalne polecenia uruchamiania testów

Modularne reguły

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

Zawiera reguły tematyczne śledzone w kontroli wersji, które odciążają główny CLAUDE.md. Każdy plik może zdefiniować dopasowanie ścieżek w polu paths we frontmatterze za pomocą wzorców glob:

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

Reguły warunkowe ładują się wyłącznie wtedy, gdy Claude edytuje pasujące pliki. Reguły bez pola paths są ładowane bezwarunkowo.

Gdy zauważysz, że Claude regularnie narusza konwencje w określonym katalogu, dodaj regułę modularną w .claude/rules/:

Wskazówka

Prompt do utworzenia reguły warunkowej 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

Aktualizacja pamięci za pomocą klawisza

Aby dodać notatkę do pamięci podczas aktywnej sesji:

1. Wpisz #, a następnie treść reguły:

   # Metoda UserService.authenticate wymaga ważnego tokenu JWT

2. Wybierz miejsce zapisu:

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

3. Kontynuuj pracę. Zapisana instrukcja staje się natychmiast aktywna w bieżącej sesji.

Powszechne wzorce 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 @lead w sprawie zmian schematu bazy danych

Import modułów za pomocą @path

W dużych projektach zachowaj zwięzłość głównego pliku CLAUDE.md, importując dedykowane pliki reguł za pomocą dyrektywy @path/to/file. Zwykłe listy wypunktowane nie ładują plików; jedynie prefiks @ aktywuje import.

Poniższy przykład przedstawia importowanie reguł z podkatalogów:

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ą ścieżki względne i bezwzględne. Ścieżki względne są rozwiązywane względem pliku zawierającego deklarację importu. Dyrektywy @ wewnątrz bloków kodu są ignorowane. Aby współdzielić reguły między różnymi worktree gita, importuj pliki z katalogu domowego (na przykład @~/.claude/my-conventions.md).

Notatka

Claude Code ładuje przy starcie wszystkie pliki CLAUDE.md w górę hierarchii katalogów od bieżącego folderu. Pliki w katalogach podrzędnych ładuje na żądanie, gdy modyfikowany jest w nich plik. Używaj importów do modularnej kompozycji reguł, a nie do wymuszania indeksowania.

Gdy główny plik CLAUDE.md przekroczy 300 linii, zrefaktoryzuj go za pomocą poniższego promptu:

Wskazówka

Prompt do refaktoryzacji dużego 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 plus the imports.

Show me the proposed file tree and rewritten root CLAUDE.md before writing files.

Konfiguracje specyficzne dla projektów

Projekt React i Next.js

Poniższa konfiguracja przedstawia standardy dla aplikacji Next.js App Router:

# 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
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 i Django

Poniższa konfiguracja definiuje standardy dla Django REST Framework:

# 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

Infrastruktura jako kod

Poniższa konfiguracja definiuje standardy dla Terraform i Kubernetes:

# 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

Dobre praktyki

Stosuj poniższe zasady podczas tworzenia CLAUDE.md:

1. Stawiaj na precyzję: Pisz “Używaj 2-spacjowych wcięć” zamiast “Dbaj o formatowanie”.
2. Dodawaj wzorce kodu: Pokazuj zwięzłe przykłady implementacji pożądanych wzorców.
3. Aktualizuj polecenia: Wprowadzaj zmiany w pliku, gdy zmieniają się skrypty lintera lub runner testów.
4. Opisuj znane ograniczenia: Zapisuj obejścia problematycznych testów i specyfikę środowiska.
5. Odwołuj się do dokumentacji: Linkuj przewodniki architektoniczne i standardy API.
6. Dbaj o hierarchię: Używaj jednoznacznych nagłówków i list punktowanych.
7. Commituj pliki pamięci: Śledź zmiany pamięci w gicie równolegle ze zmianami kodu.

Optymalizacja dla dużych repozytoriów

Organizacja hierarchiczna

W dużych repozytoriach i monorepo umieszczaj pliki CLAUDE.md w logicznych granicach modułów:

projekt/
├── CLAUDE.md                 # Kontekst główny i polecenia globalne
├── frontend/
│   ├── CLAUDE.md            # Wzorce frontendu i biblioteki UI
│   └── components/
│       └── CLAUDE.md        # Konwencje komponentów
├── backend/
│   ├── CLAUDE.md            # Architektura backendu i modele
│   └── services/
│       └── CLAUDE.md        # Wzorce mikrousług
└── infrastructure/
    └── CLAUDE.md            # Runbooki wdrożeń i IaC

Efektywność tokenów

Zarządzanie rozmiarem kontekstu

Pliki CLAUDE.md zużywają tokeny z okna kontekstowego modelu. Aby zachować przestrzeń na operacje:

• Ogranicz objętość pliku do 150-300 linii.
• Używaj importów @path do tematycznego podziału reguł.
• Usuwaj nieaktualne polecenia i przestarzałe wytyczne.
• Koncentruj się na twardych ograniczeniach zamiast opisów narracyjnych.

Standardy współpracy zespołowej

Ustalenie reguł zespołu

1. Wspólnie stwórzcie wersję początkową: Ustalcie z zespołem kluczowe polecenia weryfikacji i standardy stylu.
2. Weryfikujcie zmiany w pull requestach: Wymagajcie code review dla zmian w CLAUDE.md oraz .claude/rules/.
3. Prowadźcie cykliczny przegląd: Co kwartał czyśćcie pliki z nieaktualnych instrukcji.
4. Wykorzystujcie plik w onboardingu: Wdrażajcie nowych programistów, opierając się na konwencjach z CLAUDE.md.

Rozwiązywanie typowych problemów

CLAUDE.md się nie ładuje

Objawy: Claude ignoruje konwencje repozytorium i dopytuje o polecenia build.

Rozwiązania:

1. Upewnij się, że nazwa pliku to dokładnie wielkie litery CLAUDE.md.
2. Sprawdź, czy plik znajduje się w głównym katalogu, z którego uruchomiono claude.
3. Zrestartuj sesję.
4. Uruchom /memory, aby sprawdzić załadowaną zawartość.

Sprzeczne instrukcje

Objawy: Claude stosuje przestarzałe reguły pomimo aktualizacji CLAUDE.md.

Rozwiązania:

1. Wykonaj /clear, aby zresetować kontekst aktywnej rozmowy.
2. Sprawdź, czy nie występują sprzeczności między głównym CLAUDE.md, pamięcią użytkownika (~/.claude/CLAUDE.md) a regułami modularnymi.
3. Sprawdź, czy ścieżki w dyrektywach @path wskazują istniejące pliki.
4. Użyj jednoznacznych słów kluczowych “ALWAYS” lub “NEVER” dla rygorystycznych ograniczeń.

Wysokie zużycie limitu tokenów

Objawy: Claude sygnalizuje wysokie zużycie okna kontekstowego na wczesnym etapie sesji.

Rozwiązania:

1. Przenieś szczegółowe instrukcje do plików .claude/rules/*.md z filtrami glob we frontmatterze.
2. Zastąp bloki prozy zwięzłymi punktami.
3. Usuń zbędne przykłady kodu i historyczne komentarze.

Weryfikacja działania konfiguracji

Aby sprawdzić poprawność konfiguracji Claude Code:

1. Uruchom nową sesję:

   claude

2. Sprawdź załadowaną pamięć:

   /memory

   Upewnij się, że główny plik CLAUDE.md oraz reguły modularne widnieją na liście aktywnego kontekstu.

3. Zapytaj Claude o konwencje projektu:

   What command do we use to run our test suite and type checks?

   Sprawdź, czy model odpowie dokładnie poleceniami zapisanymi w CLAUDE.md bez zgadywania.

Kolejne kroki

AI-Native SDLC: Etap 2 - Projekt i specyfikacja Dowiedz się, jak generować formalne specyfikacje spec.md i umiejętności modularne za pomocą Claude Code

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

Przepływ pracy programistycznej Poznaj optymalny proces pracy od planowania do implementacji

Szybka ściągawka

Poniższa tabela zawiera zestawienie najważniejszych poleceń zarządzania pamięcią:

Polecenie	Przeznaczenie
/init	Analizuje repozytorium i generuje początkowy plik CLAUDE.md
/memory	Wyświetla i edytuje aktywne pliki pamięci
#	Zapisuje szybką notatkę do pamięci projektu lub użytkownika
/clear	Czyści historię konwersacji i przeładowuje pliki pamięci
@CLAUDE.md	Jawnie odwołuje się do pliku pamięci w promptach