CLAUDE.md to instrukcja dla Claude Code, ale jeśli jest za długa, model ignoruje połowę reguł. Tu opisuję, jak ją pisać, żeby faktycznie działała.

Powrót do głównego artykułu: Jak wymusić jakość w Claude Code

CLAUDE.md a settings.json

Myśl o tym tak:

  • settings.json określa, co Claude może robić (uprawnienia, model, narzędzia)
  • CLAUDE.md określa, co Claude powinien wiedzieć (konwencje, architektura, pułapki)

Settings kontroluje zachowanie. CLAUDE.md kontroluje wiedzę.

Gdzie Claude szuka CLAUDE.md

graph TD A["~/.claude/CLAUDE.md
Globalne, wszystkie projekty"] --> B["./CLAUDE.md
Root projektu, commitowany"] B --> C["./CLAUDE.local.md
Osobisty, git-ignored"] B --> D["./src/CLAUDE.md
Per-katalog, ładowany on-demand"]

Wszystkie pliki CLAUDE.md z powyższych lokalizacji są ładowane razem. Katalogi nadrzędne też, co przydaje się w monorepo (root/CLAUDE.md + root/packages/api/CLAUDE.md).

Budżet instrukcji: 150-200 reguł

To najważniejsza rzecz do zapamiętania. Claude Code ma prompt systemowy, który sam zajmuje ~50 instrukcji. Zostaje ci ~150 instrukcji, zanim przestrzeganie reguł zacznie spadać. Po przekroczeniu tego progu Claude zaczyna ignorować reguły. Nie celowo, po prostu gubi się w szumie.

Co z tego wynika: jeśli twój CLAUDE.md ma 500 linii, skróć go. Bezlitośnie.

Co wrzucać do CLAUDE.md

Reguły, których Claude nie może odgadnąć z kodu:

  • Komendy bash specyficzne dla projektu (npm run test:e2e, make proto)
  • Reguły stylu kodu, które różnią się od domyślnych (use spaces not tabs, 4-width)
  • Instrukcje testowania (always run pytest -x before committing)
  • Etykieta repo (squash merge only, prefix commits with JIRA-123)
  • Decyzje architektoniczne (we use repository pattern, not active record)
  • Pułapki (the CI uses Node 20, not 22; don't use Node 22 features)
  • Dziwactwa środowiska deweloperskiego (run docker compose up before testing)

Czego NIE wrzucać

Rzeczy, które Claude może sam wywnioskować:

  • Standardowe konwencje języka (PEP 8, Airbnb JS style)
  • Opisy plików po kolei (Claude czyta drzewo projektu)
  • Długie wyjaśnienia API (linkuj zamiast wklejać)
  • Informacje, które szybko się zmieniają
  • Rzeczy oczywiste z kodu

Test: jeśli Claude robi coś poprawnie BEZ instrukcji, nie dodawaj jej do CLAUDE.md. Zamień na hook.

Składnia importu

Zamiast wklejać 200 linii do CLAUDE.md, importuj:

Przeczytaj @README.md żeby zrozumieć strukturę projektu.
Konwencje Git: @docs/git-instructions.md
Osobiste overrides: @~/.claude/my-project-instructions.md

@ścieżka wstawia zawartość pliku w miejscu odwołania. Dobry sposób na rozbicie długiego CLAUDE.md na mniejsze, tematyczne pliki.

Wzmacnianie reguł

Claude lepiej respektuje reguły napisane mocnym językiem:

# Dobrze: jasny nakaz
IMPORTANT: Always run `npm run lint` before committing.
YOU MUST use conventional commit format.

# Źle: sugestia
It would be nice to run lint before commits.
Consider using conventional commits.

IMPORTANT i YOU MUST nie są magicznymi słowami, ale statystycznie poprawiają przestrzeganie reguł.

Wzorce pracy

Krótkie, skupione sesje

Konsensus na Reddicie: krótkie sesje biją długie maratony. Po 30-40 minutach kontekst się wypełnia i jakość spada. Zamiast ciągnąć jedną sesję godzinami:

  1. Zrób punkt kontrolny (commit)
  2. /clear albo zamknij i otwórz nową sesję
  3. Kontynuuj z czystym kontekstem

Plan Mode

Shift+Tab przełącza na Plan Mode (albo Ctrl+G otwiera plan w edytorze). W Plan Mode Claude:

  • Analizuje problem bez wykonywania zmian
  • Proponuje plan jako tekst
  • Czeka na twoje zatwierdzenie

Dobre na trudne zadania: zamiast pozwalać Claude’owi od razu pisać kod, najpierw ustalcie plan.

Wzorzec Writer/Reviewer

Dwie oddzielne sesje:

  1. Writer pisze kod
  2. Reviewer sprawdza go w osobnej sesji (z czystym kontekstem)

Reviewer nie ma kontekstu writera, więc ocenia kod „świeżym okiem”. Oba mogą pracować na tym samym repo.

Subagenty do badania

Zamiast kazać Claude’owi „zbadaj X” w głównej sesji (co zużywa kontekst), wpisz:

Użyj subagentów do zbadania jak działa moduł auth

Subagent działa w oddzielnym kontekście i zwraca skondensowany wynik.

Typowe błędy

Sesja-śmietnik

Mieszanie niepowiązanych zadań w jednej sesji. Rozwiązanie: /clear między tematami.

Poprawianie w kółko

Jeśli Claude 2+ razy nie trafia z poprawką, nie poprawiaj dalej. Rozwiązanie: /clear i lepszy prompt napisany od zera. Start od nowa ma większą skuteczność niż walka ze zdegradowaną sesją.

Przeładowany CLAUDE.md

Za dużo reguł, Claude ignoruje połowę. Rozwiązanie: wyrzuć wszystko, co Claude robi dobrze bez instrukcji. Tam, gdzie się da, zamień reguły na hooki.

Zaufanie bez weryfikacji

Claude mówi „gotowe”, a ty nie sprawdzasz. Rozwiązanie: zawsze podawaj testy lub sposób weryfikacji. „Uruchom npm test po zmianach” w CLAUDE.md.

Rekomendowany CLAUDE.md

Przykład zwięzłego, skutecznego CLAUDE.md:

# Projekt: nazwa-projektu

## Komendy
- `npm run dev`: dev server
- `npm run test`: testy (uruchom przed commitem)
- `npm run lint`: linting

## Konwencje
- Conventional Commits: feat/fix/docs/refactor
- TypeScript strict mode, bez any
- Testy w __tests__/ obok kodu

## Architektura
- Backend: FastAPI + PostgreSQL
- Frontend: Next.js 15 + Tailwind
- Monorepo z pnpm workspaces

## Pułapki
- CI wymaga Node 20, nie używaj API z Node 22
- Baza testowa wymaga `docker compose up db` przed testami
- IMPORTANT: nigdy nie commituj plików .env

@docs/api-conventions.md

~30 linii. Konkretne komendy, reguły, architektura, pułapki. Zero waty słownej.

Źródła