System Pamięci Claude Code

Właśnie wdrożyłeś nowego developera. Skonfigurował Claude Code i natychmiast poprosił go o “dodanie nowego endpointu API”. Claude wygenerował trasę Express — ale Twój projekt używa Fastify. Stworzył plik JavaScript — ale Twój projekt używa wyłącznie TypeScript. Umieścił plik w src/routes/ — ale Twoja konwencja to src/api/v2/. Każde założenie było błędne, ponieważ Claude nie miał żadnego kontekstu o Twoim projekcie.

System pamięci to rozwiązuje. To sposób, w jaki uczysz Claude’a o architekturze, konwencjach i preferencjach Twojego projektu — trwale, między sesjami, współdzielone z Twoim zespołem.

Co Wyniesiecie z Tego Rozdziału

• Kompletna hierarchia pamięci: zarządzana, projektowa, użytkownika, lokalna i automatyczna pamięć
• Techniki pisania efektywnych plików CLAUDE.md, które zmieniają zachowanie Claude’a
• Reguły projektowe z dopasowaniem ścieżek dla dużych monorepozytoriów
• Zarządzanie automatyczną pamięcią i limit 200 linii MEMORY.md
• Wzorce importów dla modularnych, łatwych w utrzymaniu plików pamięci

Hierarchia Pamięci

Claude Code ładuje pamięć z sześciu lokalizacji, każda służy innemu celowi:

Typ Pamięci	Lokalizacja	Kto Ją Widzi	Kiedy Jest Ładowana
Polityka zarządzana	Poziom systemowy (wdrażana przez IT)	Wszyscy użytkownicy	Zawsze, najwyższy priorytet
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
Reguły projektu	./.claude/rules/*.md	Wszyscy członkowie zespołu	Warunkowo, na podstawie ścieżki
Pamięć lokalna	./CLAUDE.local.md	Tylko Ty, ten projekt	Zawsze
Automatyczna pamięć	~/.claude/projects/<projekt>/memory/	Tylko Ty, dla każdego projektu	Pierwsze 200 linii

Bardziej specyficzna pamięć ma pierwszeństwo przed szerszą pamięcią. Jeśli Twój użytkowniczy CLAUDE.md mówi “używaj wcięć 2-spacjowych”, ale projektowy CLAUDE.md mówi “używaj wcięć 4-spacjowych”, reguła projektu wygrywa.

Pisanie Efektywnych Plików CLAUDE.md

Projektowy CLAUDE.md

To najważniejszy plik, jaki napiszesz. Jest ładowany do każdej sesji Claude Code dla każdego członka zespołu pracującego nad tym projektem.

# Projekt: Payments API

## Architektura
- Framework: Fastify z TypeScript
- Baza danych: PostgreSQL przez Prisma ORM
- Autoryzacja: JWT z refresh tokenami w Redis
- Wersjonowanie API: bazujące na URL (/api/v2/)

## Kluczowe Komendy
- `npm run dev` -- Uruchom serwer deweloperski na porcie 3000
- `npm run test` -- Uruchom testy Jest
- `npm run test:watch` -- Jest w trybie obserwacji
- `npm run lint` -- ESLint z auto-naprawą
- `npm run db:migrate` -- Uruchom migracje Prisma
- `npm run db:seed` -- Wypełnij bazę danymi deweloperskimi

## Konwencje Kodu
- Wszystkie trasy API w src/api/v2/
- Używaj schematów Zod do walidacji requestów/response'ów
- Odpowiedzi błędów zgodne z RFC 7807 (Problem Details)
- Zapytania do bazy używają Prisma, nigdy surowego SQL
- Wszystkie eksportowane funkcje muszą mieć komentarze JSDoc
- Testy obok plików źródłowych: user.service.ts -> user.service.test.ts

## NIE RÓB
- Nie modyfikuj plików migracji po ich zacommitowaniu
- Nie używaj console.log -- używaj serwisu Logger z src/lib/logger.ts
- Nie dodawaj nowych zależności npm bez sprawdzenia wpływu na rozmiar bundle'a

Wskazówka

Gotowy szablon CLAUDE.md do skopiowania dla nowego projektu TypeScript:

# Projekt: [NAZWA_PROJEKTU]

## Architektura
- Runtime: Node.js 20+
- Język: TypeScript (tryb strict)
- Framework: [TWÓJ_FRAMEWORK]
- Baza danych: [TWOJA_BAZA] przez [TWÓJ_ORM]
- Testowanie: [TWÓJ_FRAMEWORK_TESTOWY]

## Kluczowe Komendy
- `npm run dev` -- Serwer deweloperski
- `npm run build` -- Build produkcyjny
- `npm run test` -- Uruchom testy
- `npm run lint` -- Lint z auto-naprawą

## Konwencje Kodu
- Używaj komponentów funkcyjnych z hookami (bez komponentów klasowych)
- Preferuj named exports nad default exports
- Obsługa błędów: zawsze używaj typowanych błędów, nigdy nie rzucaj surowych stringów
- Pliki: kebab-case dla plików, PascalCase dla komponentów/klas

## Typowe Wzorce
- Wywołania API: używaj narzędzia `fetcher` w src/lib/fetcher.ts
- Zarządzanie stanem: [TWÓJ_WZORZEC]
- Autoryzacja: [TWÓJ_WZORZEC_AUTH]

Osobisty CLAUDE.md

Twój CLAUDE.md na poziomie użytkownika (~/.claude/CLAUDE.md) stosuje się do wszystkich projektów. Skup się na uniwersalnych preferencjach:

# Preferencje Osobiste

- Zawsze wyjaśniaj swoje rozumowanie przed wprowadzeniem zmian
- Gdy napotkasz punkt decyzyjny, przedstaw opcje i poproś mnie o wybór
- Używaj zwięzłych odpowiedzi -- pomijaj podsumowania tego, co właśnie zrobiłeś
- Podczas edycji plików pokaż krótkie podsumowanie diff zmian
- Preferuję wzorce programowania funkcyjnego nad OOP gdy to możliwe

Lokalne Nadpisania

CLAUDE.local.md jest automatycznie dodawany do gitignore. Używaj go dla szczegółów specyficznych dla maszyny:

# Rozwój Lokalny

- Moja baza deweloperska działa na localhost:5433 (nie domyślny 5432)
- Endpoint API testowego: https://staging.internal.company.com/api
- Używaj `npm run dev:local` zamiast `npm run dev` (niestandardowe zmienne env)

Reguły Projektu

Dla dużych projektów pojedynczy CLAUDE.md staje się nieporęczny. Reguły projektu pozwalają podzielić instrukcje na modularne pliki specyficzne dla ścieżek.

Podstawowe Reguły

Utwórz pliki w .claude/rules/:

.claude/rules/
  testing.md         # Konwencje testowania
  api-design.md      # Standardy projektowania API
  database.md        # Wzorce zapytań do bazy
  security.md        # Wymagania bezpieczeństwa

Każdy plik jest ładowany do kontekstu gdy jest istotny. Claude czyta je podczas pracy z plikami w pasujących ścieżkach.

Reguły Specyficzne dla Ścieżek

Reguły mogą targetować konkretne katalogi lub wzorce plików używając frontmatter:

---
globs: src/api/**/*.ts
---

# Konwencje Tras API

Wszystkie trasy API muszą:
1. Używać Zod do walidacji wejścia
2. Zwracać typowane odpowiedzi używając ApiResponse<T>
3. Zawierać rate limiting przez dekorator @rateLimit
4. Logować wszystkie requesty używając middleware RequestLogger

---
globs: "*.test.ts,*.spec.ts"
---

# Standardy Testowania

- Używaj opisowych nazw testów: "should return 404 when user not found"
- Grupuj powiązane testy w blokach describe według metody/funkcji
- Mockuj zewnętrzne serwisy, nigdy nie wykonuj prawdziwych wywołań API w testach
- Każdy plik testowy powinien testować pojedynczy moduł

Wskazówka

Gotowa reguła do skopiowania dla konwencji komponentów React:

Utwórz .claude/rules/react-components.md:

---
globs: "src/components/**/*.tsx"
---

# Konwencje Komponentów React

- Używaj komponentów funkcyjnych z interfejsami TypeScript dla props
- Interfejs props nazwany ComponentNameProps
- Eksportuj komponenty jako named exports, nie default
- Współlokalizuj style: Component.tsx i Component.module.css
- Współlokalizuj testy: Component.tsx i Component.test.tsx
- Używaj React.memo() tylko gdy profilowanie pokazuje korzyść wydajnościową
- Preferuj kompozycję nad prop drilling -- używaj kontekstu dla głęboko współdzielonego stanu

Automatyczna Pamięć

Automatyczna pamięć to miejsce, gdzie Claude pisze notatki dla siebie. W przeciwieństwie do CLAUDE.md (który Ty piszesz dla Claude’a), automatyczna pamięć zawiera rzeczy, które Claude odkrywa podczas sesji.

Co Claude Pamięta

• Wzorce projektu: działające komendy build, konwencje testów, kroki deploymentu
• Spostrzeżenia debugowania: rozwiązania trudnych problemów, typowe przyczyny błędów
• Notatki architektoniczne: kluczowe relacje plików, granice modułów
• Twoje preferencje: styl komunikacji, nawyki workflow

Zarządzanie Automatyczną Pamięcią

Automatyczna pamięć jest przechowywana w ~/.claude/projects/<projekt>/memory/. Główny plik to MEMORY.md, a Claude może tworzyć pliki tematyczne obok niego.

~/.claude/projects/my-project/memory/
  MEMORY.md           # Główny indeks, pierwsze 200 linii ładowane przy starcie
  debugging.md        # Wzorce debugowania odkryte przez Claude'a
  api-conventions.md  # Wzorce API nauczane przez Claude'a z Twojego kodu

Użyj /memory aby otworzyć i edytować plik automatycznej pamięci. Usuń wpisy, które są nieaktualne lub niepoprawne.

Uwaga

Tylko pierwsze 200 linii MEMORY.md są ładowane przy starcie. Jeśli Twój plik automatycznej pamięci urośnie powyżej tego, Claude nie zobaczy wszystkiego. Okresowo przeglądaj go za pomocą /memory i przycinaj nieaktualne wpisy.

Importy CLAUDE.md

Dla dużych projektów możesz podzielić swój CLAUDE.md na moduły i zaimportować je:

# Projekt: Duże Monorepo

@api-guidelines.md
@testing-standards.md
@deployment-checklist.md

Składnia @ścieżka importuje zawartość referencyjnego pliku. Ścieżki są relatywne do lokalizacji pliku CLAUDE.md.

Kiedy To Nie Działa

Claude ignoruje instrukcje CLAUDE.md: Dzieje się to gdy okno kontekstu jest zbyt pełne i starsze instrukcje zostają skompaktowane. Trzymaj swój CLAUDE.md zwięzły (poniżej 200 linii dla głównego pliku) i umieszczaj najważniejsze reguły na początku.

Automatyczna pamięć zawiera niepoprawne informacje: Claude czasami zapisuje niedokładne wzorce. Użyj /memory aby przejrzeć i poprawić wpisy. Usuń wszystko co jest błędne — nieaktualna pamięć jest gorsza niż brak pamięci.

Reguły nie stosują się do właściwych plików: Sprawdź swoje wzorce glob. Frontmatter globs używa standardowej składni glob. Testuj z prostymi wzorcami najpierw (src/**/*.ts) przed użyciem złożonych.

Lokalne nadpisania nie działają: Upewnij się, że Twój plik nazywa się dokładnie CLAUDE.local.md (nie claude.local.md ani CLAUDE_local.md). Claude Code automatycznie dodaje ten plik do gitignore.

Członkowie zespołu mają różne zachowanie: Zazwyczaj oznacza to, że ktoś ma osobisty CLAUDE.md lub lokalne nadpisania konfliktujące z ustawieniami projektu. Pierwszeństwo to: zarządzana > lokalna > projektowa > użytkownika. Sprawdź wszystkie cztery poziomy.

Co Dalej

• Integracja Korporacyjna — Polityki zarządzane i pamięć na poziomie organizacji
• Niestandardowe Komendy — Buduj komendy wykorzystujące konfigurację pamięci
• Wskazówki Optymalizacji CLAUDE.md — 10 konkretnych wskazówek do pisania lepszych plików pamięci