O autorze

Jakub Stankowski – programista .NET i Angular od 2018 roku. Pracował nad projektami frontendowymi, backendowymi i fullstackowymi, przestrzegając zasad czystego kodu, DRY i stosując CQRS. Ma również doświadczenie jako trener programowania.

Od 2023 roku intensywnie pracuje z Claude AI oraz metodą Spec-Driven Development (SDD) – produkcyjnym workflow do pracy z AI opartym na zasadzie: najpierw specyfikacja, potem implementacja. Na ProgramujZAI.pl dzieli się praktyczną wiedzą o tym, jak programować z AI bez chaosu w kodzie.

Poznaj Jakuba →

Błędy Claude Code najczęściej nie wynikają z samego modelu, tylko ze sposobu, w jaki go konfigurujesz i promptujesz. Pięć problemów wraca najczęściej: mgliste prompty bez kontekstu, brak pliku CLAUDE.md, uprawnienia ustawione na „zaakceptuj wszystko”, zerowy code review przed commitem i poleganie na AI bez specyfikacji. Każdy z nich da się naprawić w kilkanaście minut — poniżej pokazuję dokładnie jak.

Spis treści

• Błąd 1: prompty bez konkretnego celu i kryteriów akceptacji
• Błąd 2: brak kontekstu repo i pustego pliku CLAUDE.md
• Błąd 3: ignorowanie uprawnień plikowych i zakresu MCP
• Błąd 4: brak review przed commitem
• Błąd 5: over-reliance na AI bez Spec Driven Development
• Jak wdrożyć to w praktyce
• FAQ — najczęstsze pytania

Błąd 1: prompty bez konkretnego celu i kryteriów akceptacji

Prompt typu „napraw ten bug” albo „dodaj walidację formularza” zostawia Claude Code zbyt dużo swobody interpretacyjnej. Model wybierze najbardziej prawdopodobną interpretację, nie tę, którą masz w głowie — i właśnie w tym miejscu rodzi się większość poprawek do poprawek.

Jak to wygląda w praktyce

Efektem jest kod, który technicznie działa, ale ignoruje edge case’y, których nie wymieniłeś, albo zmienia więcej plików niż potrzeba, bo agent „dociągnął” kontekst po swojemu.

Jak to naprawić

• Podaj konkretny plik/funkcję zamiast ogólnego opisu problemu.
• Zdefiniuj kryteria akceptacji („testy X i Y muszą przechodzić”, „nie zmieniaj publicznego API”).
• Wskaż, czego NIE robić — negatywne przykłady ograniczają przestrzeń błędnych interpretacji równie skutecznie co pozytywne.
• Jeśli zadanie jest wieloetapowe, poproś najpierw o plan działania, a dopiero po jego akceptacji o implementację — to jedno zdanie różnicy w prompcie potrafi zaoszczędzić kilka rund poprawek.

Dobra zasada: jeśli prompt zmieściłby się w opisie zadania w Jirze bez dopytywania, prawdopodobnie jest wystarczająco konkretny dla Claude Code.

Błąd 2: brak kontekstu repo i pustego pliku CLAUDE.md

Plik CLAUDE.md ładuje się automatycznie na starcie każdej sesji i działa jak stała ściągawka o projekcie. Bez niego Claude Code za każdym razem od zera zgaduje konwencje nazewnictwa, strukturę katalogów i preferowane biblioteki.

Jak to wygląda w praktyce

Bez pliku kontekstowego dostajesz kod niespójny stylistycznie z resztą projektu — inny sposób obsługi błędów w każdym module, powtarzające się pytania o to, gdzie leży konfiguracja, i utratę decyzji podjętych w poprzedniej sesji.

Jak to naprawić

• Utwórz CLAUDE.md na poziomie projektu (nie tylko globalny w ~/.claude/) z konwencjami, strukturą i komendami build/test.
• Trzymaj plik krótki i konkretny — dokumentuj decyzje biznesowe i „dlaczego”, nie rzeczy, które model wywnioskuje sam z kodu.
• Aktualizuj go po każdej większej zmianie architektury, zamiast pozwalać mu się zdezaktualizować.

Warto rozróżnić dwa poziomy tego pliku: globalny w ~/.claude/CLAUDE.md to Twoje osobiste preferencje obowiązujące we wszystkich projektach, a projektowy — trzymany w repozytorium — to konwencje, które mają obowiązywać cały zespół i ładują się tylko wtedy, gdy pracujesz w danym katalogu. Mieszanie tych dwóch poziomów w jednym pliku to prosta droga do sytuacji, w której Twoje prywatne preferencje trafiają do repo współpracowników.

Błąd 3: ignorowanie uprawnień plikowych i zakresu MCP

Claude Code domyślnie pyta o potwierdzenie przy każdej operacji zapisu czy komendzie Bash — to jedyna prawdziwa linia obrony przed niechcianą zmianą. Włączenie trybu pomijającego uprawnienia bez sandboxa albo hurtowe dopuszczenie wszystkich narzędzi MCP usuwa tę linię obrony całkowicie.

Jak to wygląda w praktyce

Najczęstszy scenariusz to szeroka reguła allow na Bash, która przy okazji przepuszcza destrukcyjne komendy, albo serwer MCP podłączony z pełnym dostępem zapisu, podczas gdy zadanie wymagało tylko odczytu.

Jak to naprawić

• Skonfiguruj reguły allow/deny/ask w settings.json zamiast klikać „zaakceptuj zawsze” pod presją czasu — reguły deny zawsze wygrywają, niezależnie od trybu.
• Zablokuj jawnie odczyt plików z sekretami (.env, klucze API) niezależnie od pozostałych reguł.
• Dla serwerów MCP nadawaj minimalny zakres (np. tylko odczyt) — format reguły mcp__nazwa-serwera__narzędzie pozwala kontrolować to na poziomie pojedynczego narzędzia, nie całego serwera.
• Tryb pomijający uprawnienia zarezerwuj wyłącznie dla w pełni izolowanych środowisk (kontener, CI bez dostępu do sekretów produkcyjnych).

Praktyczny punkt startowy to plik projektowy .claude/settings.json z listą deny obejmującą pliki z sekretami i najbardziej ryzykowne komendy Bash, oraz osobny plik lokalny (niewersjonowany) na Twoje własne, szersze uprawnienia — dzięki temu zespół dzieli wspólne zabezpieczenia, a Ty nie tracisz wygody pracy na własnej maszynie.

Błąd 4: brak review przed commitem

Agentowy charakter Claude Code — czytanie, edycja, uruchamianie komend i tworzenie commitów w jednej pętli — kusi, żeby traktować go jak czarną skrzynkę. To błąd, który najszybciej mści się w kodzie produkcyjnym.

Jak to wygląda w praktyce

Bez review commity trafiają do repozytorium z niepotrzebnymi zmianami w plikach, których nikt nie prosił o dotykanie, z zduplikowaną logiką albo z testami, które przechodzą tylko dlatego, że asercje są zbyt luźne.

Jak to naprawić

• Używaj trybu planowania (plan mode) przy większych zmianach — model przedstawia plan przed wykonaniem, zamiast działać od razu.
• Poproś Claude Code o samodzielny diff-review przed commitem: „przejrzyj zmiany i wskaż, co wykracza poza zakres zadania”.
• Traktuj commit AI dokładnie tak jak PR juniora w zespole — czytasz diff, nie tylko wynik testów.
• Trzymaj commity małe i tematyczne — jeden commit na jedną logiczną zmianę ułatwia zarówno review, jak i ewentualny rollback pojedynczego kroku.

Zielone testy nie są dowodem poprawności, jeśli agent napisał zarówno kod, jak i testy do niego w tej samej sesji — dlatego przynajmniej część testów krytycznych ścieżek warto pisać ręcznie albo w osobnym przebiegu, zanim poprosisz o implementację.

Błąd 5: over-reliance na AI bez Spec Driven Development

Im większe zadanie, tym mocniej mści się brak specyfikacji przed implementacją. „Vibe coding” — pisanie promptu i akceptowanie tego, co wyjdzie — działa dobrze na małych, izolowanych zmianach i zaczyna się sypać w projektach wieloplikowych.

Jak to wygląda w praktyce

Bez specyfikacji model improwizuje architekturę w locie, a Ty odkrywasz rozjazd między tym, co miało powstać, a tym, co powstało, dopiero na etapie code review — czyli najdrożej, jak to możliwe.

Jak to naprawić

• Przed większym zadaniem spisz krótką specyfikację: cel, zakres, kryteria akceptacji, czego nie zmieniamy.
• Podziel duże zadania na etapy z checkpointami — review po każdym etapie, nie dopiero na końcu.
• Zero improwizacji nie znaczy zero elastyczności — specyfikacja ma być punktem odniesienia, nie sztywnym gorsetem.

W praktyce różnica jest odczuwalna już przy zadaniach na kilka plików: z krótką specyfikacją Claude Code trzyma się ustalonego zakresu, a bez niej regularnie „dokłada” refaktoryzacje, o które nikt nie prosił — bo z jego perspektywy to logiczne rozszerzenie zadania.

Jak wdrożyć to w praktyce

Poniższy checklist domyka wszystkie pięć błędów w jednej sesji porządkującej projekt. Całość zajmuje mniej czasu, niż wygląda na papierze — w praktyce da się to przejść w 30–45 minut na projekt, a efekt utrzymuje się przez wiele kolejnych sesji, bo konfiguracja jest jednorazowa, nie powtarzana przy każdym prompcie.

1. Stwórz lub zaktualizuj CLAUDE.md — konwencje, komendy build/test, struktura katalogów.
2. Skonfiguruj settings.json — jawne reguły allow/deny dla Bash i plików z sekretami.
3. Ogranicz zakres MCP — minimalne uprawnienia per narzędzie, nie per serwer.
4. Wprowadź krok review — diff-review przed każdym commitem generowanym przez agenta.
5. Zacznij pisać krótkie specyfikacje — nawet trzy zdania celu i kryteriów akceptacji przed promptem.

FAQ — najczęstsze pytania

Dlaczego Claude Code generuje zły kod?

Najczęściej dlatego, że prompt był zbyt ogólny i nie zawierał kryteriów akceptacji, albo projekt nie miał pliku CLAUDE.md z kontekstem — model wypełnia luki własnymi założeniami, które nie muszą pokrywać się z Twoimi.

Jak zabezpieczyć Claude Code przed przypadkowymi zmianami?

Skonfiguruj jawne reguły deny w settings.json dla plików z sekretami i destrukcyjnych komend Bash — reguły deny mają pierwszeństwo przed regułami allow niezależnie od trybu, w jakim pracujesz.

Czy warto używać trybu bypassPermissions?

Tylko w w pełni izolowanym środowisku — kontenerze albo pipeline CI bez dostępu do sekretów produkcyjnych. Na maszynie deweloperskiej z dostępem do kluczy SSH czy poświadczeń chmurowych to ryzyko nieproporcjonalne do zysku na wygodzie.

Jak połączyć Claude Code ze Spec Driven Development?

Zacznij od krótkiej specyfikacji przed promptem — cel, zakres, kryteria akceptacji — i trzymaj ją w pliku obok zadania. Więcej o samej metodologii i jej przewadze nad vibe codingiem znajdziesz w moim wcześniejszym artykule o Spec Driven Development.

Podsumowanie

Te pięć błędów łączy jedno: żaden nie wynika z ograniczeń samego modelu, tylko z pominięcia konfiguracji, która zajmuje kilkanaście minut. Kontekst w CLAUDE.md, jawne reguły uprawnień, review przed commitem i minispecyfikacja przed większym zadaniem to nie biurokracja — to różnica między Claude Code jako akceleratorem a Claude Code jako źródłem długu technicznego. Jeśli wdrażasz to pierwszy raz, zacznij od checklisty w sekcji powyżej i przerabiaj po jednym punkcie na projekt.

Więcej praktycznych warsztatów z Claude Code i Spec Driven Development pokazuję na moim kanale YouTube oraz na standev.it/ai-workflow-bonus.