Każda sesja Claude Code zaczyna się od zera. Agent nie pamięta, że wczoraj wyjaśniałeś mu architekturę projektu. Nie wie, że używacie Prettier z dwoma spacjami. Nie kojarzy, że testy uruchamiacie przez pnpm test, nie npm test.
Chyba że utworzysz plik CLAUDE.md. Wtedy wie wszystko — i to od pierwszej sekundy każdej sesji.
- Problem: generyczne AI vs specyfika projektu
- Czym jest CLAUDE.md
- Gdzie umieścić plik
- Co wpisać, a czego nie
- Auto-memory: AI samo notuje wzorce
- Przykładowy CLAUDE.md dla projektu Next.js
Claude Code jest potężny, ale generyczny. Nie wie, że:
- Twój zespół używa konwencji nazewnictwa
kebab-casedla plików - Testy integracyjne wymagają uruchomienia bazy danych w Dockerze
- Pull requesty muszą przejść przez review dwóch osób
- Logowanie odbywa się przez wewnętrzną bibliotekę, nie przez
console.log
Bez tej wiedzy Claude będzie zgadywał. Czasem trafi, czasem nie. A Ty będziesz poprawiał te same błędy w kółko.
Plik CLAUDE.md rozwiązuje ten problem. To instrukcja, którą Claude czyta przy każdej sesji. Raz napisana, działa zawsze.
## Czym jest CLAUDE.mdCLAUDE.md to zwykły plik Markdown. Umieszczasz go w głównym katalogu projektu, a Claude Code automatycznie go ładuje przy starcie sesji.
Możesz w nim zapisać:
- Polecenia do budowania i testowania
- Konwencje nazewnictwa i stylu kodu
- Architekturę projektu i kluczowe decyzje
- Typowe pułapki i rzeczy, których unikać
- Workflow zespołowy (np. „zawsze uruchom lint przed commitem")
Claude traktuje te instrukcje jako kontekst. Im bardziej konkretne i zwięzłe, tym lepiej je respektuje.
Celuj w maksymalnie 200 linii per plik CLAUDE.md. Dłuższe pliki zużywają więcej tokenów i zmniejszają skuteczność instrukcji.
Claude Code obsługuje kilka lokalizacji dla plików CLAUDE.md, każda z innym zakresem:
| Zakres | Lokalizacja | Dzielony z |
| Projekt (zespół) | ./CLAUDE.md lub ./.claude/CLAUDE.md | Zespół przez git |
| Użytkownik (wszystkie projekty) | ~/.claude/CLAUDE.md | Tylko Ty |
| Lokalny (nie w git) | ./CLAUDE.local.md | Tylko Ty |
| Organizacja (IT/DevOps) | /etc/claude-code/CLAUDE.md | Wszyscy w org |
Typowa konfiguracja:
./CLAUDE.md— standardy zespołu, architektura, komendy build/test./CLAUDE.local.md— Twoje osobiste preferencje, lokalne URL-e testowe~/.claude/CLAUDE.md— preferencje dla wszystkich projektów
Claude Code ładuje pliki od najbardziej ogólnych do najbardziej szczegółowych. Instrukcje z pliku projektowego nadpisują te użytkownika.
## Co wpisać, a czego nieWpisz:
- Konkretne polecenia:
npm run test:unit,docker-compose up -d - Zasady weryfikowalne: „Używaj 2 spacji do wcięć"
- Architekturę: „Handlery API są w
src/api/handlers/" - Pułapki: „Nie używaj
anyw TypeScript, nawet tymczasowo"
Nie wpisuj:
- Rzeczy, które Claude sam wydedukuje z kodu
- Ogólników typu „pisz dobry kod"
- Pełnej dokumentacji projektu (linkuj zamiast tego)
Przykład dobrej instrukcji:
## Build i testy
- `pnpm dev` - serwer deweloperski
- `pnpm test` - testy jednostkowe (wymagany coverage 80%)
- `pnpm lint` - musi przejść przed commitem
## Konwencje
- Pliki w kebab-case, komponenty w PascalCase
- Każdy endpoint API ma walidację Zod
- Logi przez @internal/logger, nie console.log
Oprócz CLAUDE.md istnieje drugi system pamięci: auto-memory. Claude sam zapisuje rzeczy, które odkrywa podczas pracy:
- Polecenia build, które działają
- Preferencje, które mu pokazujesz
- Wzorce, które korygowałeś
Te notatki są zapisywane per projekt i ładowane przy każdej sesji (pierwsze 200 linii).
| Cecha | CLAUDE.md | Auto-memory |
| Kto pisze | Ty | Claude |
| Zawartość | Instrukcje i reguły | Odkryte wzorce |
| Używaj do | Standardy, architektura | Komendy build, debugging insights |
Oba systemy się uzupełniają. CLAUDE.md to Twoje jawne instrukcje. Auto-memory to wiedza, którą Claude zdobywa sam.
Użyj komendy /init aby Claude automatycznie wygenerował startowy plik CLAUDE.md na podstawie analizy Twojego projektu. Potem doprecyzuj to, czego sam nie odkryje.
# Projekt: Dashboard Analytics
## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- PostgreSQL + Prisma
## Komendy
- `pnpm dev` - serwer na localhost:3000
- `pnpm test` - Vitest, wymagany coverage 80%
- `pnpm db:push` - sync schema z bazą
- `pnpm lint` - ESLint + Prettier (musi przejść przed PR)
## Struktura
- /app - routing Next.js
- /components - komponenty UI (shadcn/ui)
- /lib - logika biznesowa
- /prisma - schema i migracje
## Konwencje
- Komponenty w PascalCase, pliki w kebab-case
- Server Components domyślnie, Client tylko gdy potrzebne
- Formularze przez react-hook-form + Zod
- Błędy przez toast (sonner), nie alert()
## Nie rób
- Nie używaj `any` w TypeScript
- Nie commituj bez uruchomienia lint
- Nie dodawaj zależności bez uzgodnienia z zespołem
Ten plik ma ~30 linii i pokrywa 90% sytuacji. Claude wie jak budować, testować i pisać kod zgodnie z konwencjami zespołu.
Jeśli szukasz alternatywnego systemu pamięci dla agentów AI, sprawdź artykuł Co to jest OpenClaw?. OpenClaw używa podobnego podejścia z plikami AGENTS.md i MEMORY.md.
Więcej o praktycznym wdrażaniu AI w zespołach deweloperskich znajdziesz w artykule Agentic AI: przyszłość automatyzacji.