CLAUDE.md - konfiguracja projektu i pamięć

Czym jest CLAUDE.md

CLAUDE.md to plik konfiguracyjny, który mówi Claude Code, jak pracować z Twoim projektem. Analogia: jeśli README.md to instrukcja dla ludzi, to CLAUDE.md to instrukcja dla AI.

Claude Code automatycznie czyta CLAUDE.md na początku każdej sesji.

Hierarchia plików

Claude Code używa kilku poziomów konfiguracji (od ogólnego do szczegółowego):

~/.claude/CLAUDE.md          ← Globalny (wszystkie projekty)
    ↓
projekt/CLAUDE.md             ← Projekt (root, commitowany)
    ↓
projekt/src/CLAUDE.md         ← Podkatalog (per moduł)
    ↓
.claude/rules/*.md            ← Reguły warunkowe (glob pattern)
    ↓
CLAUDE.local.md               ← Lokalne preferencje (NIE commitowane)

Bardziej szczegółowy plik nadpisuje ogólniejszy w przypadku konfliktu.

Plik	Lokalizacja	Cel	Git?
~/.claude/CLAUDE.md	HOME	Globalne preferencje	NIE
CLAUDE.md	Root projektu	Konwencje zespołowe	TAK
CLAUDE.md	Podkatalogi	Instrukcje per-moduł	TAK
CLAUDE.local.md	Root projektu	Osobiste preferencje	NIE
.claude/settings.json	Root projektu	Permissions, MCP	TAK
.claude/rules/*.md	Projekt	Reguły warunkowe	TAK

Co wpisywać - szablony

Globalny ~/.claude/CLAUDE.md (~100 linii max)

# Globalne preferencje

## Styl kodu
- TypeScript: strict mode
- Python: type hints
- Komentarze po angielsku

## Workflow
- Commituj często, małe zmiany
- Conventional commits
- Testuj przed każdym commitem

Projektowy CLAUDE.md (root repozytorium)

# Nazwa Projektu

## Opis
Aplikacja webowa do zarządzania zadaniami (Next.js + Prisma)

## Struktura
- src/app/ -- strony Next.js (App Router)
- src/components/ -- komponenty React
- src/lib/ -- utils i helpery
- prisma/ -- schemat bazy danych

## Technologie
- Next.js 15 z App Router
- TypeScript (strict)
- Prisma ORM, TailwindCSS
- Jest + React Testing Library

## Konwencje
- Komponenty: PascalCase
- Pliki: kebab-case
- Hooki: useNazwa
- Testy: *.test.ts obok testowanego pliku

## Ważne pliki
- prisma/schema.prisma -- schemat bazy
- .env.example -- zmienne środowiskowe
- src/lib/auth.ts -- logika autentykacji

## Komendy
- npm run dev -- uruchom lokalnie
- npm run build -- zbuduj produkcję
- npm run test -- uruchom testy

Reguły warunkowe (.claude/rules/*.md)

Aktywowane na podstawie glob pattern:

# .claude/rules/testing.md
---
globs: "**/*.test.ts"
---
Gdy piszesz testy:
- Używaj describe/it pattern
- Mockuj zależności zewnętrzne
- Testuj edge cases
- Minimum 80% coverage

Auto Memory

Dzięki Auto Memory Claude Code akumuluje wiedzę między sesjami automatycznie.

Co zapisuje:

• Komendy, które działają
• Wnioski z debugowania
• Notatki architektoniczne
• Preferencje stylu kodu

Jak działa:

• Dane w ~/.claude/memory/MEMORY.md (globalne) i .claude/memory/MEMORY.md (projektowe)
• Pierwsze 200 linii MEMORY.md ładowane na początku każdej sesji
• Treść ponad 200 linii NIE jest ładowana automatycznie

Zarządzanie: /memory w sesji Claude Code.

Do zapamiętania: CLAUDE.md = stabilny kontekst (architektura, konwencje). Auto Memory = dynamiczny kontekst (preferencje, odkrycia). Nie powielaj informacji.

Mój pierwszy CLAUDE.md miał ponad 400 linii - wrzuciłem tam dosłownie wszystko: styl kodu, listę plików, instrukcje deploy, historię commitów. Claude ignorował połowę. Skróciłem do 150 linii, zostawiając tylko to, co Claude naprawdę musiał wiedzieć - i nagle zaczął stosować się do konwencji.

Best practices

Rób:

• Pisz zwięźle - max ~200-300 linii projektowy CLAUDE.md
• Używaj formatowania Markdown (nagłówki, listy, tabele)
• Aktualizuj regularnie - nieaktualne instrukcje są gorsze niż brak instrukcji
• Commituj CLAUDE.md do repozytorium
• Testuj efektywność - jeśli Claude ignoruje instrukcje, przeformułuj je

Nie rób:

• NIE wpisuj sekretów (hasła, klucze API, tokeny)
• NIE pisz zbyt długo - globalny max ~100 linii
• NIE powtarzaj oczywistości - Claude sam rozpozna TypeScript/React
• NIE dawaj sprzecznych instrukcji między plikami
• NIE wstawiaj całych plików - linkuj zamiast tego

Ćwiczenie praktyczne: Utwórz CLAUDE.md dla istniejącego projektu:

1. Uruchom claude /init w katalogu projektu (jeśli dostępne) LUB stwórz ręcznie
2. Wypełnij sekcje: Opis, Struktura, Technologie, Konwencje, Ważne pliki, Komendy
3. Przetestuj: zapytaj Claude Code "Jaki jest stack tego projektu?" - czy odpowiada poprawnie?
4. Iteruj: jeśli Claude ignoruje jakąś konwencję, doprecyzuj ją w CLAUDE.md

Co dalej

W następnej lekcji poznasz codzienne komendy i workflow - slash commands, flagi, pipe.