Co rano tłumaczysz swój stack Claude Code, on zapomina o twoich konwencjach po trzecim promptcie, a dwóch kolegów z zespołu dostaje różne wyniki z tego samego repozytorium. Rozwiązaniem jest dobrze dopracowany CLAUDE.md: trwała pamięć, która ładuje się na początku każdej sesji, więc Claude trzyma się twoich wzorców bez powtarzania ich w kółko. Zrobiony źle, CLAUDE.md staje się jednak ścianą tekstu na 600 linii, którą model po cichu ignoruje.
CLAUDE.md (i tego, gdzie naprawdę mieszka pamięć użytkownika)CLAUDE.md z twojego repozytorium, sprawdzą go pod kątem sprzeczności i skompresują rozdęty plik do zwięzłych regułPliki CLAUDE.md służą jako system trwałej pamięci Claude Code. W przeciwieństwie do historii konwersacji, która jest czyszczona, te pliki są automatycznie ładowane na początku każdej sesji, zapewniając spójny kontekst o twoim projekcie.
Kluczowe korzyści
Pliki CLAUDE.md mogą być umieszczone na wielu poziomach hierarchii twojego projektu. Claude Code automatycznie je odkrywa i priorytetyzuje na podstawie szczegółowości:
# W repozytorium (pod kontrolą wersji)project-root/├── CLAUDE.md # Kontekst całego projektu├── frontend/│ └── CLAUDE.md # Wytyczne specyficzne dla frontendu├── backend/│ └── CLAUDE.md # Wzorce specyficzne dla backendu└── src/ └── components/ └── CLAUDE.md # Konwencje na poziomie komponentów
# W twoim katalogu domowym (NIE w repozytorium)~/.claude/CLAUDE.md # Osobiste preferencje dla wszystkich projektów~/.claude/projects/.../CLAUDE.local.md # prywatny, per-projekt, ignorowany przez gitPliki CLAUDE.md są addytywne: każdy pasujący poziom dokłada swoją treść do kontekstu Claude naraz. Nie ma sztywnego rankingu numerowanego — gdy dwa pliki są sprzeczne, Claude używa osądu, aby je pogodzić, a bardziej szczegółowe instrukcje zwykle wygrywają z ogólniejszymi. Poziomy, które mogą się dokładać:
/Library/Application Support/ClaudeCode/CLAUDE.md na macOSCLAUDE.md, plus dowolny CLAUDE.md w katalogach nadrzędnych edytowanego pliku./.claude/rules/*.md (modułowe, zawężone tematycznie; ładowane jako pamięć projektu)~/.claude/CLAUDE.md (twoje osobiste preferencje dla każdego projektu)./CLAUDE.local.md (ignorowana przez git, tylko ty na tym repozytorium)Pliki w katalogach nadrzędnych ładują się w całości przy starcie; pliki w katalogach podrzędnych ładują się na żądanie, gdy Claude czyta plik w tym katalogu. (Sztywna, deterministyczna kolejność — gdzie jedna definicja całkowicie nadpisuje inną — dotyczy umiejętności, subagentów i serwerów MCP, a nie pamięci CLAUDE.md).
# Przegląd projektu
To jest platforma e-commerce zbudowana z Next.js i Node.js.
## Architektura- Frontend: Next.js 14 z App Router- Backend: Node.js z Express- Baza danych: PostgreSQL z Prisma ORM- Uwierzytelnianie: JWT z tokenami odświeżania- Zarządzanie stanem: Zustand
## Kluczowe zasady- TypeScript dla całego nowego kodu- Komponenty funkcyjne z hookami- RESTful API design- Kompleksowa obsługa błędów# Wytyczne frontendu
## Struktura komponentów- Używaj komponentów funkcyjnych z TypeScript- Interfejsy Props zdefiniowane nad komponentem- Niestandardowe hooki w katalogu `/hooks`- Wspólne komponenty w `/components/shared`
## Stylowanie- Tailwind CSS do wszystkich stylów- Żadnych inline styles poza dynamicznymi wartościami- Wymagane wsparcie trybu ciemnego- Projektowanie mobile-first responsive# Osobiste preferencje
## Styl kodu- Preferuj wczesne zwroty zamiast zagnieżdżonych warunków- Używaj opisowych nazw zmiennych (bez skrótów)- Komentarze dla "dlaczego", nie "co"- Maksymalna długość linii: 100 znaków
## Przepływ pracy Git- Format konwencjonalnych commitów- Squash commitów przed mergowaniem- Zawsze twórz gałęzie funkcjiClaude Code może automatycznie wygenerować kompleksowy plik CLAUDE.md, analizując twój projekt:
claude/initTa komenda:
/init daje solidny szkielet, ale bywa generyczny. Po wygenerowaniu podaj mu poniższy prompt, aby osadzić go w tym, jak twoje repozytorium naprawdę działa, a nie w tym, co sugeruje drzewo plików.
Uruchamiaj /init ponownie okresowo w miarę ewolucji projektu, a następnie ponownie odpal prompt tworzący plik, aby odświeżyć przeterminowane sekcje.
Dołącz często używane komendy i skrypty, aby zmniejszyć przełączanie kontekstu:
# Częste komendy
## Rozwój- `npm run dev` - Uruchom serwer deweloperski (port 3000)- `npm run build` - Buduj na produkcję- `npm run test` - Uruchom zestaw testów- `npm run test:watch` - Uruchom testy w trybie obserwacji- `npm run lint` - Uruchom ESLint z auto-fix- `npm run typecheck` - Uruchom sprawdzanie kompilatora TypeScript
## Baza danych- `npm run db:migrate` - Uruchom oczekujące migracje- `npm run db:seed` - Zasiej dane deweloperskie- `npm run db:reset` - Resetuj bazę danych (UWAGA: destrukcyjne)- `npm run db:studio` - Otwórz Prisma Studio
## Wdrażanie- `npm run deploy:staging` - Wdrażanie na staging (wymaga VPN)- `npm run deploy:prod` - Wdrażanie na produkcję (wymaga zatwierdzenia)
## Niestandardowe skrypty- `./scripts/generate-types.sh` - Generuj typy TypeScript z API- `./scripts/analyze-bundle.sh` - Analizuj rozmiar bundla webpack- `./scripts/update-deps.sh` - Interaktywny aktualizator zależnościProfesjonalna wskazówka
Dołącz kontekst o tym, kiedy i dlaczego używać każdej komendy, nie tylko co robią.
Dokumentuj jasno standardy kodowania i preferencje swojego zespołu:
# Wytyczne stylu kodu
## TypeScript- **ZAWSZE** używaj jawnych typów zwracanych dla funkcji- **ZAWSZE** definiuj interfejsy dla propsów komponentów- **PREFERUJ** type nad interface dla unii i prymitywów- **UNIKAJ** typu any - używaj unknown i zawężania typów
Przykład:\`\`\`typescript// Dobrze:interface ButtonProps { label: string; onClick: () => void; variant?: 'primary' | 'secondary';}
const Button: React.FC<ButtonProps> = ({ label, onClick, variant = 'primary' }) => { return <button className={styles[variant]} onClick={onClick}>{label}</button>;};
// Źle:const Button = ({ label, onClick, variant }: any) => { return <button onClick={onClick}>{label}</button>;};\`\`\`
## Organizacja importów1. Zewnętrzne zależności2. Wewnętrzne aliasy (~/)3. Importy relatywne (./)4. Importy stylów
Przykład:\`\`\`typescriptimport React, { useState, useEffect } from 'react';import { useRouter } from 'next/router';
import { api } from '~/lib/api';import { Button } from '~/components/ui';
import { formatDate } from './utils';import styles from './Component.module.css';\`\`\`
## Obsługa błędów- Używaj niestandardowych klas błędów- Zawsze loguj błędy z kontekstem- Dostarczaj przyjazne dla użytkownika komunikaty błędów- Dołączaj error boundaries dla komponentów ReactDokumentuj praktyki zespołu i przepływy pracy, aby zapewnić spójność:
# Etykieta repozytorium
## Przepływ pracy Git1. **Nazewnictwo gałęzi**: `feature/opis`, `fix/opis`, `chore/opis`2. **Komunikaty commitów**: Podążaj za konwencjonalnymi commitami - `feat:` Nowa funkcja - `fix:` Naprawa błędu - `docs:` Tylko dokumentacja - `style:` Zmiany stylu kodu - `refactor:` Refaktoryzacja kodu - `test:` Zmiany testów - `chore:` Zmiany procesu budowy lub narzędzi pomocniczych
## Proces Pull Request1. **Samodzielny przegląd**: Najpierw przejrzyj własne PR2. **Opis**: Użyj szablonu PR, podłącz do issue3. **Testy**: Wszystkie testy muszą przejść4. **Zrzuty ekranu**: Dołącz dla zmian UI5. **Rozmiar**: Utrzymuj PR poniżej 400 linii, gdy to możliwe
## Wytyczne Code Review- Bądź konstruktywny i konkretny- Sugeruj ulepszenia, nie tylko krytykuj- Używaj "my" zamiast "ty" w komentarzach- Zatwierdzaj z "LGTM" (Looks Good To Me)
## Strategia merge- **Squash and merge** dla gałęzi funkcji- **Rebase** do aktualizacji gałęzi funkcji- **Bez merge commitów** w głównej gałęziPomóż Claude zrozumieć twoje środowisko deweloperskie:
# Środowisko deweloperskie
## Wymagania wstępne- Node.js 18.x lub wyżej (użyj nvm)- PostgreSQL 14.x- Redis 6.x (do cache)- Docker Desktop (opcjonalnie, dla kontenerów)
## Początkowa konfiguracja1. Klonuj repozytorium: `git clone <repo-url>`2. Zainstaluj zależności: `npm install`3. Skopiuj zmienne środowiskowe: `cp .env.example .env`4. Skonfiguruj plik .env: - DATABASE_URL: String połączenia PostgreSQL - REDIS_URL: String połączenia Redis - JWT_SECRET: Wygeneruj za pomocą `openssl rand -base64 32` - API_KEY: Uzyskaj od lidera zespołu5. Uruchom migracje: `npm run db:migrate`6. Zasiej bazę danych: `npm run db:seed`7. Uruchom rozwój: `npm run dev`
## Zmienne środowiskowe- **Rozwój**: Użyj .env.local (git-ignored)- **Testowanie**: Użyj .env.test- **Produkcja**: Ustaw na platformie wdrażania
## Znane problemy- Gorące przeładowanie może zawieść na Windows - uruchom ponownie serwer deweloperski- Port 3000 koliduje z innymi usługami - zmień w .env- Połączenia z bazą danych mogą się wyczerpać - zwiększ rozmiar puliDokumentuj pułapki i nieoczywiste zachowania:
# Ważne ostrzeżenia
## Względy wydajności- **Strona listy produktów**: Limit do 50 elementów ze względu na wydajność- **Przesyłanie obrazów**: Automatycznie kompresowane, max 5MB- **Indeksowanie wyszukiwania**: Działa asynchronicznie, może trwać 30 sekund- **Invalidacja cache**: Wymagane ręczne wyzwolenie dla niektórych operacji
## Uwagi bezpieczeństwa- **Klucze API**: Nigdy nie commituj do repozytorium- **Dane użytkowników**: PII musi być szyfrowane w spoczynku- **Przesyłanie plików**: Waliduj typy MIME po stronie serwera- **Zapytania SQL**: Używaj wyłącznie zapytań parametryzowanych
## Częste pułapki1. **Zarządzanie stanem** - Nie mutuj stanu Zustand bezpośrednio - Używaj immer do złożonych aktualizacji
2. **Wywołania API** - Zawsze obsługuj stany ładowania i błędu - Używaj AbortController do czyszczenia
3. **Zapytania do bazy danych** - N+1 zapytania częste w panelu użytkownika - Używaj includes dla powiązanych danych
4. **Testowanie** - Mockuj zewnętrzne usługi - Resetuj bazę danych między zestawami testówNajtańszy moment na zapisanie reguły pamięci to chwila, w której poprawiasz Claude. Dwa udokumentowane sposoby, by zrobić to bez wychodzenia z REPL:
# Po prostu powiedz Claude wprost, zwykłym językiem:remember that we use pnpm, not npmsave to memory that API tests require a local Redis instance
# Albo uruchom selektor plików pamięci, aby samodzielnie edytować plik:/memoryGdy poprosisz Claude, by coś zapamiętał, wybiera on najtrafniejszy plik pamięci i dopisuje regułę we właściwej sekcji. Użyj /memory, gdy chcesz otworzyć plik i edytować go ręcznie, w tym swój punkt wejścia auto-pamięci.
Częste zastosowania:
Traktuj treść CLAUDE.md tak jak prompty - bądź konkretny i używaj podkreśleń:
# Wytyczne
Używaj TypeScript dla plików.
Podążaj za style guide.
Pisz testy.# Krytyczne wytyczne
**ZAWSZE** używaj TypeScript ze strict mode włączonym dla WSZYSTKICH plików.
**MUSISZ** podążać za style guide Airbnb z naszymi modyfikacjami:- 2 spacje wcięcia (NIE tabulatory)- Wymagane średniki- Przecinki na końcu w wieloliniowych
**WYMAGANE** dla każdej funkcji:- Testy jednostkowe z >80% pokryciem- Testy integracyjne dla endpointów API- Testy E2E dla krytycznych ścieżek użytkownika
**NIGDY**:- Używaj słowa kluczowego var (użyj const/let)- Commituj instrukcji console.log- Wyłączaj reguły ESLint bez komentarzaSkuteczne wzorce instrukcji:
Większość plików CLAUDE.md psuje się tak samo: reguły są ze sobą sprzeczne, martwe instrukcje zalegają po zmianie kodu, a plik rozrasta się ponad punkt, w którym model niezawodnie się go trzyma. Odpal te dwa prompty na swoim obecnym pliku w świeżej sesji (najpierw /clear, aby wcześniejszy kontekst nie zaburzał przeglądu).
Po przejrzeniu wyników poproś Claude o przepisanie pliku — ale ogranicz go, bo inaczej znów go rozdmie.
Następnie rozpocznij nową sesję i potwierdź, że przycięty plik nadal jest respektowany przy reprezentatywnym zadaniu.
Lista kontrolna optymalizacji
CLAUDE.md daje dużą dźwignię, co oznacza, że jego scenariusze awarii łatwo przeoczyć, dopóki jakość wyjścia po cichu nie spadnie. Zwykli winowajcy:
./.claude/rules/*.md.CLAUDE.md w katalogu podrzędnym (lub plik .claude/rules/) może być sprzeczny z głównym. Bardziej szczegółowy wygrywa, więc zapomniana reguła frontendu może po cichu nadpisać twój standard projektu. Gdy zachowanie jest niespójne między katalogami, sprawdź cały łańcuch, nie tylko korzeń.pages/ po migracji do app/, albo komenda, która została przemianowana, wysyła Claude z pewnością w złym kierunku. Odpalaj prompt sprawdzający za każdym razem, gdy kończysz refaktoryzację lub zmieniasz nazwy skryptów.CLAUDE.md mówi “100% pokrycia testami”, a repozytorium siedzi na 40%, Claude albo będzie marudził przy każdej zmianie, albo po cichu zignoruje regułę. Dokumentuj to, co jest prawdą teraz; cele śledź gdzie indziej.Najbardziej skuteczne pliki CLAUDE.md mają wspólne cechy:
Z dobrze zoptymalizowanymi plikami CLAUDE.md zapewniającymi kontekst jesteś gotowy opanować interfejs linii poleceń. Przejdź do Mistrzostwo w linii poleceń, aby nauczyć się istotnych komend i skrótów produktywności.