Rdzeń · krok 3/5Rdzeń programu czytasz bez konta. Quizy, zapis postępu i biblioteka — dla członków.
CLAUDE.md to plik, w którym raz zapisujesz, jak agent ma pracować w twoim projekcie. Bez niego agent za każdym razem zgaduje stack, styl i konwencje. Z nim pracuje według twoich zasad: zna ograniczenia i trzyma się decyzji, które już zapadły.
- 1Konsystencja — AI pracuje w Twoim stylu, nie w losowym
- 2Szybkość — mniej iteracji, bo AI rozumie od startu
- 3Bezpieczeństwo — ograniczenia i zasady zbudowane w instrukcjach
- 4Wspólny start — nowa osoba w zespole (i każda nowa sesja agenta) zaczyna z tym samym kontekstem, zamiast odkrywać zasady metodą prób i błędów
Problem: Każda sesja to reset
Uruchamiasz Claude Code. Pytasz: "Dodaj autentykację do aplikacji."
AI może zwrócić:
- •JWT albo sesje (nie wiesz które wybierze)
- •Inny style kodu niż reszta projektu
- •Pattern, który konfliktuje z Twoją architekturą
- •Nowy folder zamiast istniejącej struktury
Każda sesja wymaga wyjaśniania: "Pamiętaj, że używamy Prisma, TypeScript, Next.js z App Routerem, dark theme, krótkie komponenty..."
To strata czasu. I właśnie po to istnieje CLAUDE.md.
Co to jest CLAUDE.md?
CLAUDE.md to plik w głównym folderze projektu. Claude Code wczytuje go automatycznie na starcie każdej sesji.
Jedna rzecz, którą warto wiedzieć od początku: CLAUDE.md to kontekst, nie egzekwowana konfiguracja. Claude traktuje go jak instrukcję od ciebie — im konkretniej napisaną, tym wierniej stosowaną. Twarde granice (np. „nigdy nie czytaj .env") ustawiasz regułami uprawnień, nie zdaniem w CLAUDE.md.
Treść: Instrukcja obsługi Twojego projektu — dla AI.
- •Stos technologiczny
- •Struktura folderów
- •Konwencje kodowania
- •Design system
- •Decyzje architektoniczne
- •Zasady (co można robić, co nie)
Struktura CLAUDE.md
Sekcja 1: Metadane projektu
markdown# Projekt: [Nazwa] ## Stack techniczny - [Framework]: [wersja] - [Language]: [standard/wersja] - [Baza danych]: [jeśli jest] ## Kto pracuje? - Developers - Claude Code (main tool)
Sekcja 2: Architektura i routing
markdown## Struktura projektu
src/ ├── app/ # Next.js App Router │ ├── (auth)/ # Route group: login, register │ ├── (app)/ # Protected routes │ └── api/ # API endpoints ├── components/ # React components ├── lib/ # Utilities, hooks, types ├── types/ # TypeScript interfaces └── styles/ # Global styles
code### Routing - App Router (Next.js) - Route groups: `(auth)/`, `(app)/`, `(public)/` - Dynamic: `[id]`, `[...slug]` - API: `/api/[resource]/route.ts`
Sekcja 3: Konwencje kodowania
markdown## Naming Conventions - Files: kebab-case (`user-profile.tsx`, `auth-service.ts`) - Components: PascalCase (`UserProfile`, `LoginForm`) - Functions: camelCase (`getUserData`, `validateEmail`) - Constants: SCREAMING_SNAKE_CASE (`API_KEY`, `MAX_RETRIES`) - Types/Interfaces: PascalCase (`User`, `AuthResponse`) ## Code Style - TypeScript strict mode required - Use type annotations on public functions - Arrow functions preferred - Avoid `any` type — use generics or unions - One component per file (unless very small)
Sekcja 4: Design i UI
markdown## Visual Design - Theme: dark-mode (default) - Color palette: - Primary (dark): #0F1419 - Secondary (text): #94A3B8 - Accent (action): #D96147 - Success: #10B981 - Warning: #F59E0B - Error: #EF4444 ## UI Framework - Tailwind CSS only (no css-in-js) - Naming: `src/components/[Feature]/[Component].tsx` - Icons: Lucide React when possible - Forms: Use controlled components with Zod validation
Sekcja 5: Backend i API
markdown## Database - Prisma ORM - PostgreSQL - Migrations: `prisma migrate` - Schema: `prisma/schema.prisma` ## API Patterns - RESTful + pagination - Error responses: `{ success: false, error: "message" }` - Auth: NextAuth.js with JWT - Rate limiting: Implement per critical endpoints ## Environment Variables - Database: DATABASE_URL - Auth: AUTH_SECRET - API keys: EXTERNAL_SERVICE_KEY - Repo: .env.local (gitignored)
Sekcja 6: Ograniczenia i zasady
markdown## DO's - ✅ Use React Server Components by default - ✅ Commit frequently with clear messages - ✅ Add TypeScript types for public functions - ✅ Test locally before suggesting deployment ## DON'Ts - ❌ Don't use inline CSS - ❌ Don't install new dependencies without asking - ❌ Don't modify database schema without migration - ❌ Don't commit .env or secrets - ❌ Don't use `eval()` or `dangerouslySetInnerHTML` ## Breaking Changes - Check CHANGELOG.md before major updates - Coordinate with team before database migrations
Ta sama umowa bez kodu
Plik kontekstowy to nie wynalazek programistów — to stała umowa, którą zapisujesz raz, zamiast powtarzać w każdym zleceniu. Bez kodu działa tak samo:
- •Projekty w aplikacji Claude — instrukcje projektu obowiązują we wszystkich rozmowach w nim („odpowiadaj po polsku", „analizuj pod kątem kosztów", ton marki).
- •Cowork — instrukcje globalne w ustawieniach (twój sposób pracy) i kontekst przypisany do folderu albo projektu (ta konkretna sprawa).
Zasady są wspólne dla wszystkich tych miejsc:
- •Dopisuj regułę, gdy ten sam błąd wraca — nie na zapas. Umowa pisana „na wszelki wypadek" puchnie i rozmywa to, co ważne.
- •Nieaktualna notatka szkodzi bardziej niż jej brak. Instrukcja o narzędziu, którego już nie używacie, prowadzi agenta w złą stronę z pełnym przekonaniem. Przeglądaj umowę, gdy zmienia się sposób pracy.
- •Umowa to kontekst, nie zamek. Twarde granice (czego agent ma nie czytać, nie usuwać) ustawiasz uprawnieniami i tym, co w ogóle podłączasz — nie zdaniem w instrukcji.
Hierarchia plików kontekstowych
| Plik | Zakres | Kto widzi |
|---|---|---|
~/.claude/CLAUDE.md | wszystkie twoje projekty | tylko ty |
./CLAUDE.md lub ./.claude/CLAUDE.md | ten projekt | zespół (przez git) |
./CLAUDE.local.md | ten projekt, twoje prywatne ustawienia | tylko ty (dodaj do .gitignore) |
CLAUDE.md w podfolderze | ten podfolder | wczytywany, gdy Claude pracuje na plikach w tym folderze |
.claude/rules/*.md | temat albo wybrane ścieżki | zespół (przez git) |
Wszystkie znalezione pliki są łączone, a nie nadpisują się nawzajem. Kolejność: od najszerszego zakresu do najwęższego — instrukcje bliżej folderu, w którym pracujesz, Claude czyta później. Jeśli dwa pliki mówią co innego, Claude może wybrać dowolnie — dlatego co jakiś czas przeglądaj je razem i usuwaj sprzeczności.
Poziom 1: Projekt CLAUDE.md
W głównym folderze projektu (albo w .claude/CLAUDE.md). Wczytywany automatycznie na starcie sesji.
Zakres: cały projekt. Trafia do repozytorium — to wspólna umowa zespołu.
Poziom 2: Twój globalny ~/.claude/CLAUDE.md
Plik w katalogu domowym: ~/.claude/CLAUDE.md. Twoje preferencje dla WSZYSTKICH projektów.
markdown# Globalne preferencje Claude Code ## Styl pracy - Zawsze pytaj przed usunięciem plików - Commit messages po polsku - Preferuję krótkie objaśnienia, nie eseje ## Znane problemy - ESLint wymaga --fix - Port 3000 zajęty → użyj 3001
Poziom 3: Reguły w .claude/rules/
Przy większym projekcie dzielisz instrukcje na tematyczne pliki w .claude/rules/ (np. testing.md, api-design.md). Reguła z polem paths we frontmatterze wczytuje się tylko wtedy, gdy Claude pracuje na pasujących plikach — mniej szumu, mniej zużytego kontekstu:
markdown--- paths: - "src/api/**/*.ts" --- # Zasady dla API - Każdy endpoint waliduje dane wejściowe - Błędy zwracamy w formacie { success: false, error: "..." }
Reguła bez pola paths wczytuje się zawsze, tak jak CLAUDE.md.
Poziom 4: CLAUDE.local.md
Twoje prywatne uwagi do tego projektu (lokalne adresy, dane testowe). Dodaj plik do .gitignore — nie jest dla zespołu.
A co z plikami innych narzędzi?
Jeśli repozytorium ma już AGENTS.md (format używany przez inne narzędzia agentowe), a nie ma CLAUDE.md, Claude Code wczyta AGENTS.md. Gdy masz oba — możesz w CLAUDE.md zaimportować drugi plik linijką @AGENTS.md i trzymać wspólne instrukcje w jednym miejscu.
Jak generować CLAUDE.md
Dwie drogi:
- •
/initw Claude Code — Claude analizuje projekt i proponuje startowy CLAUDE.md (komendy, konwencje, strukturę). Jeśli plik już istnieje,/initzaproponuje poprawki zamiast go nadpisywać. - •ClaudeMdGenerator w tym module — dobry, gdy chcesz przemyśleć plik sam, sekcja po sekcji: nazwa projektu, stack techniczny, struktura folderów, konwencje kodowania, zasady i ograniczenia.
Wynik: szkic do wklejenia do projektu. W obu przypadkach to punkt startu — dopisz to, czego z kodu nie da się wyczytać.
Pliki CLAUDE.md edytujesz też w trakcie sesji przez /memory. Tam zobaczysz również auto memory — notatki, które Claude zapisuje sam (np. twoje poprawki i preferencje) w osobnym katalogu projektu. Różnica: CLAUDE.md piszesz ty i jest wspólną umową; auto memory pisze Claude i zostaje na twoim komputerze. Jedno i drugie możesz przeglądać, edytować i czyścić.
Kiedy aktualizować CLAUDE.md
❌ Nie aktualizuj po każdej drobnostce. ✅ Aktualizuj gdy:
- •Claude drugi raz popełnia ten sam błąd albo drugi raz wpisujesz tę samą poprawkę
- •Zmienił się stos techniczny (nowy framework, baza)
- •Dodaliście nową konwencję nazewnictwa
- •Zmienił się design system (nowe kolory, komponenty)
- •Zmienił się proces deploymentu
- •Nowe ograniczenia lub zasady (bezpieczeństwo, performance)
Traktuj CLAUDE.md jako żywy dokument — ale krótki. Celuj w mniej niż ~200 linii na plik: długi plik zjada kontekst i obniża posłuszeństwo. Procedury wieloetapowe przenieś do skilli, zasady dla części kodu — do .claude/rules/. Pisz sprawdzalnie: „Uruchom npm test przed commitem" zamiast „testuj zmiany".
Wzorzec: Od ogólnego do konkretnego
code1. CLAUDE.md (stos, architektura, konwencje) ↓ 2. README.md (jak uruchomić, overview) ↓ 3. .claude/rules/ (zasady per temat / per ścieżka) ↓ 4. Inline comments (Why, not What)
Najpierw CLAUDE.md (kontekst ogólny, zawsze w kontekście), potem reguły dla konkretnych ścieżek — wczytywane, gdy Claude dotyka pasujących plików.
Praktyka: Copywriter produktowy
Maria pisze opisy produktów dla sklepu. Skonfigurowała CLAUDE.md:
markdown# EcoNest Store ## Brand Voice - Tone: warm, concrete, never pushy - Style: short sentences. Facts > adjectives. - Keywords: natural, sustainable, tested - Avoid: "best", "revolutionary", "you must have" ## Product Description Format headline (max 8 words) body (40-60 words) 3 key features as bullets
Przed: Maria za każdym razem opisuje markę w poleceniu → dostaje opis ogólnikowy → sporo poprawek.
Po: zasady marki żyją w CLAUDE.md → razem z Claude zaczynają od tonu i formatu marki → poprawki dotyczą treści, nie stylu.
Obserwacja zamiast obietnicy: ile czasu to oszczędza, zależy od twojej pracy. Sprawdź u siebie: policz poprawki przy pięciu opisach bez CLAUDE.md i pięciu z nim.