CLAUDE.md - konfiguracja projektu i pamięć | Kurs Claude AI

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)
    ↓
~/.claude/rules/*.md          ← Reguły użytkownika (wszystkie projekty na tej maszynie)
    ↓
projekt/CLAUDE.md             ← Projekt (root, commitowany)
    ↓
projekt/src/CLAUDE.md         ← Podkatalog (per moduł)
    ↓
.claude/rules/*.md            ← Reguły projektu (opcjonalny scope przez paths)
    ↓
CLAUDE.local.md               ← Lokalne preferencje (NIE commitowane)

Pliki się nie nadpisują - wszystkie trafiają do kontekstu, a bardziej szczegółowe Claude czyta później. Kolejność nie rozstrzyga jednak konfliktów: przy sprzecznych instrukcjach Claude może wybrać dowolną z nich. Sprzeczności usuwaj, zamiast liczyć na to, że wygra plik bardziej lokalny. Pliki z podkatalogów dociągają się dopiero, gdy Claude pracuje z plikami w tych katalogach.

Stan na 1 października 2026: ta hierarchia obowiązuje w terminalu, VS Code, JetBrains i aplikacji desktopowej. Sesja w chmurze (claude.ai/code) startuje ze świeżego klona repozytorium, więc widzi tylko pliki z repo: projektowe CLAUDE.md i .claude/rules/. Twój ~/.claude/CLAUDE.md, reguły z ~/.claude/rules/ i niecommitowany CLAUDE.local.md zostają na komputerze.

Plik	Lokalizacja	Cel	Git?
`~/.claude/CLAUDE.md`	HOME	Globalne preferencje	NIE
`~/.claude/rules/*.md`	HOME	Osobiste reguły tematyczne dla każdego projektu na maszynie	NIE
`CLAUDE.md`	Root projektu	Konwencje zespołowe	TAK
`CLAUDE.md`	Podkatalogi	Instrukcje per-moduł	TAK
`AGENTS.md`	Root projektu lub podkatalogi	Instrukcje wspólne dla wielu agentów AI; Claude Code czyta je, gdy brak CLAUDE.md (od wersji 2.1.277)	TAK
`CLAUDE.local.md`	Root projektu	Osobiste preferencje (dodaj do `.gitignore`)	NIE
`.claude/settings.json`	Root projektu	Permissions, MCP	TAK
`.claude/rules/*.md`	Projekt	Reguły tematyczne, opcjonalnie per ścieżka	TAK

Importy @ścieżka. CLAUDE.md może dociągać inne pliki składnią @ścieżka/do/pliku, np. @README albo @docs/git-instructions.md. Importy ładują się przy starcie sesji i zagnieżdżają do 4 poziomów. Porządkują duży plik, ale nie oszczędzają kontekstu, bo importowane pliki też wchodzą na starcie.

CLAUDE.local.md wciąż działa, ale ma ograniczenie: przy pracy na kilku git worktree istnieje tylko tam, gdzie go utworzysz. Dokumentacja zaleca wtedy import z katalogu domowego - wpis @~/.claude/moje-instrukcje.md w CLAUDE.md daje ten sam efekt w każdym worktree.

AGENTS.md (od wersji 2.1.277). Wiele repozytoriów ma już plik AGENTS.md z instrukcjami dla innych agentów AI do kodowania. Claude Code czyta go sam, ale tylko wtedy, gdy w katalogu roboczym ani wyżej nie ma CLAUDE.md, .claude/CLAUDE.md ani CLAUDE.local.md. Twój ~/.claude/CLAUDE.md i reguły z .claude/rules/ nie blokują AGENTS.md, tylko ładują się obok niego.

Pułapka: wystarczy dodać własny CLAUDE.local.md, żeby Claude przestał czytać AGENTS.md. Chcesz, żeby czytał oba źródła naraz? W /config ustaw Project instructions na claude-md-and-agents-md albo wpisz w CLAUDE.md linię @AGENTS.md. Czy AGENTS.md się wczytał, sprawdzisz w /memory.

Przechodzisz z innego agenta? Komenda /import przeniesie z Codexa, Gemini CLI albo Cursora pliki instrukcji, serwery MCP, komendy, subagentów i skille (wymaga 2.1.213 lub nowszej, a import z Cursora 2.1.265 lub nowszej).

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

Sekcje „Struktura” i „Technologie” trzymaj krótkie. Układ katalogów i listę zależności Claude wyczyta z kodu, więc /doctor (więcej o nim niżej) zaproponuje ich wycięcie. Najwięcej dają rzeczy, których w kodzie nie widać: pułapki, powody decyzji i konwencje odbiegające od domyślnych ustawień narzędzi.

Reguły w .claude/rules/

Katalog .claude/rules/ dzieli instrukcje na pliki tematyczne (np. testing.md, security.md). Reguła bez frontmattera ładuje się zawsze, przy starcie sesji. Reguła z polem paths aktywuje się tylko wtedy, gdy Claude pracuje z pasującymi plikami - to oszczędza kontekst.

Przykład: plik .claude/rules/testing.md:

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

Dwa poziomy reguł. Reguły projektu leżą w .claude/rules/ i wędrują z repozytorium. Reguły osobiste, wspólne dla wszystkich projektów na Twojej maszynie, trzymasz w ~/.claude/rules/ - to nowszy poziom, który działa identycznie (ten sam frontmatter, to samo pole paths), ale nie trafia do gita. Praktyczny podział: konwencje zespołu do projektu, własne nawyki (np. „odpowiadaj po polsku”, „nie używaj em dashów”) do katalogu domowego.

Budżet wzorców. Lista paths jednej reguły mieści do 1000 rozwiniętych wzorców i 4 MiB. Liczą się tylko wzorce z klamrami: src/*.{ts,tsx} rozwija się w dwa wzorce. Zwykłe wzorce bez klamer budżetu nie zużywają. Przy zwykłych projektach nie zbliżysz się do tego pułapu. Problem robi się przy generowanych wzorcach z wieloma klamrami - wtedy rozbij regułę na kilka plików.

Auto Memory

Dzięki Auto Memory Claude Code akumuluje wiedzę między sesjami automatycznie. Stan na 1 października 2026: mechanizm i lokalizacja plików bez zmian. Auto Memory jest domyślnie włączona w sesjach lokalnych.

Co zapisuje:

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

Jak działa:

Dane per projekt w ~/.claude/projects/<projekt>/memory/ - indeks MEMORY.md plus pliki tematyczne (np. debugging.md)
Na start sesji ładuje się początek indeksu: do ~200 linii lub ~25 KB MEMORY.md, cokolwiek nastąpi pierwsze
Reszta indeksu i pliki tematyczne NIE wchodzą automatycznie - Claude doczytuje je na żądanie
Wszystkie worktree tego samego repo współdzielą jedną pamięć, bo ścieżka <projekt> wynika z repozytorium git, nie z katalogu roboczego; dane zostają lokalnie na Twojej maszynie i nie trafiają do sesji w chmurze

Zarządzanie: /memory w sesji Claude Code. Przeglądasz tam pliki CLAUDE.md i notatki pamięci, a przełącznikiem włączasz lub wyłączasz Auto Memory. Prośba „zapamiętaj, że…” trafia do Auto Memory. Chcesz zapisu w CLAUDE.md? Powiedz wprost: „dopisz to do CLAUDE.md”.

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 - dokumentacja Anthropic zaleca mniej niż 200 linii na jeden plik CLAUDE.md. Dłuższy plik zjada kontekst, a Claude rzadziej się go trzyma
Używaj formatowania Markdown (nagłówki, listy, tabele)
Aktualizuj regularnie - nieaktualne instrukcje są gorsze niż brak instrukcji
Zlecaj przegląd instrukcji. /doctor prompt-audit (od wersji 2.1.283) szuka instrukcji pisanych pod starsze modele, odwołań do nieistniejących plików i komend oraz sprzeczności między plikami. Zwykły /doctor proponuje wyciąć z CLAUDE.md to, co Claude wyczyta z kodu. Oba najpierw pokazują raport i niczego nie zmieniają bez Twojej zgody
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 - podaj samą ścieżkę (bez @), a Claude doczyta plik, gdy uzna go za potrzebny. Import @ wczytuje cały plik już na starcie

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

Uruchom claude w katalogu projektu i wpisz /init LUB stwórz plik ręcznie. Ze zmienną CLAUDE_CODE_NEW_INIT=1 komenda /init przeprowadzi Cię też przez skille, hooki i osobiste pliki pamięci

Wypełnij sekcje: Opis, Struktura, Technologie, Konwencje, Ważne pliki, Komendy

Przetestuj: zapytaj Claude Code „Jaki jest stack tego projektu?” - czy odpowiada poprawnie?

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.