Zainicjuj swój pierwszy projekt

Naucz się konfigurować Claude Code dla maksymalnej efektywności w swoim projekcie. Ten przewodnik obejmuje tworzenie plików CLAUDE.md, zarządzanie pamięcią projektu i ustanawianie jasnego kontekstu dla rozwoju wspomaganego przez AI.

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
• 🔄 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

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 14 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

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, organizuj wspomnienia z importami:

CLAUDE.md z importami

# Główna konfiguracja projektu

## Przegląd architektury
Wysokopoziomowy projekt systemu i zasady...

## Importuj konkretne konfiguracje
- Frontend: ./frontend/CLAUDE.md
- Backend: ./backend/CLAUDE.md
- Infrastruktura: ./infra/CLAUDE.md
- Testowanie: ./tests/CLAUDE.md

Notatka

Claude Code 4.0+ automatycznie odkrywa i ładuje pliki CLAUDE.md w katalogach nadrzędnych i podrzędnych gdy są istotne.

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

Następne kroki

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.