Rozwiązywanie problemów z sesją Claude Code

Rozwiązywanie problemów z sesją Claude Code polega na ustaleniu, która warstwa zawiodła, przed kolejną próbą: konfiguracja (ustawienia, reguły uprawnień, CLAUDE.md, serwery MCP, hooki), rozmowa (nieaktualny lub przepełniony kontekst) czy wynik (przerośnięty albo błędny diff). Claude Code ma narzędzie diagnostyczne dla każdej warstwy, a poprawka się liczy dopiero wtedy, gdy własne testy repozytorium znów przechodzą.

Ta strona jest dla programistów, którzy codziennie pracują z Claude Code, i dla tech leada, który odpowiada za wspólny plik .claude/settings.json zespołu. Masz regułę deny, a Claude i tak uruchomił polecenie. Albo model pomija konwencję zapisaną czarno na białym w CLAUDE.md, serwer MCP Sentry nie pokazuje żadnych narzędzi, a ostatni diff zamienił 20-liniowy serwis w fabrykę z trzema interfejsami. Żadnego z tych problemów nie rozwiąże powtórzenie tego samego promptu z większym naciskiem.

Jeśli dopiero zaczynasz pracę z Claude Code i potrzebujesz podstaw cofania edycji, zacznij od naprawiania błędów. Problemy z instalacją, logowaniem i komunikatami błędów we wszystkich narzędziach opisuje przewodnik po rozwiązywaniu problemów.

Co daje ci sprawdzona procedura diagnozowania Claude Code

• Triaż w pięciu poleceniach, który wskazuje zepsutą warstwę, zanim cokolwiek zmienisz
• Fakty o regułach uprawnień, które wyjaśniają, dlaczego reguła „nie działa”, oraz politykę do wklejenia
• Właściwy klawisz dla każdego rodzaju przerwania (Esc, Enter do kolejki, Ctrl+C) i to, co każdy z nich zachowuje
• Cztery prompty do skopiowania: triaż, audyt reguł, odchudzanie przerośniętego kodu i dowód, że naprawa działa
• Tabelę objaw → przyczyna → naprawa dla awarii, które faktycznie cię spotkają

Która warstwa się zepsuła? Triaż w pięciu poleceniach

Uruchom je, zanim zmienisz prompt albo ustawienie. Każde polecenie odpowiada na jedno pytanie, a wszystkie razem zajmują mniej niż minutę.

Pytanie	Gdzie uruchamiasz	Polecenie	Na co patrzeć
Czy instalacja jest sprawna?	Terminal	claude doctor	Stan instalacji i problemy w plikach ustawień, które czyta
Które reguły i tryby są aktywne?	Sesja	/permissions	Każda reguła i plik ustawień, z którego pochodzi; zakładka Recently denied z blokadami trybu auto
Które instrukcje się wczytały?	Sesja	/memory	Aktywne pliki CLAUDE.md i wpisy auto memory
Czy problemem jest kontekst?	Sesja	/context	Zapełniona siatka, rozdęta pamięć, narzędzia zużywające dużo kontekstu
Czy narzędzia i hooki są podłączone?	Sesja	/mcp, /hooks	Rozłączone lub nieuwierzytelnione serwery; hooki na oczekiwanym zdarzeniu

claude doctor to kontrola tylko do odczytu uruchamiana w terminalu; /doctor w sesji przeprowadza pełniejszy przegląd, który potrafi też naprawić znalezione problemy. Liczy się również claude --version: Claude Code wychodzi w kanałach latest i stable, a stable jest mniej więcej tydzień z tyłu, więc funkcji opisanej na tej stronie może jeszcze nie być w twojej instalacji (sprawdzone na v2.1.283, 2026-09-26).

Gdy triaż wskazuje na konfigurację, ale nie wiesz, który jej element zawinił, zawęź poszukiwania metodą bisekcji:

# Terminal: start z wyłączonymi CLAUDE.md, skillami, pluginami, hookami i serwerami MCP.
# Ustawienia zarządzane (policy), uwierzytelnianie, model i uprawnienia nadal działają.
claude --safe-mode

# Jeśli problem znika, siedzi w twoich dostosowaniach. Włącz logi debug tylko dla
# podejrzanych kategorii i zapisz je do pliku, który przeczytasz później.
claude --debug "api,hooks" --debug-file /tmp/claude-debug.log

W trwającej sesji wbudowany skill /debug włącza logowanie debug i sam czyta log sesji.

Prompt do skopiowania: triaż przed ponowną próbą

Stop. Do not edit any file in this turn. Tell me which layer is failing:
1. Configuration: list the settings files and CLAUDE.md files you loaded,
   and any permission rule, hook or MCP server that affected your last action.
2. Context: say what you currently believe the task is, the files you think
   matter, and anything from earlier in this conversation you may be relying on
   that is no longer true.
3. Output: summarise what you changed since my last message with `git diff --stat`
   and name the one change you are least sure of.
End with the smallest next step that would confirm which layer it is.

Dlaczego moja reguła uprawnień nie działa?

Większość zgłoszeń „Claude zignorował moją regułę” sprowadza się do czterech faktów z dokumentacji uprawnień (sprawdzone 2026-09-26, v2.1.283):

1. Kolejność to deny, potem ask, potem allow, a szczegółowość reguły jej nie zmienia. Szerokie Bash(aws *) w deny blokuje aws s3 ls, nawet jeśli zezwalasz też na Bash(aws s3 ls). Pasująca reguła ask wywołuje pytanie, nawet gdy pasuje węższa reguła allow.
2. Zakresy się sumują, a nie nadpisują. deny w ustawieniach użytkownika blokuje allow na poziomie projektu i odwrotnie. Ustawienia zarządzane wygrywają ze wszystkim, także z flagami wiersza poleceń.
3. Reguł nie egzekwuje model, tylko Claude Code. Zdanie „nigdy nie uruchamiaj migracji” w CLAUDE.md wpływa na to, co Claude próbuje zrobić, ale niczego nie blokuje. Blokadę umieść w permissions.deny albo w hooku PreToolUse.
4. Spacja przed końcowym * jest częścią reguły. Bash(ls *) pasuje do ls i ls -la, ale nie do lsof; Bash(ls*) pasuje też do lsof. Starsza końcówka Bash(ls:*) znaczy to samo co Bash(ls *), ale dwukropek w każdym innym miejscu to zwykły znak.

Najwięcej kosztują zespoły dwie pułapki. Po pierwsze, deny na Read(./.env) obejmuje narzędzia plikowe Claude’a, plikowe polecenia Bash, takie jak cat, head i sed, oraz przekierowania, ale nie polecenie, które czyta plik bez podania jego nazwy (grep -r API_KEY .), ani skrypt, który go otwiera (node -e …, python …). Trzymaj sekrety poza drzewem roboczym albo włącz Bash w sandboksie; zobacz uprawnienia i sandboksy. Po drugie, reguły ścieżek są sprawdzane tylko dla Read(...) i Edit(...): reguła zapisana jako Write(docs/**) zostanie przyjęta, ale nigdy nie zadziała, a Claude Code ostrzeże o tym przy starcie.

Polityka startowa do .claude/settings.json, którą możesz zacommitować dla całego zespołu:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm test *)",
      "Bash(npm run lint *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm install *)",
      "Bash(git clean *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Reguła deny dla Bash dopasowuje zapis, którego Claude zwykle używa, a nie sam program: rm -fr czy git push origin +main przejdą obok tych reguł, więc wszystko, co nie może się wydarzyć nigdy, zabezpiecz dodatkowo Bashem w sandboksie albo hookiem PreToolUse.

Reguły deny i ask dopasowują każde podpolecenie, także zagnieżdżone w cd /tmp && git clean -f czy w podstawieniu $( … ), więc git clean wywoła pytanie nawet w trybie auto. SQL w rodzaju DROP TABLE nie jest poleceniem Bash: destrukcyjne operacje na bazie blokuj w konfiguracji samego serwera MCP albo regułą ask na narzędziu, które je wykonuje.

Od v2.1.283 (oba kanały wydań na 2026-10-12) tryb auto jest trybem startowym interaktywnych sesji w terminalu i w VS Code: zamiast pytać ciebie, akcje ocenia klasyfikator. W trybie Manual startują natomiast sesje uruchomione przez claude -p lub Agent SDK (poza zewnętrznymi dostawcami i sesjami z wyłączoną telemetrią, gdzie od v2.1.285 startują w trybie auto), sesje, w których ustawienia wyłączają tryb auto, oraz sesje na modelu, którego tryb auto nie obsługuje. Jeśli klasyfikator zablokował akcję, która powinna przejść, otwórz /permissions, znajdź ją w zakładce Recently denied i naciśnij r, żeby ponowić ją z ręcznym zatwierdzeniem. Po 3 blokadach z rzędu albo 20 w jednej sesji tryb auto się wstrzymuje i Claude Code znów cię pyta, dopóki nie zatwierdzisz akcji; tych progów nie da się zmienić. Pamiętaj, że auto lub bypassPermissions jako defaultMode w ustawieniach projektu jest ignorowane; ustaw je w ustawieniach użytkownika albo zarządzanych.

Prompt do skopiowania: audyt, dlaczego reguła zadziałała albo nie

Read .claude/settings.json, .claude/settings.local.json and ~/.claude/settings.json.
For the command `npm run db:reset -- --force`, walk the rules in the order Claude
Code evaluates them (deny, then ask, then allow, across all scopes) and tell me
which rule matches first and what the outcome is. Then list any rule that can
never match: path rules on Write or Glob, a missing space before a trailing *,
or an allow shadowed by a broader deny. Propose the minimal edit; do not apply it.

Uwaga

--dangerously-skip-permissions wyłącza wszystkie kontrole. Pomoc samego CLI zaleca tę flagę wyłącznie dla sandboksów bez dostępu do internetu: jednorazowego kontenera albo roboczego klonu, nigdy twojej maszyny do pracy.

Dlaczego Claude pomija mój CLAUDE.md?

Zacznij od /memory. Trzy przyczyny wyjaśniają większość przypadków:

• Plik się nie wczytał. Claude Code czyta AGENTS.md tylko wtedy, gdy projekt nie ma CLAUDE.md, i dopiero od v2.1.277 (od v2.1.281 na Bedrock, Google Cloud, Foundry, bramkach LLM i instalacjach z wyłączoną telemetrią). Repozytorium z oboma plikami dostaje wyłącznie CLAUDE.md.
• Instrukcja ginie w tłumie. CLAUDE.md na 600 linii konkuruje o uwagę z całą resztą kontekstu. Regułę, która wciąż umyka, przenieś na początek pliku, a jeśli nie wolno jej złamać nigdy, zamień ją w hook. Zobacz system pamięci.
• Reguła wypadła przy kompaktowaniu albo czyszczeniu. Po długiej sesji /compact streszcza rozmowę i ograniczenie podane w czacie (a nie w CLAUDE.md) może tego nie przetrwać. Trwałe reguły trzymaj w pliku, nie w rozmowie.

Jak zatrzymać Claude’a, nie tracąc sesji

Stara rada „nigdy nie naciskaj Ctrl+C, bo zabijesz sesję” jest błędna. Według dokumentacji trybu interaktywnego (sprawdzone 2026-09-26):

Klawisz	Gdy Claude pracuje	Gdy Claude czeka
Esc	Zatrzymuje odpowiedź lub wywołanie narzędzia w trakcie tury; dotychczasowa praca zostaje	Zamyka okno dialogowe
Wpisz, potem Enter	Dodaje wiadomość do kolejki; Claude dostaje ją, gdy tylko skończą się bieżące wywołania narzędzi, w tej samej turze	Wysyła wiadomość
Esc Esc	—	Z tekstem w polu: czyści je (strzałka w górę przywraca tekst z historii). Przy pustym polu: otwiera menu przewijania (rewind)
Ctrl+Enter	Wysyła wiadomości z kolejki od razu, bez czekania (v2.1.275 lub nowsza; Ctrl+X Ctrl+S w terminalach, które nie zgłaszają rozszerzonych klawiszy)	—
Ctrl+C	Przerywa bieżącą operację	Pierwsze naciśnięcie czyści pole, drugie zamyka Claude Code

Wybieraj według tego, co chcesz zachować:

• Claude idzie dobrą drogą, ale brakuje mu ograniczenia. Wpisz je i naciśnij Enter. Wiadomość trafia do kolejki, a nie przerywa pracy: „Keep the v1 response shape; mobile clients still call it.” Wiadomość z kolejki, która dołącza do trwającej tury, nie dostaje własnego checkpointu, więc cofnięcie jej oznacza cofnięcie całej tury. Zmieniasz zdanie, zanim Claude ją przeczyta? Naciśnij strzałkę w górę w pierwszej linii pola, a wiadomości z kolejki wrócą do pola wpisywania.
• Claude zmierza w złą stronę. Naciśnij Esc i podaj korektę. Dotychczasowe edycje zostają na dysku, więc zanim pójdziesz dalej, sprawdź /diff.
• Całe podejście jest złe. Naciśnij Esc, a potem Esc Esc przy pustym polu, żeby cofnąć kod i rozmowę do punktu sprzed próby. Menu przewijania szczegółowo opisuje przewodnik po naprawianiu błędów.
• Chcesz o coś zapytać, nie zmieniając kierunku pracy. Użyj /btw: odpowiada na pytanie poboczne, nie dodając go do rozmowy.

Jak sprawić, by nieudaną próbę Claude Code łatwo było cofnąć

Checkpointy cofają edycje wykonane narzędziami plikowymi Claude’a, ale nie pliki zmienione poleceniami Bash (rm, mv, generator kodu) ani przez subagentów (poza forkiem skilla działającym na pierwszym planie), także przez /code-review --fix uruchomiony w tle, a ich migawki są domyślnie sprzątane po około 30 dniach. Git to checkpoint, który obejmuje wszystko. Pętla, dzięki której nieudana próba kosztuje niewiele:

1. Zacommituj bieżący stan przed każdą zmianą, która dotyka więcej niż jednego pliku.

   git add -p && git commit -m "checkpoint: before extracting billing adapter"

   git add -p dodaje zmiany fragment po fragmencie, więc przypadkowy .env czy artefakt builda się nie prześlizgnie.

2. Zleć zmianę razem z kryterium akceptacji w prompcie: „Done means npm test and npm run typecheck pass and no file outside src/billing/ changes.”

3. Oceniaj wynik po testach, a nie po czytaniu kodu. Jeśli po dwóch próbach testy nadal nie przechodzą albo git diff --stat pokazuje pliki spoza zakresu zadania, przestań łatać do przodu.

4. Zresetuj i napisz nowy prompt z tym, czego się dowiedziałeś.

   git reset --hard HEAD   # usuwa każdą niezacommitowaną zmianę, także twoją

   Potem uruchom /clear i wyślij węższy prompt, który nazywa ograniczenie pominięte w pierwszej próbie.

Dwie nieudane próby naprawy to sygnał. Trzecia zwykle buduje na błędach dwóch poprzednich, a kontekst mieści już wszystkie trzy.

Co zrobić, gdy Claude przekombinuje rozwiązanie

Przerost ma rozpoznawalny kształt: fabryka albo rejestr z jednym produktem, interfejs z jedną implementacją, opcja konfiguracji, o którą nikt nie prosił, nowa zależność do zadania na dziesięć linii. git diff --stat pokazuje to, zanim przeczytasz choć linię: liczba plików i linii jest nieproporcjonalna do prośby.

Prompt do skopiowania: odchudź przerośniętą zmianę

This change is over-engineered for what we need. Collapse it to the simplest
version that keeps the current tests passing: remove any factory, registry or
singleton with a single product, inline any interface with one implementer, and
drop options nobody calls. Do not add dependencies. Run the test suite and
typecheck, then show `git diff --stat` against HEAD and one line per thing you
removed that we might want back later.

Następnemu razowi zapobiegnij regułą w CLAUDE.md, na podstawie której model może działać, a nie hasłem:

## Scope rules
- Add an abstraction only when there are two real callers today.
- No new dependency without asking first.
- If a change touches more than 5 files, stop and propose a plan before editing.

Tryb planowania (/plan) robi to samo dla pojedynczego ryzykownego zadania: Claude bada kod i proponuje rozwiązanie, nie edytując plików źródłowych, a ty zatwierdzasz plan, zanim trafi do kodu jakakolwiek zmiana.

Jak udowodnić, że naprawiona praca jest poprawna

Naprawa jest skończona, gdy mówią to dowody, a nie gdy diff wygląda wiarygodnie. Sprawdzaj w tej kolejności, od najtańszego:

1. Zasięg zmian. git diff --stat i /diff: zmieniły się tylko pliki wskazane w zadaniu.
2. Bramki. Jedno polecenie sprawdzające repozytorium (testy, typecheck, lint) przechodzi lokalnie. Jeśli repozytorium nie ma takiego polecenia, to pierwsza rzecz do naprawy; zobacz jak przygotować repozytorium do pracy agentów.
3. Niezależny przegląd. /code-review przegląda bieżący diff pod kątem błędów poprawności jako osobny przebieg, który wyłapuje to, co sesja pisząca kod sama sobie wmówiła.
4. Akceptacja. Akceptujesz na podstawie dowodów. Sam kod czytasz tylko w tych klasach zmian, które twój zespół zastrzegł dla człowieka, zgodnie z czytaniem dowodów zamiast kodu.

Prompt do skopiowania: udowodnij naprawę przed commitem

Before I commit, prove this change is safe without me reading every line:
1. Run the full test suite, the typecheck and the linter; paste the summary lines.
2. Show `git diff --stat` and flag any file outside the scope I gave you.
3. For each behaviour I asked for, name the test that exercises it, or say
   "untested" and write that test now.
4. List anything you changed that no test covers.
Do not stage or commit anything.

Gdy sesja Claude Code się sypie: objawy i naprawy

Objaw	Prawdopodobna przyczyna	Naprawa
Zablokowane polecenie i tak się wykonało	Reguła dla złego narzędzia (reguła ścieżki dla Write/Glob) albo bez spacji przed *; polecenie dotarło do pliku bez podania jego nazwy (grep -r, skrypt) albo miało inny zapis (rm -fr zamiast rm -rf)	Uruchom prompt audytu reguł; przenieś sekrety poza drzewo albo włącz Bash w sandboksie
Dozwolone polecenie wciąż pyta	Szersza reguła ask lub deny w innym zakresie	/permissions pokazuje plik źródłowy każdej reguły; usuń albo zawęź szerszą regułę
Odpowiedzi dryfują albo powtarzają stare błędy	Kontekst pełen nieudanych prób	Potwierdź w /context, potem /compact z fokusem („keep only the billing refactor decisions”) albo /clear i start od nowa
/clear usunął coś potrzebnego	Za wczesne czyszczenie	/rewind przywraca rozmowę sprzed /clear w tym samym procesie; /resume wybiera wcześniejszą sesję
Serwer MCP nie pokazuje narzędzi	Serwer z .mcp.json czeka na zatwierdzenie albo wygasł OAuth	claude mcp list oznacza oczekujące serwery; /mcp, by zatwierdzić lub uwierzytelnić ponownie (albo claude mcp login <name> w terminalu); /mcp reconnect <server>; zobacz konfigurację MCP
Hook nigdy się nie uruchamia	Zła nazwa zdarzenia lub matcher; błąd hooka	/hooks pokazuje, co jest zarejestrowane; claude --debug "hooks"; zobacz automatyzację hookami
Autocompact is thrashing: the context refilled to the limit...	Jeden plik lub wynik narzędzia zapełnia okno zaraz po każdym kompaktowaniu	Poproś o plik w zakresie linii albo po funkcji, /compact keep only the plan and the diff albo przenieś pracę na dużym pliku do subagenta
Tryb auto nagle pyta o wszystko	Klasyfikator zablokował 3 akcje z rzędu albo 20 w sesji, więc tryb auto się wstrzymał	Sprawdź zakładkę Recently denied w /permissions; zatwierdź następną bezpieczną akcję, żeby wznowić tryb auto, albo zawęź zadanie
Sesja zawiesza się i nie reaguje na klawisze	Zawieszone wywołanie narzędzia albo terminal	Ctrl+C; jeśli nie pomoże, zamknij terminal i uruchom claude --continue w tym samym katalogu (albo claude --resume, żeby wybrać sesję): rozmowa zostaje zachowana
Limit użycia w połowie zadania	Długie sesje z wysokim poziomem rozumowania (/effort)	/usage pokazuje koszt sesji i limity planu; obniż /effort, zanim zmienisz model; zobacz kontrolę kosztów
Ta sama poprawka zawodzi dwa razy	Łatanie do przodu na błędnym założeniu	Stop, git reset --hard do checkpointu, /clear, nowy prompt z pominiętym ograniczeniem

O modelach: Claude Opus 5.5 jest domyślnym modelem Claude Code (oba kanały wydań na 2026-10-12) i działa z poziomem rozumowania (effort) ustawionym na medium. Gdy trudne zadanie utknie, podnieś ten poziom poleceniem /effort high, zanim zmienisz model, a rutynową pracę przenieś na Claude Sonnet 5.5 tylko wtedy, gdy decyduje koszt. Aktualne ceny i limity są w przeglądzie modeli.

Dokąd dalej po rozwiązaniu problemów z Claude Code

• Utrwal poprawki dla całego zespołu: współpraca w zespole omawia wspólne ustawienia, CLAUDE.md i domyślne zasady przeglądu.
• Porównaj tryby uprawnień i sandboksy z Codexem i Cursorem: uprawnienia i sandboksy.
• Obserwuj sesje w dłuższym okresie: monitorowanie Claude Code i kontrola kosztów.
• Błędy w twojej aplikacji, a nie w sesji: debugowanie z Claude Code.
• Jeśli trafiłeś na błąd w samym Claude Code, zgłoś go Anthropic poleceniem /feedback w sesji i opisz kroki, które go odtwarzają.