Siedem błędów w pliku CLAUDE.md, które potajemnie pogarszają jakość wyników generowanych przez Claude Code.

To właśnie w tych wątpliwościach kryją się złe konfiguracje. Żadnych błędów, żadnych ostrzeżeń – tylko niejasny, ogólny i częściowo błędny kod, sesja po sesji. Niejasny lub przeciążony plik nie tylko nie pomaga, ale także pochłania zasoby i przeszkadza w wykonywaniu rzeczywistych zadań. Dlatego zanim zmienisz choćby jedną linię, dokładnie przeczytaj, co się tam znajduje, a następnie naprawiaj problemy po kolei.

Błąd 1: niejasny opis stosu

Linia taka jak Używamy Reacta i bazy danych. nie mówi Claude’owi prawie nic. Będzie zgadywał, że chodzi o router Next.js, wybierze bibliotekę do zarządzania stanem mniej więcej losowo i pisać testy w frameworku, którego nie używasz. Wynik może się skompilować, ale nadal nie będzie pasował do twojej bazy kodu.

Zamiast tego opisz dokładnie:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Dokładne wersje i konwencje to to, co przekształca ogólne wyniki w kod, który wygląda tak, jakby należał do twojego repozytorium. Podaj ich nazwy.

Błąd 2: brak ograniczeń, brak zasady „nigdy tego nie rób”

To najczęstszy ukryty błąd. Ludzie opisują projekt, ale nigdy nie wyznaczają jasnych granic. Bez ograniczeń Claude uruchamia npm w projekcie pnpm, edytuje utworzone pliki oraz przerabia kod, o którym nigdy nie wspomniano. To nie są halucynacje – to rozsądne przypuszczenia, które powstają, ponieważ żadna zasada tego nie zabrania.

Dodaj blok z ograniczeniami:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Zasady dotyczące tego, czego nie wolno robić, dają większe korzyści niż same opisy, ponieważ zapobiegają kosztownym błędom jeszcze przed ich wystąpieniem.

Błąd 3: ignorowanie agentów i podagentów

Większość plików CLAUDE.md jest pisana tak, jakby jeden model pracował samodzielnie, bez żadnych wskazówek dla specjalistycznych subagentów działających równolegle z główną sesją. Jeśli używasz subagentów do testowania, dokumentacji lub wdrażania, należy to odnotować w pliku: wymień każdego agenta, obszar, za który jest odpowiedzialny, oraz sytuacje, w których główny agent powinien przekazać mu zadanie.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Jeśli nadal projektujesz model delegacji, pomocne jest zrozumienie, w jaki sposób różnią się umiejętności, subagenci, polecenia typu slash oraz MCP, zanim podjąć ostateczną decyzję co do struktury.

Błąd 4: przeciążony plik, który zużywa cały budżet kontekstu

Zbyt wiele nie oznacza lepszej jakości. Plik CLAUDE.md składający się z 2000 linii, wypełniony pełnymi przewodnikami stylu, dokumentacją API oraz rejestrami zmian, ładuje wszystko to przy każdej sesji, niezależnie od tego, czy jest to istotne, czy nie. To utrudnia wykonywanie rzeczywistych zadań, a ponieważ uwaga pogarsza się w obecności zbyt dużo informacji, otrzymujemy model, który technicznie przeczytał twoje zasady, ale nadal nie stosuje ich w sposób wiarygodny.

Ogranicz się do tego, co najważniejsze. Wskazuj pliki lub konkretne umiejętności, aby uzyskać szczegóły, zamiast je wklejać. Zasada dotycząca jednego pakietu powinna znajdować się w pliku specyficznym dla tego pakietu, a nie w katalogu głównym. Zlicz tokeny w pliku przed i po redukcji, aby upewnić się, że działania te przyniosły efekt.

Błąd 5: instrukcje, których Claude nie może wykonać

Weź na przykład Napisz czysty, łatwy w utrzymaniu i wysokiej jakości kod. Claude już uważa, że to robi, więc niejasne przymiotniki nic nie zmieniają. Zastąp je zasadami, które można sprawdzić:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Zasady operacyjne dają modelowi mierzalny cel. Frazy aspiracyjne nie dostarczają mu żadnego celu.

Błąd 6: przestarzałe zasady sprzeczne z kodem

Problem z plikiem CLAUDE.md jest rzeczywisty. Załóżmy, że sześć miesięcy po przeniesieniu się zespołu na Zustand plik nadal podaje „use Redux”. Taka zasada nie pozostaje bez wpływu – doprowadza do konfliktu pomiędzy ustawieniami konfiguracji a faktycznym kodem, a Claude nie potrafi zdecydować, komu wierzyć.

Przeglądaj plik za każdym razem, gdy zależności ulegną znacznym zmianom, i uwzględnij ten przegląd w liście kontrolnym PR. Zachowaj go w Git, aby móc zobaczyć, kiedy ostatnio zmieniono każdą zasadę. Przestarzały plik CLAUDE.md często jest gorszy niż jego całkowity brak.

Błąd 7: jeden ogromny plik tekstowy

W monorepo pojedynczy, nieuporządkowany plik CLAUDE.md sprawia, że Claude stosuje zasady frontendu do kodu backendu i odwrotnie. Gdy wszystko stanowi jeden nierozróżniony blok, nie ma możliwości określenia kontekstu.

Umieść globalne zasady w pliku root CLAUDE.md, a pliki specyficzne dla poszczególnych pakietów lub usług dodaj osobno. W pliku głównym używaj jasnych nagłówków sekcji:

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

Struktura wskazuje Claude’owi, które zasady mają zastosowanie gdzie.

Szybka weryfikacja i lista kontrolna

Przestań zgadywać i ocenij plik pod kątem czterech kryteriów: specyficzności, ograniczeń, struktury i rozmiaru. Porównanie z dobrze skonstruowanym wzorem również pomaga, ponieważ pokazuje, jak wygląda dobry plik w praktyce.

Rozważ następujące pytania:

• Czy podano dokładne wersje frameworków i bibliotek?
• Czy istnieje sekcja z ograniczeniami zawierająca surowe zasady typu „nigdy tego nie rób”?
• Czy wymieniono, jakie agenty istnieją i co każdy z nich obsługuje?
• Czy plik ma mniej niż 200 wierszy, a szczegóły są przeniesione do odpowiednich umiejętności lub powiązanych plików?
• Czy wszystkie instrukcje są konkretne i realizowalne, a nie jedynie aspiracyjne?

Czy ktoś sprawdzał je pod kątem przestarzałych zasad w ciągu ostatnich 30 dni?

Czy jest podzielone na nagłówki, czy też na pliki specyficzne dla poszczególnych pakietów, jeśli używasz monorepo?

Odpowiedz „nie” na więcej niż dwa z tych pytań, a twoje CLAUDE.md prawdopodobnie kosztuje cię więcej, niż oszczędza.