---
title: "Claude Code: CLAUDE.md i wzorce pracy"
description: "Jak pisać CLAUDE.md, żeby Claude go nie ignorował. Wzorce pracy, typowe błędy, rekomendacje społeczności."
author: Maciej Olszewski
date: 2026-05-07
tags:
  - claude-code
  - ai
url: "https://inprojects.ai/blog/claude-code-claude-md-i-workflow/"
language: pl
---

# Claude Code: CLAUDE.md i wzorce pracy

> Jak pisać CLAUDE.md, żeby Claude go nie ignorował. Wzorce pracy, typowe błędy, rekomendacje społeczności.

> 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](https://inprojects.ai/blog/claude-code-wymuszanie-jakosci/)

## 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

```mermaid
graph TD
    A["~/.claude/CLAUDE.md<br/>Globalne, wszystkie projekty"] --> B["./CLAUDE.md<br/>Root projektu, commitowany"]
    B --> C["./CLAUDE.local.md<br/>Osobisty, git-ignored"]
    B --> D["./src/CLAUDE.md<br/>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:

```markdown
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:

```markdown
# 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:

```markdown
# 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

- [Claude Code best practices, oficjalna dokumentacja](https://code.claude.com/docs/en/best-practices)
- [32 Claude Code Tips, Agentic Coding](https://agenticcoding.substack.com/p/32-claude-code-tips-from-basics-to)
- [50 Claude Code Tips, Builder.io](https://www.builder.io/blog/claude-code-tips-best-practices)
- [Claude Code Reddit, podsumowanie](https://www.morphllm.com/claude-code-reddit)
- [Thinking triggers, kentgigger.com](https://kentgigger.com/posts/claude-code-thinking-triggers)
- [Effort parameter, kentgigger.com](https://kentgigger.com/posts/claude-code-effort-parameter)