claude-code ai

Claude Code: CLAUDE.md i wzorce pracy

Jak pisać CLAUDE.md żeby Claude go nie ignorował. Workflow patterns, typowe błędy, rekomendacje community.

MO Maciej Olszewski ·

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 vs settings.json

Myśl o tym tak:

  • settings.json — co Claude może robić (uprawnienia, model, narzędzia)
  • CLAUDE.md — co Claude powinien wiedzieć (konwencje, architektura, gotchas)

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. Parent directories też — przydatne 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 compliance zaczyna 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)
  • Gotchas (the CI uses Node 20, not 22 — don't use Node 22 features)
  • Quirks ś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 się szybko 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 inline. Dobre do rozbicia długiego CLAUDE.md na mniejsze, tematyczne pliki.

Wzmacnianie reguł

Claude lepiej respektuje reguły z 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ą adherence.

Workflow patterns

Krótkie, skupione sesje

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

  1. Zrób checkpoint (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.

Writer/Reviewer pattern

Dwie oddzielne sesje:

  1. Writer — pisze kod
  2. Reviewer — sprawdza 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

Kitchen sink session

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

Poprawianie w kółko

Jeśli Claude 2+ razy nie trafia z poprawką — nie poprawiaj dalej. Fix: /clear, napisz lepszy prompt od zera. Zaczynanie od nowa ma wyższy success rate niż walka z degradowaną sesją.

Przeładowany CLAUDE.md

Za dużo reguł, Claude ignoruje połowę. Fix: wyrzuć wszystko co Claude robi dobrze bez instrukcji. Zamień reguły na hooki tam gdzie to możliwe.

Trust-then-verify gap

Claude mówi „gotowe” a ty nie sprawdzasz. Fix: 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

## Gotchas
- 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, gotchas. Zero fluffu.

Źródła

← Wszystkie artykuły