Procedury aktualizacji Claude Code

Zaczynasz dzień, uruchamiasz claude, by wrócić do wczorajszej gałęzi, a auto-aktualizacja w tle właśnie wgrała nową wersję minor. Twój hook pre-commit zwraca błąd, serwer MCP nie chce się połączyć, a twój zespół pracuje na trzech różnych buildach. Aktualizacje są rutyną, dopóki któraś nie zepsuje się w środku sprintu — ten przewodnik znów czyni je nudnymi, niezależnie od tego, czy instalujesz przez npm, natywnie czy z przypiętą wersją korporacyjną.

Co z tego wyniesiesz

• Listę kontrolną przed aktualizacją, która tworzy kopie zapasowe konfiguracji, które aktualizacja może faktycznie nadpisać.
• Poprawne komendy aktualizacji i cofnięcia dla każdego typu instalacji (natywna, npm, przypięta korporacyjnie).
• Gotowy do użycia prompt, który zamienia changelog w spersonalizowany plan migracji.
• Rutynę weryfikacji, która wychwytuje zepsuty hook lub serwer MCP, zanim zrobi to twój zespół.

Claude Opus 4.8 (maj 2026)

Opus 4.8 to obecny domyślny model

Claude Opus 4.8 (claude-opus-4-8, wydany 2026-05-28) jest teraz domyślnym modelem Claude Code. Domyślnie używa wysiłku high, a dla trudnych lub długotrwałych zadań dostępne są xhigh („extra”) oraz max. Dynamiczne przepływy pracy są dostarczane jako podgląd badawczy na świeżym buildzie z linii v2.1.x. Opus 4.8 współdzieli kształty żądań Messages API z Opus 4.7, więc przejście z 4.7 nie wymaga zmian w kodzie — poniższe uwagi migracyjne nadal obowiązują przy aktualizacji z Opus 4.6 lub wcześniejszych. Uruchom claude update, by uzyskać bieżące wydanie przed przypięciem Opus 4.8.

Migracja do Claude Opus 4.7 (kwiecień 2026)

Breaking changes w Claude Opus 4.7

Opus 4.7 (claude-opus-4-7, wydany 2026-04-16) wprowadza cztery breaking changes na poziomie Messages API. Claude Code ukrywa większość tego przed tobą, ale jeśli używasz Opus 4.7 przez SDK lub własne klienty API — lub przez bramki LLM jak LiteLLM — musisz zaktualizować kształty żądań. Użytkownicy Claude Managed Agents nie są dotknięci.

1. Usunięto extended thinking budgets

thinking: {"type": "enabled", "budget_tokens": N} zwraca teraz 400. Adaptive thinking to jedyny tryb thinking-on i jest wyłączone domyślnie na Opus 4.7.

# Przed (Opus 4.6)
thinking = {"type": "enabled", "budget_tokens": 32000}

# Po (Opus 4.7)
thinking = {"type": "adaptive"}
output_config = {"effort": "high"}  # lub "xhigh" dla najgłębszego rozumowania

2. Usunięto parametry samplingu

Ustawienie temperature, top_p lub top_k na wartość inną niż domyślna zwraca 400. Po prostu pomiń je — zamiast tego kieruj promptem na determinizm (uwaga: temperature=0 nigdy nie gwarantowała identycznego wyjścia).

# Przed
response = client.messages.create(model="claude-opus-4-6", temperature=0, ...)

# Po — pomiń parametry samplingu
response = client.messages.create(model="claude-opus-4-7", ...)

3. Zawartość myślenia domyślnie pomijana

Bloki myślenia są nadal emitowane, ale ich pole thinking jest puste, chyba że zrobisz opt-in. To cicha zmiana — ustaw display, aby przywrócić widoczne rozumowanie.

thinking = {
    "type": "adaptive",
    "display": "summarized",  # lub "omitted" (domyślne)
}

Wpływ na UX: jeśli twój produkt streamuje rozumowanie do użytkowników, nowe domyślne zachowanie wygląda jak długa pauza, zanim pojawi się wyjście. Użyj "summarized", aby przywrócić widoczny postęp podczas myślenia.

4. Nowy tokenizer (~1.0–1.35x użycie tokenów)

Opus 4.7 używa nowego tokenizera. Spodziewaj się od tej samej liczby do ~35% więcej tokenów w porównaniu z Opus 4.6, w zależności od kształtu workflow. /v1/messages/count_tokens zwróci inne liczby dla tego samego wejścia. Podnieś max_tokens o zapas — włącznie z progami kompakcji w Claude Code.

Opus 4.7 dostarcza pełny kontekst 1M w standardowej cenie API (bez premii long-context). W Claude Code wersje przed v2.1.117 liczyły kontekst względem okna 200K nawet przy używaniu Opus 4.7, powodując zawyżone procenty /context i wczesny autocompact. Zaktualizuj Claude Code do 2.1.117+ przed przypięciem Opus 4.7, aby uzyskać poprawkę.

Task budgets (beta)

Opus 4.7 dodaje opcjonalny task_budget jako miękki limit na całkowitą liczbę tokenów w pełnej pętli agentycznej (włącznie z myśleniem, wywołaniami narzędzi, wynikami narzędzi, finalnym wyjściem). W odróżnieniu od max_tokens, model widzi odliczanie i sam się moderuje.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[{"role": "user", "content": "Refactor the auth module."}],
    betas=["task-budgets-2026-03-13"],
)

Minimalna wartość to 20k tokenów. Pomiń ją przy otwartych zadaniach, gdzie jakość ma większe znaczenie niż wydatek tokenów.

Zmiany zachowania (nie API-breaking, ale warto wiedzieć)

• Bardziej dosłowne podążanie za instrukcjami — usuń rusztowania w stylu „dokładnie sprawdź X przed zwróceniem”; Opus 4.7 nie uogólnia już na elementy, o które nie prosiłeś.
• Długość odpowiedzi kalibruje się do złożoności zadania — spodziewaj się zwięźlejszego wyjścia na prostych pytaniach.
• Mniej wywołań narzędzi domyślnie, częściej korzysta z rozumowania — podnieś effort, aby zwiększyć użycie narzędzi.
• Bardziej bezpośredni, stanowczy ton — mniej fraz walidujących, mniej emoji.
• Mniej subagentów spawnowanych domyślnie — sterowalne przez prompting.

Deprecjacja Claude Sonnet 4 / Opus 4

Starsze modele Claude Sonnet 4 (claude-sonnet-4-20250514) i Claude Opus 4 (claude-opus-4-20250514) zostają wycofane 2026-06-15. Migruj odpowiednio do claude-sonnet-4-6 i claude-opus-4-7 przed tą datą. Szczegóły znajdziesz na stronie deprecjacji modeli Anthropic.

Zrozumienie ścieżek aktualizacji

Auto-aktualizacje (domyślnie)

Bezproblemowe aktualizacje w tle bez przestojów - zalecane dla większości użytkowników

Aktualizacje ręczne

Pełna kontrola nad czasem i testowaniem - idealne dla zespołów i przedsiębiorstw

Przypięcie wersji

Zablokowanie określonych wersji dla stabilności - wymagane w regulowanych środowiskach

Gotowość do cofnięcia

Zawsze utrzymuj możliwość powrotu - krytyczne dla środowisk produkcyjnych

Lista kontrolna przed aktualizacją

Przed każdą aktualizacją upewnij się, że jesteś przygotowany:

1. Sprawdź bieżącą wersję

   claude --version
   claude doctor  # Bardziej szczegółowa diagnostyka

2. Przejrzyj informacje o wydaniu

   github.com/anthropics/claude-code/releases

   # Sprawdź stronę wydań na GitHubie (lub changelog w produkcie)

   Wskazówka

   Prompt do skopiowania, który zamienia changelog w plan migracji. Uruchom go po tym, jak krok 1 pokaże twoją bieżącą wersję:

   I'm about to upgrade Claude Code from <CURRENT_VERSION> to <TARGET_VERSION>.
   Read the release notes at github.com/anthropics/claude-code/releases for every
   version between those two. List, in a table: (1) anything that changes the
   settings.json schema or default permissions, (2) any hook event renames or
   removed hook fields, (3) any .mcp.json / `claude mcp` changes, (4) any renamed
   or removed slash commands or CLI flags. For each, give the exact migration step.
   Then tell me which of my files to back up first.

3. Wykonaj kopię zapasową krytycznych konfiguracji

   # Kopia zapasowa konfiguracji
   cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)
   cp -r .claude .claude.backup.$(date +%Y%m%d)

4. Przetestuj w środowisku niekrytycznym

   • Użyj najpierw projektu testowego
   • Zweryfikuj, czy główne przepływy pracy nadal działają
   • Sprawdź niestandardowe komendy i hooki

5. Powiadom członków zespołu

   • Przekaż harmonogram aktualizacji
   • Podziel się wszelkimi przełomowymi zmianami
   • Skoordynuj czas dla minimalnego zakłócenia

Procedury aktualizacji według typu instalacji

Instalacja natywnego pliku binarnego to zalecana, obecna metoda (opisana poniżej). Ścieżka globalnej instalacji NPM jest przestarzała, ale nadal działa — zachowaj te komendy dla maszyn, których jeszcze nie zmigrowałeś.

Instalacja globalna NPM (przestarzała)

Notatka

Instalacja NPM jest przestarzała. Używaj metody instalacji natywnej, kiedy to możliwe — zobacz Instalacja natywnego pliku binarnego poniżej. Zmigruj istniejącą instalację npm za pomocą claude install.

Standardowa aktualizacja

# Sprawdź dostępne aktualizacje
npm outdated -g @anthropic-ai/claude-code

# Wykonaj aktualizację
npm update -g @anthropic-ai/claude-code

# Zweryfikuj aktualizację
claude --version

Czysta instalacja

# Czasami potrzebne dla dużych skoków wersji
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

Określona wersja

# Przypnij do określonej wersji
npm install -g @anthropic-ai/claude-code@1.0.54

# Zweryfikuj dokładną wersję
npm list -g @anthropic-ai/claude-code

Wskazówka

Problemy z uprawnieniami? Jeśli aktualizacja npm kończy się błędami uprawnień, rozważ migrację do instalacji lokalnej:

claude install

Instalacja natywnego pliku binarnego (zalecana)

Natywny instalator to obecny domyślny wariant i unika problemów z uprawnieniami właściwych dla globalnych instalacji npm. Instalacje natywne aktualizują się automatycznie w tle.

Update Binary

# Zaktualizuj istniejącą instalację
claude update

# Lub (ponownie) zainstaluj najnowszy build natywny
curl -fsSL https://claude.ai/install.sh | bash

# Potwierdź typ instalacji i wersję
claude doctor

Platform Notes

• macOS: Uniwersalny plik binarny, działa na Intel i Apple Silicon
• Linux: Automatyczne wykrywanie architektury
• Windows: Użyj WSL do instalacji binarnej

Obsługa przełomowych zmian

Przykład: identyfikatory modeli Bedrock

Gdy uruchamiasz Claude Code na Amazon Bedrock, model ustawia się przez zmienną środowiskową ANTHROPIC_MODEL. Częstym błędem przy aktualizacji jest użycie surowego, pozbawionego wersji ciągu modelu — Bedrock go odrzuca. Użyj identyfikatora profilu inferencji z prefiksem regionu i sufiksem wersji albo pełnego ARN profilu inferencji aplikacji. Stosuj ten schemat zawsze, gdy aktualizacja zmienia twój domyślny model:

1. Użyj poprawnego ciągu modelu Bedrock

   # Forma identyfikatora profilu inferencji (prefiks regionu + datowana wersja + -v1:0)
   export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'
   
   # Lub ARN profilu inferencji aplikacji
   export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-profile-id'

   Surowe foundation-model/anthropic.claude-... (bez prefiksu regionu, bez -vN:0) nie jest poprawnym identyfikatorem Bedrock. Przed przypięciem wyszukaj bieżący identyfikator profilu inferencji dla wybranego modelu w konsoli Bedrock.

2. Przetestuj konfigurację

   # Zweryfikuj, czy binding się rozwiązuje
   claude doctor

3. Kontynuuj aktualizację

   claude update

Typowe kategorie przełomowych zmian

Format konfiguracji

Zmiany struktury JSON, nowe wymagane pola, przestarzałe opcje

Zmiany API

Zmiany nazw pól SDK (np. total_cost → total_cost_usd)

Zmiany nazw narzędzi

Wbudowane narzędzia otrzymują jaśniejsze nazwy (np. LSTool → LS)

Zmiany komend

Slash komendy lub flagi zmodyfikowane lub przestarzałe

Strategia aktualizacji korporacyjnej

Kontrola wersji i testowanie

• Folderinfrastructure/

  • Folderclaude-code/

    • versions.json (zatwierdzone wersje)
    • Foldertest-suite/ (walidacja aktualizacji)

      • …
    • Folderrollback-scripts/

      • …
• Folderdocumentation/

  • upgrade-log.md
  • known-issues.md

Proces wdrażania etapowego

1. Środowisko deweloperskie

   • Testuj z ochotniczymi programistami
   • Uruchom przez 1-2 dni
   • Zbierz opinie

2. Środowisko stagingowe

   • Szersza grupa testowa
   • Pełna walidacja przepływu pracy
   • Benchmarking wydajności

3. Wdrożenie produkcyjne

   • Komunikuj przez kanały zespołowe
   • Stopniowo według zespołu/regionu
   • Monitoruj problemy

4. Przegląd po aktualizacji

   • Zbierz opinie zespołu
   • Dokumentuj wszelkie problemy
   • Aktualizuj procedury

Zarządzanie konfiguracją korporacyjną

# Wyłącz auto-aktualizacje w całej firmie
export DISABLE_AUTOUPDATER=1

# Przypinanie wersji w package.json
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "1.0.54"
  }
}

# Zautomatyzowany skrypt wdrażania
#!/bin/bash
APPROVED_VERSION="1.0.54"
CURRENT_VERSION=$(claude --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

if [ "$CURRENT_VERSION" != "$APPROVED_VERSION" ]; then
  npm install -g @anthropic-ai/claude-code@$APPROVED_VERSION
fi

Procedury cofnięcia

Gdy aktualizacja powoduje problemy, szybkie cofnięcie jest niezbędne:

Natychmiastowe cofnięcie

NPM Method

# Cofnij do poprzedniej wersji
npm install -g @anthropic-ai/claude-code@1.0.53

# Przywróć kopię zapasową konfiguracji
rm -rf ~/.claude
mv ~/.claude.backup.20250716 ~/.claude

Local Install

# Instalacje lokalne utrzymują historię wersji
cd ~/.claude/versions

# Wyświetl dostępne wersje
ls -la

# Przełącz na poprzednią wersję
ln -sf 1.0.53 current

Lista kontrolna cofnięcia

• ☐ Zatrzymaj wszystkie działające instancje Claude Code
• ☐ Przywróć poprzednią wersję
• ☐ Przywróć kopie zapasowe konfiguracji
• ☐ Wyczyść wszelki uszkodzony cache/stan
• ☐ Zweryfikuj funkcjonalność
• ☐ Dokumentuj problemy dla raportu błędów

Weryfikacja po aktualizacji

Po każdej aktualizacji zweryfikuj krytyczną funkcjonalność:

1. Podstawowa funkcjonalność

   # Sprawdź wersję i diagnostykę
   claude --version
   claude doctor
   
   # Przetestuj podstawową interakcję
   claude "Hello, are you working correctly?"

2. Integralność konfiguracji

   # Zweryfikuj zachowane ustawienia
   cat ~/.claude/settings.json
   
   # Sprawdź niestandardowe komendy
   ls .claude/commands/

3. Funkcjonalność narzędzi

   # Przetestuj operacje na plikach
   claude "List files in current directory"
   
   # Sprawdź serwery MCP (CLI w terminalu)
   claude mcp list

   Wewnątrz sesji interaktywnej uruchom zamiast tego /mcp — otwiera on interfejs statusu serwerów i zarządzania OAuth.

4. Sprawdzenie wydajności

   • Czas odpowiedzi
   • Użycie pamięci
   • Obsługa kontekstu

Rozwiązywanie typowych problemów z aktualizacją

Uszkodzenie konfiguracji

Uwaga

Jeśli Claude Code nie uruchamia się po aktualizacji, często przyczyną jest uszkodzenie konfiguracji.

# Diagnozuj problemy z konfiguracją
claude doctor

# Zresetuj do wartości domyślnych, jeśli potrzeba
mv ~/.claude/config.json ~/.claude/config.json.backup
claude # Odtworzy z wartościami domyślnymi

Błędy uprawnień

# Problemy z uprawnieniami NPM
sudo npm install -g @anthropic-ai/claude-code  # Niezalecane

# Lepsze rozwiązanie: migruj do lokalnej
claude install

Konflikty wersji

# Sprawdź wielokrotne instalacje
which -a claude
type -a claude

# Usuń duplikaty
npm uninstall -g @anthropic-ai/claude-code
# Następnie zainstaluj ponownie

Kompatybilność serwera MCP

Po głównych aktualizacjach serwery MCP mogą wymagać aktualizacji:

# Sprawdź status serwerów MCP (CLI w terminalu)
claude mcp list

# Aby zaktualizować serwer MCP, usuń go i dodaj ponownie.
# Separator -- jest wymagany dla serwerów stdio, by flagi Claude'a
# nie kolidowały z własną komendą i argumentami serwera.
claude mcp remove <server-name>
claude mcp add <server-name> -- <command> [args...]

Podsumowanie najlepszych praktyk

Zawsze twórz kopie zapasowe

Konfiguracji i niestandardowych komend przed każdą aktualizacją

Najpierw testuj

W izolowanym środowisku przed wdrożeniem zespołowym

Czytaj informacje o wydaniu

Zrozum zmiany i potencjalny wpływ

Koordynuj zespoły

Synchronizuj aktualizacje, aby uniknąć niezgodności wersji

Monitoruj po aktualizacji

Obserwuj zmiany wydajności lub nowe problemy

Dokumentuj wszystko

Prowadź dzienniki aktualizacji dla przyszłego odniesienia

Kontakty awaryjne

Jeśli podczas aktualizacji pojawią się krytyczne problemy:

1. GitHub Issues: Zgłaszaj błędy ze szczegółami wersji (wyjście claude doctor)
2. Discord: Sprawdź na Discordzie Claude Developers, czy inni trafiają na ten sam problem
3. Najpierw cofnij: Nie próbuj naprawiać do przodu w środowisku produkcyjnym
4. Dokumentuj dokładnie: Pomóż innym uniknąć tego samego problemu

Wskazówka

Prompt do skopiowania na smoke test po aktualizacji. Uruchom go w prawdziwym projekcie zaraz po aktualizacji:

I just upgraded Claude Code. Verify my setup is intact: read my settings.json and
.mcp.json, then check that (1) every configured MCP server connects, (2) my hooks
still fire on their events, and (3) my custom slash commands in .claude/commands/
still resolve. Report anything that broke and the smallest fix for each. Don't
change any files — just diagnose.

Co dalej

• Historia wersji Claude Code — śledź, co pojawiło się między twoimi wersjami.
• Funkcje beta i wczesny dostęp — włącz funkcje z podglądu badawczego, takie jak dynamiczne przepływy pracy.
• Bądź na bieżąco z Claude Code — pełny przepływ pracy zarządzania wersjami.