Inicjalizacja pierwszego projektu

Opanuj sztukę inicjalizacji projektów z Claude Code. Ten przewodnik obejmuje tworzenie skutecznych plików CLAUDE.md, zarządzanie pamięcią projektu, konfigurację serwerów MCP oraz ustanawianie przejrzystego kontekstu dla rozwoju wspomaganego przez AI.

Zrozumienie kontekstu projektu

Co wyróżnia Claude Code

W przeciwieństwie do tradycyjnych narzędzi do kodowania, Claude Code utrzymuje trwałą pamięć między sesjami poprzez pliki CLAUDE.md. Traktuj je jako DNA swojego projektu - mówią Claude wszystko, co musi wiedzieć o twojej bazie kodu, standardach i przepływach pracy.

Kluczowe korzyści:

• Zero powtórzeń - dokumentuj raz, używaj zawsze
• Spójność zespołu - dziel się wiedzą między programistami
• Świadomość kontekstu - Claude rozumie twój projekt dogłębnie
• Ewoluująca pamięć - aktualizuj w miarę rozwoju projektu

System CLAUDE.md

Typy pamięci i hierarchia

Claude Code używa zaawansowanej hierarchii pamięci, która ładuje kontekst na podstawie twojego katalogu roboczego:

Pamięć projektu

Lokalizacja: ./CLAUDE.md

Wspólna baza wiedzy twojego zespołu. Dodaj to do Git, aby wszyscy pracowali z tym samym kontekstem.

# Projekt: Platforma e-commerce

## Architektura
- Next.js 15 z App Router
- Baza danych Turso z Drizzle ORM
- Stripe do płatności
- Clerk do uwierzytelniania

## Kluczowe polecenia
- `pnpm dev` - Uruchom serwer deweloperski
- `pnpm test` - Uruchom zestaw testów
- `pnpm db:push` - Wypchnij zmiany schematu

## Standardy kodowania
- Używaj trybu strict TypeScript
- Preferuj eksporty nazwane
- Podążaj za wzorcami React Server Components
- WAŻNE: Nigdy nie importuj kodu klienta w komponentach serwera

Pamięć użytkownika

Lokalizacja: ~/.claude/CLAUDE.md

Twoje osobiste preferencje, które stosują się do wszystkich projektów.

# Osobiste preferencje deweloperskie

## Styl kodu
- Preferuj wczesne returny zamiast zagnieżdżonych if
- Używaj opisowych nazw zmiennych (bez pojedynczych liter)
- Komentuj skomplikowaną logikę inline

## Przepływ pracy
- Zawsze pisz testy dla nowych funkcji
- Commituj często z konwencjonalnymi commitami
- Przeglądaj wygenerowany kod linijka po linijce

Pamięć modułu

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

Wytyczne specyficzne dla kontekstu dla różnych części twojego monorepo.

# Moduł frontend

## Wytyczne komponentów
- Używaj komponentów shadcn/ui jako bazy
- Podążaj za zasadami Atomic Design
- Komponenty muszą być dostępne (WCAG 2.1 AA)

## Zarządzanie stanem
- Stan serwera: TanStack Query
- Stan klienta: Zustand
- Stan formularzy: React Hook Form + Zod

Proces wyszukiwania pamięci

1. Claude rozpoczyna w twoim bieżącym katalogu roboczym
2. Przeszukuje rekursywnie w górę do (ale nie włączając) root /
3. Ładuje wszystkie znalezione pliki CLAUDE.md i CLAUDE.local.md
4. Odkrywa zagnieżdżone pliki CLAUDE.md w podkatalogach na żądanie
5. Scala wszystkie pamięci z właściwą precedencją (lokalny → projekt → użytkownik)

Wskazówka

Claude automatycznie odkrywa pliki CLAUDE.md w podkatalogach, gdy pracujesz z plikami w tych katalogach. Oznacza to, że nie musisz ładować wszystkiego z góry - Claude pobiera kontekst w miarę potrzeb.

Szybka inicjalizacja projektu

Używanie polecenia /init

Najszybszy sposób na bootstrap kontekstu twojego projektu:

claude

> /init

To polecenie analizuje twój projekt i generuje kompleksowy plik CLAUDE.md. Oto co zazwyczaj zawiera:

Wygenerowany CLAUDE.md

# Przegląd projektu
Automatycznie wykryty typ i struktura projektu

## Stos technologiczny
- Język: TypeScript
- Framework: Next.js 15.0.3
- Baza danych: PostgreSQL z Prisma
- Testowanie: Jest + React Testing Library

## Struktura projektu
- `/src` - Kod źródłowy aplikacji
- `/src/components` - Komponenty React
- `/src/app` - Strony Next.js app router
- `/src/lib` - Funkcje pomocnicze i współdzielony kod
- `/tests` - Pliki testów

## Dostępne skrypty
- `npm run dev` - Uruchom serwer deweloperski na porcie 3000
- `npm run build` - Zbuduj dla produkcji
- `npm run test` - Uruchom zestaw testów
- `npm run lint` - Uruchom ESLint

## Zmienne środowiskowe
Wymagane zmienne wykryte w .env.example:
- DATABASE_URL - String połączenia PostgreSQL
- NEXT_PUBLIC_API_URL - Endpoint API

## Zależności
Kluczowe pakiety:
- next: 15.0.3
- react: 19.0.0
- @prisma/client: 5.22.0
- tailwindcss: 3.4.1

## Przepływ Git
- Główna gałąź: main
- Gałęzie funkcji: feature/*
- Styl commitów: Conventional Commits

## Dodatkowe uwagi
- Używanie trybu strict TypeScript
- Tailwind CSS do stylowania
- Server Components domyślnie

Dostosowywanie wygenerowanej pamięci

Po uruchomieniu /init, udoskonal wygenerowany plik:

1. Dodaj konwencje zespołu niewykryte automatycznie
2. Udokumentuj decyzje architektoniczne i ich uzasadnienie
3. Uwzględnij typowe pułapki specyficzne dla twojego projektu
4. Dodaj często używane polecenia z wyjaśnieniami
5. Określ wzorce kodowania, których chcesz, aby Claude przestrzegał

Dynamiczne aktualizacje pamięci

Używanie skrótu

Najszybszy sposób na dodawanie pamięci podczas rozwoju:

# Zawsze używaj Radix UI do dropdownów, nie natywnych elementów select

Claude zapyta cię o wybór miejsca zapisania tej pamięci:

Prompt lokalizacji pamięci

Gdzie powinna zostać zapisana ta pamięć?
> 1. Pamięć projektu (./CLAUDE.md)
2. Moduł frontend (./frontend/CLAUDE.md)
3. Pamięć użytkownika (~/.claude/CLAUDE.md)
4. Lokalna pamięć projektu (./CLAUDE.local.md)

Wskazówka

Używaj skrótu # obficie, gdy odkrywasz wzorce specyficzne dla projektu. Jest szybszy niż ręczne edytowanie plików CLAUDE.md i pomaga budować kompleksową dokumentację z czasem.

Importy CLAUDE.md

Dla skomplikowanych projektów używaj importów, aby utrzymać pamięć modularną:

CLAUDE.md z importami

# Główna konfiguracja projektu

Zobacz @README.md dla przeglądu projektu
Przejrzyj @docs/ARCHITECTURE.md dla projektu systemu

## Wytyczne specyficzne dla modułów
- Frontend: @frontend/STYLE_GUIDE.md
- Backend: @backend/API_CONVENTIONS.md
- Baza danych: @docs/database/SCHEMA_DESIGN.md

## Osobiste nadpisania
- @~/.claude/my-project-preferences.md

Importy obsługują:

• Ścieżki względne: @./docs/guide.md
• Ścieżki bezwzględne: @/home/user/standards.md
• Katalog domowy: @~/documents/notes.md
• Importy rekursywne (maks. głębokość: 5)

Konfiguracja projektu

Podstawowe ustawienia (.claude/settings.json)

Skonfiguruj zachowanie Claude dla twojego projektu:

.claude/settings.json

{
"model": "claude-opus-4",
"maxTurns": 30,
"allowedTools": [
  "Edit",
  "View",
  "Bash(git:*)",
  "Bash(npm:*)",
  "Bash(pnpm:*)",
  "WebFetch",
  "mcp__*"
],
"hooks": [
  {
    "matcher": "Edit",
    "hooks": [
      {
        "type": "command",
        "command": "pnpm prettier --write \"$CLAUDE_FILE_PATHS\""
      }
    ]
  }
],
"ignoredFiles": [
  "*.env*",
  "*.key",
  "*.pem",
  "node_modules/**",
  ".next/**",
  "dist/**"
]
}

Konfiguracja serwera MCP

Skonfiguruj serwery Model Context Protocol dla rozszerzonych możliwości:

Zakres projektu

Utwórz .mcp.json w katalogu głównym projektu (dzielony przez Git):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

Przez CLI

Dodaj serwery MCP interaktywnie:

# Dodaj integrację GitHub
claude mcp add github --transport stdio \
  npx -y @modelcontextprotocol/server-github \
  -e GITHUB_TOKEN=$GITHUB_TOKEN

# Dodaj dostęp do bazy danych
claude mcp add postgres --transport stdio \
  npx -y @modelcontextprotocol/server-postgres \
  -e CONNECTION_STRING=$DATABASE_URL

# Dodaj automatyzację przeglądarki
claude mcp add puppeteer --transport stdio \
  npx -y @modelcontextprotocol/server-puppeteer

Zakres użytkownika

Dla narzędzi osobistych dostępnych we wszystkich projektach:

# Dodaj do konfiguracji użytkownika
claude mcp add -s user context7 \
  --transport sse \
  https://context7.mcp.run

Uwaga

Gdy członkowie zespołu po raz pierwszy używają projektu z .mcp.json, Claude Code zapyta o zatwierdzenie. Ten środek bezpieczeństwa zapobiega złośliwym konfiguracjom MCP. Członkowie zespołu mogą zresetować zatwierdzenia za pomocą claude mcp reset-project-choices.

Przestrzenie robocze wielu katalogów

Konfigurowanie skomplikowanych projektów

Dla monorepo lub architektur wielu usług:

1. Uruchom Claude w katalogu głównym

   cd ~/projects/my-monorepo
   claude

2. Dodaj dodatkowe katalogi

   > /add-dir ../shared-lib
   > /add-dir ../design-system

3. Lub użyj flag CLI

   claude --add-dir ../backend ../frontend ../shared

4. Ustaw na stałe

   claude config add addDirs "../backend,../frontend"

Najlepsze praktyki przestrzeni roboczej

Organizacja monorepo

project-root/
├── CLAUDE.md              # Ogólny kontekst projektu
├── .mcp.json             # Wspólne serwery MCP
├── frontend/
│   ├── CLAUDE.md         # Zasady specyficzne dla frontend
│   └── src/
├── backend/
│   ├── CLAUDE.md         # Wzorce backend
│   └── src/
└── shared/
    ├── CLAUDE.md         # Kontekst wspólnej biblioteki
    └── src/

Uruchamiaj Claude z project-root/ ze wszystkimi podkatalogami dostępnymi.

Polecenia niestandardowe

Tworzenie poleceń specyficznych dla projektu

Przechowuj przepływy pracy wielokrotnego użytku jako polecenia slash:

.claude/commands/new-feature.md

# Utwórz nową funkcję zgodnie z naszą architekturą

Proszę utwórz nową funkcję o nazwie: $ARGUMENTS

Wykonaj te kroki:
1. Utwórz folder funkcji w src/features/$ARGUMENTS
2. Skonfiguruj standardową strukturę:
 - index.ts (publiczne eksporty)
 - types.ts (interfejsy TypeScript)
 - $ARGUMENTS.tsx (główny komponent)
 - $ARGUMENTS.test.tsx (testy)
 - $ARGUMENTS.stories.tsx (Storybook)
3. Dodaj funkcję do głównych eksportów
4. Utwórz początkowe testy ze 100% pokryciem
5. Dodaj do konfiguracji flag funkcji

Używaj naszych standardowych wzorców:
- Wzorzec Container/Presenter
- Niestandardowe hooki dla logiki
- Styled components do stylowania
- React Query do pobierania danych

Użycie: /project:new-feature user-profile

Organizacja poleceń

.claude/commands/
├── new-feature.md        # /project:new-feature
├── api/
│   └── endpoint.md      # /project:api:endpoint
├── db/
│   ├── migration.md     # /project:db:migration
│   └── seed.md          # /project:db:seed
└── test/
    └── e2e.md           # /project:test:e2e

Przykład z prawdziwego świata

Kompletna konfiguracja projektu

Oto jak senior developer konfiguruje nowy projekt Next.js:

1. Zainicjalizuj projekt

   cd ~/projects/saas-app
   claude
   > /init

2. Udoskonal wygenerowany CLAUDE.md

   > Edytuj CLAUDE.md i dodaj specyficzne konwencje naszego zespołu

3. Skonfiguruj serwery MCP

   > /mcp add github --transport sse https://github.com/api/mcp
   > /mcp add postgres --transport stdio npx @modelcontextprotocol/server-postgres

4. Skonfiguruj konfigurację projektu

   > Utwórz .claude/settings.json z naszymi preferowanymi narzędziami i hookami

5. Dodaj polecenia niestandardowe

   > Utwórz .claude/commands/new-component.md dla naszego generatora komponentów
   > Utwórz .claude/commands/deploy.md dla przepływu pracy wdrożenia

6. Skonfiguruj dostęp do wielu katalogów

   > /add-dir ../design-system
   > /add-dir ../shared-types

7. Przetestuj konfigurację

   > Utwórz nową funkcję uwierzytelniania użytkownika zgodnie z naszymi wzorcami

Najlepsze praktyki pamięci

Złote zasady dla plików CLAUDE.md

1. Bądź konkretny a nie ogólny - “Używaj Zod do walidacji” a nie “waliduj dane wejściowe”
2. Uwzględnij przykłady - Pokaż Claude dokładnie, czego chcesz
3. Udokumentuj dlaczego - Wyjaśnij uzasadnienie za konwencjami
4. Aktualizuj regularnie - Używaj # do dodawania nauk podczas kodowania
5. Przeglądaj okresowo - Czyść przestarzałe informacje co miesiąc
6. Testuj skuteczność - Poproś Claude o wyjaśnienie twoich konwencji z powrotem

Antywzorce do unikania

❌ Zbyt ogólne: “Pisz dobry kod”
✅ Konkretne: “Używaj wczesnych returnów, maks. 3 poziomy zagnieżdżeń, wyodrębniaj skomplikowane warunki”

❌ Brak kontekstu: “Używaj naszego stylu API”
✅ Z kontekstem: “Podążaj za konwencjami REST: GET /api/users, POST /api/users, używaj kebab-case”

❌ Przestarzałe info: “Używamy komponentów klas React 16”
✅ Obecnie: “React 19 z Server Components, używaj tylko komponentów funkcji”

Rozwiązywanie problemów

Typowe problemy

Pamięć się nie ładuje

Objaw: Claude nie wydaje się świadomy zawartości twojego CLAUDE.md

Rozwiązania:

1. Sprawdź lokalizację pliku - musi być w katalogu głównym projektu lub katalogach nadrzędnych
2. Zweryfikuj nazwę pliku - dokładnie CLAUDE.md (rozróżnia wielkość liter na Linux/Mac)
3. Uruchom /memory aby zobaczyć, co jest załadowane
4. Zrestartuj Claude Code po dodaniu nowych plików pamięci

Połączenie MCP nieudane

Objaw: Serwery MCP pokazują się jako rozłączone

Rozwiązania:

1. Uruchom z flagą debug: claude --mcp-debug
2. Sprawdź, czy URL/ścieżka serwera jest poprawna
3. Zweryfikuj, czy tokeny uwierzytelniania są ustawione
4. Przetestuj serwer ręcznie: npx @modelcontextprotocol/server-name
5. Sprawdź ustawienia firewall/proxy

Sprzeczne instrukcje

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

Rozwiązania:

1. Użyj /clear do zresetowania kontekstu rozmowy
2. Dodaj “WAŻNE:” lub “MUSISZ” dla krytycznych zasad
3. Sprawdź precedencję - lokalny nadpisuje projekt nadpisuje użytkownika
4. Usuń sprzeczne instrukcje z katalogów nadrzędnych

Następne kroki

Teraz, gdy twój projekt jest zainicjalizowany z bogatym kontekstem:

Przepływ PRD Naucz się tworzyć kompleksowe wymagania z Claude

Konfiguracja MCP Skonfiguruj zaawansowane serwery MCP dla twojego przepływu pracy

Przepływ pracy deweloperskiej Opanuj metodologię PRD → Plan → Todo

Pamiętaj: Świetny kontekst prowadzi do świetnego kodu. Zainwestuj czas w swoje pliki CLAUDE.md i obserwuj, jak twoja produktywność wzleci!