Folder .claude w Claude Code: jak naprawdę działa architektura projektu

Czym jest folder .claude/ i dlaczego agent sprawdza go jako pierwsze

Folder .claude/ to katalog w rootcie projektu, który Claude Code traktuje jako swoją „instrukcję obsługi” konkretnego repozytorium. Nie jest to folder globalny – każdy projekt może mieć własne reguły, własne narzędzia i własnych subagentów. Agent skanuje ten katalog zanim zrobi cokolwiek innego.

Wyobraź sobie, że pracujesz jednocześnie nad API w Pythonie i frontendem w Next.js. Bez .claude/ agent nie wie nic o twoich konwencjach, preferowanym stylu testów ani o tym, że nigdy nie commituje się bezpośrednio do maina. Z .claude/ – wie to wszystko zanim napiszesz pierwsze słowo promptu.

Pełna struktura wygląda następująco:

• CLAUDE.md – główny plik reguł projektu, ładuje się przy każdym wywołaniu
• CLAUDE.local.md – prywatne nadpisania każdego developera, gitignored
• hooks/ – skrypty odpalane deterministycznie przy określonych zdarzeniach
• skills/ – konteksty domenowe ładowane na żądanie, nie przy starcie
• agents/ – subagenci z izolowanymi oknami kontekstu
• commands/ – slash commands (/ship, /review i inne)
• rules/ – reguły ładowane tylko dla konkretnych ścieżek plików (glob)
• output-styles/ – formatowanie odpowiedzi agenta
• plugins/ – nowość 2026: bundel komend, agentów i MCP w jednym pakiecie

Jeden szczegół, który często umyka: plik .mcp.json musi leżeć w rootcie projektu, nie wewnątrz .claude/. To jeden z najczęstszych błędów przy pierwszej konfiguracji. MCP definiuje serwery dostępne dla agenta – połączenia z bazą danych, zewnętrznym API, wewnętrznymi narzędziami firmy.

CLAUDE.md: plik reguł, który działa prawie zawsze

CLAUDE.md to główny plik instrukcji dla agenta. Trafia do kontekstu przy każdym wywołaniu – co oznacza, że każda zapisana tu reguła kosztuje tokeny, niezależnie od tego czy jest w danej chwili potrzebna. Limit 200 linii to nieoficjalna, ale sprawdzona zasada. Przekroczenie tego progu nie psuje niczego technicznie, ale przy intensywnym użytkowaniu szybko odbija się na kosztach i prędkości działania agenta.

Doświadczeni użytkownicy trzymają w CLAUDE.md tylko absolutne minimum: konwencje kodu, technologie projektu, rzeczy których agent nie powinien robić bez pytania. Reszta – do skills/.

I tu pojawia się rzecz, o której wiele tutoriali milczy: CLAUDE.md jest „advisory”. Agent może zignorować jego zawartość, jeśli sytuacja tego wymaga. To fundamentalna różnica w stosunku do hooków. Serio – wrócimy do tego za chwilę.

CLAUDE.local.md – personalizacja bez konfliktów w zespole

Każdy developer w zespole może mieć swój własny CLAUDE.local.md. Plik jest gitignored z definicji, więc twoje osobiste preferencje – np. „zawsze pytaj przed zapisem do bazy” albo „używaj tabów zamiast spacji” – nie trafiają do repozytorium i nie nadpisują ustawień kolegów. Proste rozwiązanie, a eliminuje dziesiątki zbędnych rozmów przy code review.

Hooks: jedyna część architektury, której agent nie może zignorować

Hooks to skrypty powłoki w katalogu hooks/. I to jedyna część całej architektury .claude/, która działa deterministycznie – odpala się zawsze, niezależnie od treści CLAUDE.md i niezależnie od tego co zrobi agent.

To nie jest sugestia dla Claude’a. To wymuszenie na poziomie systemu.

Trzy główne typy:

• PostToolUse.sh – odpala się po każdej edycji pliku przez agenta. Typowe zastosowania: automatyczny commit do gita, walidacja przez linter, powiadomienie w Slacku o zmianie w konkretnym module.
• SessionStart.sh – przy starcie każdej sesji. Tutaj sprawdzasz czy środowisko jest gotowe do pracy, ładujesz zmienne środowiskowe, weryfikujesz połączenia z zewnętrznymi serwisami.
• PreCompact.sh – przed kompresją kontekstu. Claude Code automatycznie kompresuje starsze fragmenty długich sesji; ten hook pozwala zapisać istotny stan zanim to nastąpi.

Tu robi się ciekawie. Wyobraź sobie agenta, który właśnie zrefaktoryzował 40 plików w twoim projekcie. PostToolUse.sh może automatycznie uruchomić testy po każdej zmianie i zatrzymać agenta, jeśli coś się posypie – zanim przejdzie do pliku numer 41. Bez hooka agent dowie się o problemie dopiero gdy zapytasz. Albo nie dowie się wcale.

Hook może zwrócić non-zero exit code, co natychmiast zatrzymuje wykonywanie bieżącego zadania przez agenta i zwraca mu informację o błędzie. To różni hooks od reguł w CLAUDE.md – tych drugich agent może po prostu nie zastosować.

Skills, agents i rules: zaawansowane zarządzanie kontekstem

Prawdziwa siła architektury .claude/ leży w tym, że nie ładuje wszystkiego naraz. Tu właśnie większość tutoriali się urywa.

Skills: kontekst na żądanie

Skills ładują się wyłącznie wtedy, gdy agent ich potrzebuje – nie przy starcie sesji. Projekt z 30 skillami zużywa tyle samo tokenów przy inicjalizacji co projekt z jednym. Właśnie to odróżnia skills od CLAUDE.md, który trafia do kontekstu zawsze, przy każdym wywołaniu.

Każdy skill to osobny folder z instrukcjami, przykładami i referencjami. Skill api-docs/ może zawierać szablon dokumentacji endpointów, przykłady dobrych i złych opisów oraz listę wymaganych pól. Agent sięgnie po ten skill tylko gdy pracuje z plikami dokumentacji – nie przy pisaniu testów, nie przy refaktorze modelu.

Agents: subagenci z izolowanym kontekstem

Katalog agents/ zawiera definicje subagentów – każdy z własnym, izolowanym oknem kontekstu. Subagent nie widzi historii rozmowy agenta-rodzica i nie dzieli z nim tokenów. Dla złożonych, wieloetapowych zadań to spora oszczędność.

Praktyczne przykłady z pliku konfiguracyjnego: code-reviewer.md analizuje diffy i zwraca podsumowanie bez zaśmiecania głównej sesji, researcher.md odpowiada za web fetch i syntezę zewnętrznych informacji, log-analyzer.md parsuje błędy i crash logi. Każdy robi jedno i robi to dobrze.

Rules: reguły dla konkretnych ścieżek

Katalog rules/ pozwala zdefiniować reguły ładowane tylko dla plików pasujących do wzorca glob. Plik api.md załaduje się wyłącznie gdy agent pracuje z plikami w src/api/** – nie przy froncie, nie przy migracjach, nie przy testach jednostkowych. Efekt: precyzyjniejsze reguły i mniejsze zużycie tokenów na każde wywołanie.

Porównanie elementów architektury – kiedy co stosować

Jak zbudować folder .claude/ od zera – co wdrożyć najpierw

Zamiast tworzyć od razu pełną strukturę (co jest pułapką, bo CLAUDE.md urośnie do 500 linii zanim zdążysz mrugnąć), zacznij od trzech kroków. To kolejność, która ma uzasadnienie.

1. Utwórz CLAUDE.md z minimum reguł – wypisz tylko to, co naprawdę boli: konwencje nazewnictwa, stos technologiczny, zakazy (np. „nigdy nie modyfikuj pliku schema.sql bez pytania”). Maksimum 50 linii na start. Resztę dodasz gdy agent zrobi coś nieoczekiwanego.
2. Dodaj jeden hook: PostToolUse.sh – choćby prostą walidację lintera po każdej zmianie pliku. To natychmiast pokaże ci wartość deterministycznych zachowań w praktyce. Jeden prosty skrypt robi więcej niż trzy strony reguł w CLAUDE.md.
3. Przenieś specjalistyczny kontekst do skills/ – wszystko co dotyczy konkretnego modułu lub technologii wyciągnij z CLAUDE.md do osobnego skill-folderu. CLAUDE.md powinien pozostać szczupły – reguły globalne, nic więcej.

Jeśli Twój projekt korzysta z zewnętrznych integracji, sprawdź też dostępne plugins/. W 2026 roku to first-class feature Claude Code – plugin bundluje komendy, agentów i konfigurację MCP w jednym pakiecie. Instalacja jedną komendą zamiast ręcznego składania wszystkiego z osobna.

I jeszcze raz: .mcp.json idzie do roottu projektu, nie do .claude/. Zapamiętaj to teraz, żeby nie debugować przez godzinę dlaczego agent nie widzi serwerów MCP.