Bezpieczne procedury aktualizacji

Aktualizacja Claude Code wymaga starannego planowania i wykonania, szczególnie w środowiskach zespołowych lub korporacyjnych. Ten przewodnik przedstawia kompleksowe procedury bezpiecznych, niezawodnych aktualizacji z minimalnym zakłóceniem przepływu pracy.

Migracja do Claude Opus 4.7 (kwiecień 2026)

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 opt-in. To cicha zmiana — ustaw display aby przywrócić widoczne rozumowanie.

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

Wpływ UX: jeśli twój produkt streamuje rozumowanie do użytkowników, nowe zachowanie wygląda jak długa pauza przed wyjściem. 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 tego samego 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 triggerami 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 przeciwko oknu 200K nawet przy używaniu Opus 4.7, powodując zawyżone procenty /context i wczesne 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łkowite tokeny 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 działający countdown i sam 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": "Zrefactoryzuj moduł auth."}],
    betas=["task-budgets-2026-03-13"],
)

Minimalna wartość to 20k tokenów. Pomiń dla otwartych zadań 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, więcej 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

Legacy Claude Sonnet 4 (claude-sonnet-4-20250514) i Claude Opus 4 (claude-opus-4-20250514) retirują 2026-06-15. Migruj do claude-sonnet-4-6 i claude-opus-4-7 odpowiednio przed tą datą. Zobacz stronę deprecjacji modeli Anthropic dla szczegółów.

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:

Sprawdź bieżącą wersję

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

Przejrzyj informacje o wydaniu

# Wewnątrz Claude Code
/release-notes

# Lub sprawdź GitHub
# github.com/anthropics/claude-code/releases

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)

Przetestuj w środowisku niekrytycznym
- Użyj najpierw projektu testowego
- Zweryfikuj, czy główne przepływy pracy nadal działają
- Sprawdź niestandardowe komendy i hooki
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 globalna NPM

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

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

# Zweryfikuj aktualizację
claude --version

# 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

# 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

Instalacja lokalna (zalecana)

Metoda instalacji lokalnej unika problemów z uprawnieniami i zapewnia płynniejsze aktualizacje:

# Jeśli jeszcze nie dokonałeś migracji
claude install

# Aktualizacje następują automatycznie lub ręcznie
claude update

# Sprawdź lokalizację instalacji
which claude  # Powinno pokazać ~/.claude/local/claude

Instalacja natywnego pliku binarnego (Alpha)

Aktualizacja pliku binarnego
Uwagi o platformach

# Z istniejącej instalacji
claude install

# Lub świeża instalacja
curl -fsSL claude.ai/install.sh | bash

Obsługa przełomowych zmian

Przykład: Zmiana formatu ARN Bedrock (v0.2.125)

Podczas aktualizacji przez przełomowe zmiany, postępuj według tego schematu:

Zidentyfikuj zmianę
- Stary format: arn:aws:bedrock:region::foundation-model/model%2Fversion
- Nowy format: arn:aws:bedrock:region::foundation-model/model/version

Zaktualizuj konfigurację

# Przed aktualizacją, zaktualizuj zmienne środowiskowe
export ANTHROPIC_MODEL="arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-7"
# Uwaga: Brak %2F, użyj literalnego /

Przetestuj konfigurację

# Zweryfikuj, czy konfiguracja działa
claude doctor

Kontynuuj aktualizację
Okno terminala
```
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

Środowisko deweloperskie
- Testuj z ochotniczymi programistami
- Uruchom przez 1-2 dni
- Zbierz opinie
Środowisko stagingowe
- Szersza grupa testowa
- Pełna walidacja przepływu pracy
- Benchmarking wydajności
Wdrożenie produkcyjne
- Komunikuj przez kanały zespołowe
- Stopniowo według zespołu/regionu
- Monitoruj problemy
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:

# 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

# 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ść:

Podstawowa funkcjonalność

# Sprawdź wersję i diagnostykę
claude --version
claude doctor

# Przetestuj podstawową interakcję
claude "Cześć, czy działasz prawidłowo?"

Integralność konfiguracji

# Zweryfikuj zachowane ustawienia
cat ~/.claude/settings.json

# Sprawdź niestandardowe komendy
ls .claude/commands/

Funkcjonalność narzędzi

# Przetestuj operacje na plikach
claude "Wyświetl pliki w bieżącym katalogu"

# Przetestuj serwery MCP
/mcp list

Sprawdzenie wydajności
- Czas odpowiedzi
- Użycie pamięci
- Obsługa kontekstu

Rozwiązywanie typowych problemów z aktualizacją

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 serwera MCP
/mcp list

# Aby zaktualizować serwer MCP, usuń i dodaj ponownie
claude mcp remove <nazwa-serwera>
claude mcp add <nazwa-serwera> <komenda> [argumenty...]

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:

GitHub Issues: Zgłaszaj błędy ze szczegółami wersji
Fora społeczności: Sprawdź, czy inni doświadczają tego samego problemu
Najpierw cofnij: Nie próbuj naprawiać do przodu w środowisku produkcyjnym
Dokumentuj dokładnie: Pomóż innym uniknąć tego samego problemu