Inicjalizacja Projektu: CLAUDE.md i Kontekst Projektu

Prosisz Claude o dodanie nowego endpointa API, a on generuje kod w stylu Express — ale Twój projekt używa Hono. Prosisz o napisanie testów, a on sięga po Jest, podczas gdy Twoje repozytorium używa Vitest z niestandardową konfiguracją. Każda sesja zaczyna się od korygowania Claude o Twoim stacku, konwencjach i strukturze plików. Dobrze przygotowany plik CLAUDE.md całkowicie eliminuje ten wzorzec.

Ten przewodnik pokazuje, jak tworzyć i utrzymywać pliki pamięci, które uczą Claude o Twoim konkretnym projekcie, dzięki czemu pisze kod pasujący do Twojej bazy kodu od pierwszego prompta.

Co Wyniesiesz z Tego Przewodnika

• Plik CLAUDE.md dopasowany do architektury i konwencji Twojego projektu
• Modułowe reguły w .claude/rules/ dla instrukcji tematycznych
• Zrozumienie pełnej hierarchii pamięci (zarządzana, użytkownika, projektu, lokalna)
• Automatyczna pamięć skonfigurowana do uczenia się Twoich preferencji w czasie

Hierarchia Pamięci

Claude Code ładuje instrukcje z wielu lokalizacji. Zrozumienie hierarchii pomaga umieścić odpowiednie instrukcje we właściwym miejscu.

Typ Pamięci	Lokalizacja	Kto Ją Widzi	Kiedy Ładowana
Zarządzana polityka	/Library/Application Support/ClaudeCode/CLAUDE.md	Wszyscy użytkownicy	Zawsze
Pamięć użytkownika	~/.claude/CLAUDE.md	Tylko Ty, wszystkie projekty	Zawsze
Pamięć projektu	./CLAUDE.md lub ./.claude/CLAUDE.md	Wszyscy członkowie zespołu	Zawsze (root)
Reguły projektu	./.claude/rules/*.md	Wszyscy członkowie zespołu	Zawsze
Pamięć lokalna	./CLAUDE.local.md	Tylko Ty, ten projekt	Zawsze
Automatyczna pamięć	~/.claude/projects/<project>/memory/	Tylko Ty, per projekt	Pierwsze 200 linii
Zagnieżdżony CLAUDE.md	./subdir/CLAUDE.md	Wszyscy członkowie zespołu	Na żądanie

Bardziej konkretne instrukcje mają pierwszeństwo przed ogólnymi. Reguła na poziomie projektu nadpisuje preferencję na poziomie użytkownika. CLAUDE.local.md jest automatycznie ignorowany przez git, co czyni go bezpiecznym dla osobistych preferencji.

Bootstrapowanie za Pomocą /init

Najszybszym sposobem rozpoczęcia jest polecenie /init wewnątrz sesji Claude Code:

cd /path/to/your/project
claude

Następnie wewnątrz sesji:

/init

Claude przeanalizuje strukturę Twojego projektu, wykryje stos technologiczny i wygeneruje CLAUDE.md zawierający:

• Kluczowe polecenia (build, test, lint, format)
• Wykryte technologie i frameworki
• Przegląd struktury katalogów
• Podstawowe konwencje kodowania

Uwaga

Automatycznie wygenerowany CLAUDE.md jest punktem wyjścia, a nie gotowym produktem. Musisz go dostosować do swoich rzeczywistych standardów kodowania, decyzji architektonicznych i konwencji zespołu. Generyczna wersja wyprodukuje generyczne rezultaty.

Anatomia Świetnego CLAUDE.md

Oto szablon w jakości produkcyjnej. Skopiuj strukturę i wypełnij swoimi szczegółami projektu:

# Project: [Nazwa Twojego Projektu]

## Key Commands
- `npm run dev` - Start development server (port 3000)
- `npm run build` - Production build
- `npm run test` - Run Vitest tests
- `npm run test:watch` - Watch mode
- `npm run lint` - ESLint check
- `npm run format` - Format with Prettier
- `npm run type-check` - TypeScript checking

## Architecture
- **Framework**: Next.js 14 with App Router
- **Language**: TypeScript (strict mode)
- **Styling**: Tailwind CSS with shadcn/ui components
- **Database**: PostgreSQL with Drizzle ORM
- **Auth**: NextAuth.js v5 with Google/GitHub providers
- **Testing**: Vitest + React Testing Library

## Coding Conventions
- Use functional components with TypeScript interfaces (not types) for props
- Prefer named exports over default exports
- Use `async/await` over `.then()` chains
- Error handling: always catch and log, never silently swallow errors
- Imports: external deps first, then internal absolute (`~/`), then relative

## File Organization
- `src/app/` - Next.js App Router pages and layouts
- `src/components/` - Reusable UI components
- `src/lib/` - Utility functions and shared logic
- `src/lib/db/` - Database schema and queries (Drizzle)
- `src/server/` - Server-only code (API handlers, auth)

## Important Patterns
- All API routes return `NextResponse.json()` with explicit status codes
- Database queries go through `src/lib/db/queries.ts`, not inline
- Components follow the pattern: interfaces first, hooks, handlers, render
- Never use `any` - use `unknown` and narrow the type

Wskazówka

Prompt do skopiowania i wklejenia, aby wygenerować niestandardowy CLAUDE.md:

Przeanalizuj całą tę bazę kodu. Następnie napisz plik CLAUDE.md, który zawiera:
1. Wszystkie kluczowe polecenia ze skryptów package.json
2. Stos technologiczny ze konkretnymi wersjami
3. Konwencje kodowania oparte na istniejących wzorcach kodu
4. Organizację plików i to, co zawiera każdy katalog
5. Ważne wzorce architektoniczne, które obserwujesz
6. Typowe błędy do unikania oparte na stylu kodu

Sformatuj to jako plik markdown, który mogę zapisać bezpośrednio jako CLAUDE.md.

Modułowe Reguły z .claude/rules/

W przypadku większych projektów rozdzielenie instrukcji na skoncentrowane pliki jest czystsze niż jeden masywny CLAUDE.md. Umieść pliki markdown w .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Główne instrukcje projektu
│   └── rules/
│       ├── code-style.md   # Wytyczne stylu kodu
│       ├── testing.md      # Konwencje testowania
│       ├── api-design.md   # Wzorce endpointów API
│       └── security.md     # Wymagania bezpieczeństwa

Wszystkie pliki .md w .claude/rules/ są automatycznie ładowane jako pamięć projektu.

Reguły Specyficzne dla Ścieżek

Reguły mogą być zawężone do konkretnych plików za pomocą YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "src/server/**/*.ts"
---

# API Development Rules

- All API endpoints must validate input with Zod schemas
- Return standardized error responses with { error: string, code: number }
- Include rate limiting middleware on public endpoints
- Log all 5xx errors to our monitoring service

Reguły bez pola paths mają zastosowanie do wszystkich plików. Reguły z paths ładują się tylko wtedy, gdy Claude pracuje z pasującymi plikami.

Organizowanie Reguł według Zakresu

.claude/rules/
├── frontend/
│   ├── react.md        # React component patterns
│   └── styling.md      # Tailwind conventions
├── backend/
│   ├── api.md          # API design patterns
│   └── database.md     # Query patterns
└── general.md          # Universal rules

Wszystkie pliki .md są wykrywane rekurencyjnie, więc podkatalogi działają bez problemu.

Importy CLAUDE.md

Możesz importować zewnętrzne pliki do swojego CLAUDE.md używając składni @path/to/file:

Zobacz @README.md dla przeglądu projektu i @package.json dla dostępnych poleceń.

# Additional References
- API docs: @docs/api-reference.md
- Git workflow: @docs/git-workflow.md

Zarówno ścieżki względne, jak i bezwzględne działają. Ścieżki względne są rozwiązywane względem pliku zawierającego import. Importy mogą być zagnieżdżone do 5 poziomów głębokości.

Notatka

Pierwszym razem, gdy Claude Code napotka zewnętrzne importy w projekcie, pokazuje okno dialogowe zatwierdzenia. Po zatwierdzeniu importy ładują się cicho w kolejnych sesjach.

Pamięć na Poziomie Użytkownika

Dla preferencji, które mają zastosowanie do wszystkich Twoich projektów, edytuj ~/.claude/CLAUDE.md:

# Personal Preferences

- I prefer detailed explanations with code examples
- Always show the full file path when creating new files
- When writing tests, include both happy path and error cases
- Use British English in comments and documentation

Możesz również tworzyć reguły na poziomie użytkownika w ~/.claude/rules/:

~/.claude/rules/
├── preferences.md    # Your coding preferences
└── workflows.md      # Your preferred workflows

Automatyczna Pamięć

Claude Code może automatycznie zapisywać informacje z sesji. Automatyczna pamięć rejestruje wzorce projektu, spostrzeżenia z debugowania i Twoje preferencje bez ręcznej edycji plików.

Aby się włączyć (jeśli nie jest jeszcze domyślnie włączone):

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

Automatyczna pamięć jest przechowywana w ~/.claude/projects/<project>/memory/MEMORY.md. Pierwsze 200 linii jest ładowanych do każdej sesji. Szczegółowe notatki trafiają do plików tematycznych, które Claude czyta na żądanie.

Możesz poprosić Claude, aby zapamiętał rzeczy wprost:

Zapamiętaj, że używamy pnpm, nie npm, w tym projekcie.

Zapisz do pamięci, że testy API wymagają lokalnej instancji Redis działającej na porcie 6379.

Użyj /memory, aby otworzyć selektor plików pamięci i bezpośrednio edytować dowolny plik pamięci.

Wskazówka

Prompt do skopiowania i wklejenia, aby ocenić skuteczność Twojego CLAUDE.md:

Przeczytaj mój plik CLAUDE.md i oceń go według tych kryteriów:
1. Czy zawiera wszystkie kluczowe polecenia z package.json?
2. Czy dokładnie opisuje stos technologiczny?
3. Czy konwencje kodowania są wystarczająco konkretne, aby być użytecznymi?
4. Czy są jakieś przestarzałe lub niepoprawne instrukcje?
5. Jakie ważne wzorce mi brakuje?

Zaproponuj konkretne ulepszenia z dokładnym tekstem do dodania.

CLAUDE.local.md dla Osobistych Nadpisań

Dla preferencji specyficznych dla projektu, które nie powinny być commitowane do git, użyj CLAUDE.local.md w katalogu głównym projektu:

# My local preferences

- My local API runs on port 8080, not the default 3000
- Use my test database: postgresql://localhost:5433/myapp_test
- When running E2E tests, use --headed flag so I can watch

Ten plik jest automatycznie ignorowany przez git. Jest ładowany wraz z projektem CLAUDE.md, ale wpływa tylko na Twoje lokalne sesje.

Kiedy To Się Psuje

Claude ignoruje instrukcje z Twojego CLAUDE.md — Upewnij się, że plik jest w katalogu głównym projektu lub w .claude/CLAUDE.md. Claude ładuje pliki pamięci względem katalogu, z którego rozpocząłeś sesję. Jeśli uruchomisz claude z podkatalogu, przeszukuje on w górę drzewa, ale Twój plik musi być wykrywalny.

Instrukcje konfliktują między plikami — Bardziej konkretne zakresy wygrywają. Reguły projektu nadpisują reguły użytkownika, a reguły lokalne nadpisują reguły projektu. Jeśli masz sprzeczne instrukcje, zakres najbliższy katalogowi roboczemu ma pierwszeństwo.

CLAUDE.md jest zbyt długi i Claude wydaje się tracić wątek — Utrzymuj główny CLAUDE.md zwięzły (poniżej 200 linii) z najbardziej krytycznymi informacjami. Przenieś szczegółowe wytyczne do plików .claude/rules/. Claude ładuje pliki reguł wraz z główną pamięcią, ale może zarządzać większą ilością treści, gdy jest zorganizowana tematycznie.

Pliki automatycznej pamięci się starzeją — Użyj /memory, aby otworzyć i edytować pliki pamięci. Usuń przestarzałe wpisy. Claude może również automatycznie aktualizować pamięć, gdy wzorce się zmieniają.

Co Dalej

Po ustaleniu kontekstu projektu dowiedz się, jak przekształcać wymagania produktowe w ustrukturyzowane plany implementacji.

Workflow PRD Przekształć wymagania w plany i listy zadań

Głębokie Rozumowanie Użyj /think i rozszerzonego myślenia dla złożonych problemów