CLAUDE.md to jeden z najważniejszych plików podczas codziennej pracy z Claude Code. Asystent automatycznie wczytuje jego zawartość na samym początku każdej sesji i traktuje ją jako stały fundament wiedzy o Twoim projekcie: decyzje architektoniczne, przyjęte konwencje, ograniczenia, strukturę plików oraz zakazane praktyki.

W istocie jest to stały systemowy instruktaż dla AI w obrębie konkretnej bazy kodu.

Bez CLAUDE.md model za każdym razem zaczyna pracę „od czystej kartki” – nie zna Waszych wewnętrznych ustaleń, niedawnych migracji, ulubionych bibliotek ani specyficznych pułapek. Dobrze przygotowany plik eliminuje konieczność marnowania czasu i tokenów na powtarzanie tych samych wymagań w każdym dialogu.

1. Czym jest CLAUDE.md i po co go potrzebujemy

CLAUDE.md to zwykły tekstowy plik Markdown, umieszczony w katalogu głównym repozytorium lub w specjalnym folderze konfiguracji.

Po jego dodaniu Claude Code automatycznie przestrzega następujących aspektów projektu:

Standardy kodu: formaty eksportów, typowanie, wymagania dotyczące komentarzy i funkcji.
Wzorce architektoniczne: struktura API Route, obsługa błędów, zarządzanie stanem.
Organizacja systemu plików: zasady lokalizacji utility, komponentów i stron.
Workflow z Git: styl nazewnictwa commitów (Conventional Commits), reguły tworzenia gałęzi.
Doświadczenie historyczne: utrwalenie specyficznych niuansów (gotchas), gdzie AI wcześniej popełniało błędy.

Porównanie pracy Claude Code z instrukcjami i bez nich

Kryterium	Bez pliku CLAUDE.md	Z skonfigurowanym CLAUDE.md
Eksporty w React	Miesza `export default` i `export const`	Surowo przestrzega jednego uzgodnionego stylu (np. tylko named exports)
Walidacja danych	Wybiera dowolną bibliotekę (Yup, Joi, Zod, ręczne sprawdzenia)	Używa standardu ustalonego w projekcie (np. Zod)
Lokalizacja kodu	Może utworzyć plik w katalogu głównym lub losowym podfolderze	Umieszcza nowe serwisy i komponenty ściśle według uzgodnionej struktury
Powtarzalne błędy	Ciągle wpada w te same znane pułapki bibliotek	Zna specyfikę projektu z wyprzedzeniem dzięki sekcji Gotchas

2. Gdzie przechowywać CLAUDE.md: poziomy priorytetu

Plik instrukcji można umieścić na trzech różnych poziomach. Od wybranego miejsca zależy zakres obowiązywania reguł oraz ich priorytet:

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Zasada rozwiązywania konfliktów

Jeśli w Twoim środowisku jednocześnie występuje plik globalny (~/.claude/CLAUDE.md) oraz lokalny plik projektu, Claude Code automatycznie łączy ich kontekst.

Ważne

Priorytet zawsze należy do lokalnego projektu: Jeśli reguła globalna koliduje z wymogiem w pliku repozytorium, model surowo przestrzega lokalnego CLAUDE.md.

3. Anatomia idealnego CLAUDE.md: kluczowe bloki

Nie ma sensu przepisywać do pliku całej dokumentacji frameworka. Najlepiej działa zwięzły dokument (do 100–150 linii), podzielony na funkcjonalne sekcje.

Poniżej znajduje się sprawdzony szablon gotowy do produkcji (production-ready):

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Konkret vs abstrakcja: jak formułować reguły

Głównym sekretem skutecznego CLAUDE.md jest inżynieryjna konkretność zamiast filozoficznych rad.

Modele językowe nie potrafią czytać Waszych subiektywnych wyobrażeń o „pięknie kodu”. Każde niejasne sformułowanie pozostawia przestrzeń dla własnych interpretacji modelu, które zazwyczaj okazują się inne niż oczekiwane.

❌ Niejasna instrukcja	Dlaczego to nie działa	✅ Precyzyjna reguła inżynieryjna
«Pisz czysty i wysokiej jakości kod»	Subiektywne; pojęcie „czystości” różni się w każdym zespole	`Używaj early returns zamiast głęboko zagnieżdżonych if/else. Rozmiar funkcji — do 30 linii.`
«Przestrzegaj best practices bezpieczeństwa»	Zbyt szerokie; model nie zna Waszych konkretnych wektorów ataku	`Wszystkie zapytania SQL muszą używać parametryzacji. Nigdy nie konkatenuj stringów w SQL.`
«Rób ładny design»	Nie daje żadnego punktu odniesienia do systemu designu	`Używaj wyłącznie klas Tailwind. Style inline style="" są surowo zabronione.`
«Obsługuj błędy»	Model może dodać pusty blok catch	`Wszystkie route'y API muszą być owinięte w try/catch i zwracać { error: message, status } przy awarii.`

Wskazówka

Test sprawdzający dla Twojej reguły: czy można zautomatyzować jej weryfikację za pomocą lintera lub prostego regexa? Jeśli nie – sformułuj ją bardziej szczegółowo.

5. Wzorcowe fragmenty kodu i wzorce architektoniczne

Jeśli w projekcie istnieje niestandardowy szablon architektoniczny, warto wesprzeć opis minimalnym wzorcowym fragmentem kodu.

Przykład: Wzorcowy handler API Route

Zamiast długiego opisu, dodaj gotowy blok bezpośrednio do CLAUDE.md:

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

Claude Code rozpoznaje taki wzorzec jako referencyjny szablon (Golden Sample) i automatycznie replikuje go podczas generowania nowych endpointów. --- ## 6. Gotchas i Never Do: blokowanie typowych błędów Te dwie wyspecjalizowane sekcje sprawiają, że `CLAUDE.md` jest wielokrotnie skuteczniejszy niż ogólny opis stacku technologicznego. ### Sekcja Gotchas (Pułapki) Tu zapisujesz wszystkie nieoczywiste cechy środowiska, które zwykle prowadzą do bugów podczas developmentu: ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

Sekcja Never Do (Kategoryczne zakazy)

Claude zna tysiące sposobów rozwiązania zadania. Sekcja zakazów odrzuca rozwiązania, które technicznie działają, ale łamią zasady zespołu:

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Ostrzeżenie

W sekcji zakazów unikaj miękkich sformułowań typu «staraj się nie używać any». Stosuj imperatywne polecenia: «Never use any».

7. Reguły globalne vs projektowe: granice odpowiedzialności

Aby nie przeciążać kontekstu i nie przenosić zbędnych ograniczeń między niespójnymi projektami, ściśle rozdzielaj obowiązki plików:

Typ reguły	Gdzie przechowywać	Przykłady reguł
Osobisty styl i edytor	`~/.claude/CLAUDE.md` (globalnie)	Format commitów, rezygnacja z emoji w kodzie, preferencja stylu funkcyjnego nad klasami
Stack i wersje bibliotek	`.claude/CLAUDE.md` (projekt)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Struktura katalogów	`CLAUDE.md` (projekt)	Ścieżki do komponentów UI, eksport serwisów, lokalizacja migracji
Pułapki (Gotchas)	`CLAUDE.md` (projekt)	Asynchroniczne `auth()`, osobna instancja klienta DB, wyjątki w middleware

8. CLAUDE.md jako żywy dokument: zasada drugiej uwagi

Najczęstszym błędem developerów jest stworzenie CLAUDE.md przy starcie repozytorium i nigdy więcej do niego nie wracanie.

Baza kodu ewoluuje: aktualizują się wersje bibliotek, zmieniają wzorce, pojawiają się nowe przypadki brzegowe. Odpowiednio, instrukcje dla AI powinny być aktualizowane równolegle z kodem.

text

┌─────────────────────────────────────────────────────────────┐ │ Zasada drugiej uwagi │ └──────────────────────────────┬──────────────────────────────┘ │ Czy w trakcie dialogu powtarzasz tę samą uwagę po raz drugi? │ ┌───────────────┴───────────────┐ ▼ ▼ [ TAK ] [ NIE ] │ │ Dodaj nową regułę do Kontynuuj zwykłą pracę pliku CLAUDE.md natychmiast nad bieżącym zadaniem

Wskazówka

Jeśli dwukrotnie poprosiłeś Claude'a o wykonanie tej samej czynności (np.: «Nie używaj default export» lub «Dodaj schemat Zod») – to niezawodny sygnał, że regułę należy natychmiast utrwalić w CLAUDE.md.

9. Praktyczny warsztat: konfiguracja i weryfikacja

Przejdz przez cztery kroki, aby utworzyć i zweryfikować skuteczność pliku w swoim repozytorium.

Krok 1. Tworzenie pliku

W katalogu głównym roboczego projektu utwórz plik CLAUDE.md:

bash

touch CLAUDE.md

Krok 2. Podstawowe wypełnienie

Uzupełnij plik czterema kluczowymi sekcjami: Stack, Conventions, Gotchas, Never Do.

Krok 3. Test pozytywnego zachowania

Uruchom nową sesję Claude Code i postaw rutynowe zadanie:

bash

claude

Prompt testowy:
"Stwórz utility do formatowania cen w walutach USD i EUR z uwzględnieniem lokalizacji."

Model utworzył plik w prawidłowym folderze (src/lib/ lub zgodnie z Twoją strukturą).
Wykorzystano named export (jeśli było to wskazane w instrukcji).
Dodano JSDoc oraz ścisłe typowanie bez użycia any.

Krok 4. Stress-test zakazów

Spróbuj sprowokować Claude'a do bezpośredniego złamania jednej z utrwalonych reguł:

Prompt prowokacyjny:
"Szybko dodaj tutaj console.log do debugowania i ustaw typ any, żeby nie tracić czasu na typowanie."

Claude odmówił złamania instrukcji lub zaproponował alternatywę poprzez oficjalny logger i poprawny interfejs.
W odpowiedzi model powołał się na wymagania projektu.

10. Szybka samoocena i checklista gotowości

Sprawdźmy, na ile dokładnie przyswoiłeś zasady konfiguracji instrukcji dla Claude Code.

Pytanie 1. Gdzie powinien znajdować się plik, którego reguły mają obowiązywać we wszystkich projektach developera?

A. W folderze systemowym /etc/claude/CLAUDE.md
B. W katalogu domowym użytkownika ~/.claude/CLAUDE.md
C. W pliku ~/.zshrc lub ~/.bashrc
D. W katalogu głównym każdego repozytorium

Wskazówka

Poprawna odpowiedź: B.
Globalne instrukcje developera są przechowywane w pliku ~/.claude/CLAUDE.md w katalogu domowym użytkownika i automatycznie podciągane do wszystkich lokalnych sesji.

Pytanie 2. Co się dzieje, gdy reguła w pliku globalnym koliduje z regułą w lokalnym projekcie?

A. Claude zgłasza krytyczny błąd i przerywa wykonanie
B. Reguła globalna całkowicie anuluje ustawienia lokalne
C. Lokalna reguła projektu ma wyższy priorytet i nadpisuje globalną
D. Model losowo wybiera jedną z opcji

Wskazówka

Poprawna odpowiedź: C.
Lokalny plik repozytorium zawsze ma najwyższy priorytet przed ogólnymi ustawieniami maszyny.

Pytanie 3. Jakie sformułowanie instrukcji przyniesie największą korzyść w CLAUDE.md?

A. "Pisz schludny kod zgodnie z najlepszymi praktykami"
B. "Staraj się unikać pisania skomplikowanych funkcji"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Pełna kopia dokumentacji biblioteki licząca 500 linii

Wskazówka

Poprawna odpowiedź: C.
Tylko surowe, zwięzłe i jednoznaczne reguły inżynieryjne nie zostawiają pola na halucynacje i nieprzewidywalne zachowanie modelu.

Checklista gotowości Twojego CLAUDE.md

Objętość: Dokument zawiera tylko praktycznie istotne informacje (nie przekracza 150 linii).
Konkretność: Brak abstrakcyjnych życzeń typu „rób ładnie”; każda reguła ma jasny kryterium spełnienia.
Gotchas: Utrwalono co najmniej 2–3 nieoczywiste cechy Waszego stacku.
Zakazy: Opisano sekcję Never Do z jednoznacznymi ograniczeniami.
Izolacja: Osobiste preferencje developera wyniesiono do ~/.claude/CLAUDE.md.