Operacje wsadowe

Gdy musisz przekształcić setki plików, przeprowadzić migrację całych baz kodu lub zastosować systematyczne zmiany w wielu serwisach, Claude Code staje się mnożnikiem siły. Ten przewodnik ujawnia zaawansowane wzorce dla orkiestracji transformacji kodu na dużą skalę, które zajęłyby dni ręcznej pracy, ale można je ukończyć w godziny przy właściwym podejściu.

Filozofia operacji wsadowych

Zrozumienie skali i automatyzacji

Operacje wsadowe w Claude Code podążają za innym paradygmatem niż interakcyjne programowanie:

Zasady operacji wsadowych

Systematyczne nad doraźnym: Zdefiniuj wzorce raz, zastosuj wszędzie
Weryfikacja na skalę: Automatyczne testowanie dla każdej zmiany
Postęp przyrostowy: Dziel duże migracje na etapy z punktami kontrolnymi
Gotowość do wycofania: Każda operacja wsadowa powinna być odwracalna
Oparte na wzorcach: Używaj spójnych podejść w podobnych transformacjach

Kiedy używać operacji wsadowych

Rozpoznaj scenariusze, które korzystają z przetwarzania wsadowego:

Migracje frameworków: React 16 → 18, Vue 2 → 3, aktualizacje Angular
Zmiany kontraktów API: Aktualizacja wszystkich konsumentów zmodyfikowanego API
Egzekwowanie zasad lintingu: Stosowanie nowych standardów w całej bazie kodu
Aktualizacje zależności: Obsługa zmian łamiących w głównych bibliotekach
Modernizacja kodu: ES5 → ES6+, callback → wzorce async/await
Refaktoryzacja między serwisami: Przemianowanie encji używanych w mikrousługach

Podstawowe wzorce operacji wsadowych

Wzorzec listy zadań

Fundamentem większości operacji wsadowych jest systematyczne generowanie zadań:

> Przeanalizuj bazę kodu i utwórz migration-tasks.md zawierający:
  - Wszystkie komponenty klasowe React wymagające konwersji na hooki
  - Aktualną ścieżkę pliku i nazwę komponentu
  - Szacowaną złożoność (prosta/średnia/złożona)
  - Zależności od innych komponentów

  Posortuj według kolejności zależności, abyśmy mogli migrować od dołu do góry

Claude generuje ustrukturyzowaną listę zadań:

# Zadania migracji do React Hooks

## Komponenty proste (brak stanu, czyste renderowanie)
1. components/ui/Button.jsx - Button
2. components/ui/Label.jsx - Label
...

## Komponenty średnie (tylko stan lokalny)
10. components/forms/TextInput.jsx - TextInput
11. components/forms/Checkbox.jsx - Checkbox
...

## Komponenty złożone (kontekst, refy, cykl życia)
25. components/auth/LoginForm.jsx - LoginForm (używa AuthContext)
26. components/data/DataTable.jsx - DataTable (złożony cykl życia)
...

Wzorzec systematycznego wykonania

Przekształć listę zadań w wykonywalne partie:

> Dla każdego komponentu w migration-tasks.md oznaczonego jako "prosty":
  1. Konwertuj na komponent funkcyjny z hookami
  2. Uruchom testy komponentu
  3. Jeśli testy przechodzą, zatwierdź z komunikatem "refactor: convert [nazwa] to hooks"
  4. Zaktualizuj listę zadań oznaczając jako ukończone
  5. Jeśli testy nie przechodzą, zaloguj błąd i przejdź do następnego

  Zacznij od pierwszych 5 prostych komponentów

Wzorzec pętli weryfikacji

Wbuduj weryfikację w każdą operację wsadową:

> Dla każdego zmigrowanego komponentu:
  1. Wygeneruj testy migawkowe jeśli brakuje
  2. Uruchom istniejące testy
  3. Porównaj rozmiar pakietu przed/po
  4. Sprawdź błędy w konsoli
  5. Kontynuuj tylko jeśli wszystkie sprawdzenia przechodzą

> Po każdej partii zmian:
  1. Uruchom ESLint z naszą konfiguracją
  2. Uruchom kompilator TypeScript
  3. Sprawdź nieużywane importy
  4. Sprawdź brak zależności cyklicznych
  5. Napraw problemy przed kontynuowaniem

> Dla zmian komponentów UI:
  1. Wygeneruj historie Storybook
  2. Zrób migawki wizualne
  3. Porównaj z bazą
  4. Oznacz regresje wizualne
  5. Utwórz dokument przeglądu

Zaawansowane techniki wsadowe

Wzorzec przetwarzania równoległego

Wykorzystaj wiele instancji Claude do naprawdę równoległego wykonania:

# Terminal 1: Obsługa prostych komponentów
$ claude
> Przetwórz wszystkie komponenty "proste" z migration-tasks.md

# Terminal 2: Obsługa średnich komponentów
$ claude
> Przetwórz wszystkie komponenty "średnie" z migration-tasks.md

# Terminal 3: Aktualizacja dokumentacji
$ claude
> Podczas migracji komponentów, aktualizuj ich dokumentację

# Terminal 4: Monitorowanie i koordynacja
$ claude
> Monitoruj git log, zapewnij brak konfliktów, śledź ogólny postęp

Wzorzec migracji przyrostowej

Dla ryzykownych zmian na dużą skalę, użyj flag funkcji i wdrażania przyrostowego:

> Zaimplementuj obsługę dwóch trybów dla uwierzytelniania:
  1. Dodaj flagę funkcji USE_NEW_AUTH
  2. Otocz stary kod uwierzytelniania w if (!USE_NEW_AUTH)
  3. Zaimplementuj nowe uwierzytelnianie w bloku else
  4. Obie ścieżki muszą przejść wszystkie testy
  5. Wdróż z wyłączoną flagą, testuj w produkcji
  6. Stopniowo włączaj dla większej liczby użytkowników
  7. Gdy stabilne, usuń stary kod

Zacznij od auth/login.js

Wzorzec między repozytoriami

Koordynuj zmiany w wielu repozytoriach:

# Utwórz skrypt koordynacji
> Wygeneruj cross-repo-update.sh który:
  1. Wymieni wszystkie repozytoria wymagające aktualizacji
  2. Dla każdego repozytorium:
     - Sklonuj jeśli nie istnieje
     - Utwórz gałąź 'update-api-contract'
     - Uruchom claude z tym samym promptem
     - Zatwierdź zmiany
     - Wypchnij gałąź
  3. Wygeneruj podsumowanie wszystkich zmian
  4. Utwórz dokument z linkami do PR

Przykłady migracji z rzeczywistego świata

Migracja frameworka: Express do Fastify

Faza analizy

> Przeanalizuj naszą aplikację Express i utwórz plan migracji do Fastify:
  - Wymień wszystkie używane middleware
  - Zidentyfikuj wzorce specyficzne dla Express
  - Znajdź odpowiedniki w Fastify
  - Oszacuj nakład pracy na moduł

Warstwa kompatybilności

> Utwórz express-compat.js który:
  - Owija Fastify dla obsługi middleware Express
  - Zapewnia kompatybilność req/res
  - Pozwala na stopniową migrację

Migracja tras

> Dla każdego pliku trasy w routes/:
  1. Konwertuj router Express na plugin Fastify
  2. Zaktualizuj middleware na hooki Fastify
  3. Dostosuj obsługę request/response
  4. Zachowaj ten sam kontrakt API
  5. Testuj z istniejącymi testami integracyjnymi

Migracja middleware

> Konwertuj middleware Express na pluginy Fastify:
  - Uwierzytelnianie → hook preHandler
  - Obsługa błędów → error handler
  - Parsowanie body → wbudowana obsługa
  - Pliki statyczne → @fastify/static

Faza czyszczenia

> Po migracji wszystkich tras:
  1. Usuń zależności Express
  2. Usuń warstwę kompatybilności
  3. Optymalizuj funkcje specyficzne dla Fastify
  4. Zaktualizuj dokumentację

Ewolucja kontraktu API

Gdy zmieniasz szeroko używane API:

> Musimy przemianować 'customerId' na 'clientId' w 10 serwisach.

  Faza 1 - Dodaj kompatybilność wsteczną:
  Dla każdego serwisu:
    1. Dodaj pole 'clientId' obok 'customerId'
    2. Loguj ostrzeżenie o deprecacji gdy używany 'customerId'
    3. Zaktualizuj kod wewnętrzny na używanie 'clientId'
    4. Wdróż z obsługą obu pól

  Faza 2 - Zaktualizuj konsumentów:
  Dla każdego serwisu konsumującego:
    1. Zaktualizuj na wysyłanie/oczekiwanie 'clientId'
    2. Usuń użycie 'customerId'
    3. Testuj integrację
    4. Wdróż

  Faza 3 - Usuń pole przestarzałe:
  Dla każdego serwisu:
    1. Usuń obsługę 'customerId'
    2. Usuń ostrzeżenia o deprecacji
    3. Finalne testowanie
    4. Wdróż

Ewolucja schematu bazy danych

Zarządzanie złożonymi zmianami schematu:

> Zmigruj z pojedynczego pola 'address' na strukturalny adres:

  1. Dodaj nowe kolumny (zachowaj stare):
     - street_address
     - city
     - state
     - postal_code
     - country

  2. Utwórz skrypt migracji:
     - Parsuj istniejące dane adresowe
     - Wypełnij nowe pola
     - Obsłuż przypadki graniczne
     - Loguj adresy nie do sparsowania

  3. Zaktualizuj kod aplikacji:
     - Dodaj nowe pola do modeli
     - Podwójny zapis do starych i nowych
     - Stopniowo aktualizuj zapytania

  4. Weryfikuj i przełącz:
     - Porównaj stare vs nowe dane
     - Przełącz odczyty na nowe pola
     - Przerwij pisanie do starego pola

  5. Czyszczenie:
     - Usuń starą kolumnę
     - Usuń kod podwójnego zapisu

Automatyzacja i skryptowanie

Tryb headless dla operacji wsadowych

Wykorzystaj tryb headless Claude do skryptowanych transformacji:

#!/bin/bash
# Wygeneruj listę plików
find src -name "*.js" -type f > files-to-process.txt

# Przetwórz każdy plik
while IFS= read -r file; do
  echo "Przetwarzanie $file..."

  claude -p "W $file, konwertuj wszystkie var na const/let na podstawie użycia. \
    Użyj const dla nigdy nie przypisywanych, let dla przypisywanych ponownie. \
    Zachowaj całą funkcjonalność." \
    --allowedTools Edit \
    --quiet

  # Uruchom szybki test
  if npm test -- --findRelatedTests "$file" > /dev/null 2>&1; then
    git add "$file"
    git commit -m "refactor: modernize variable declarations in $file"
  else
    echo "Testy nie powiodły się dla $file, pomijam"
    git checkout -- "$file"
  fi
done < files-to-process.txt

Wzorzec fan-out

Dla masowych operacji równoległych:

> Utwórz skrypt fan-out dla przetwarzania 1000+ komponentów:

#!/bin/bash
# Podziel zadania na części
split -l 50 migration-tasks.txt chunk-

# Przetwarzaj części równolegle
for chunk in chunk-*; do
  (
    claude -p "Przetwórz wszystkie komponenty wymienione w $chunk zgodnie z przewodnikiem migracji. \
      Loguj postęp do $chunk.log" \
      --allowedTools Edit Bash View \
      > "$chunk.output" 2>&1
  ) &
done

# Czekaj na wszystkie zadania w tle
wait

# Połącz wyniki
cat chunk-*.log > migration-complete.log

Niestandardowe hooki dla operacji wsadowych

Skonfiguruj hooki dla spójnego przetwarzania:

{
  "hooks": [
    {
      "matcher": "Edit",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
        },
        {
          "type": "command",
          "command": "eslint --fix \"$CLAUDE_FILE_PATHS\""
        }
      ]
    },
    {
      "matcher": "PostBatch",
      "hooks": [
        {
          "type": "command",
          "command": "npm test -- --coverage"
        }
      ]
    }
  ]
}

Odzyskiwanie błędów i wycofywanie

Wzorzec punktów kontrolnych

Utwórz punkty przywracania podczas operacji wsadowych:

> Przed rozpoczęciem migracji:
  1. Utwórz tag git 'pre-migration-backup'
  2. Wygeneruj sumy kontrolne plików: find . -type f -exec md5sum {} \; > pre-migration.md5
  3. Zrób kopię zapasową krytycznych konfiguracji
  4. Udokumentuj aktualny działający stan

  Po każdym głównym kamieniu milowym:
  1. Zatwierdź z opisowym komunikatem
  2. Otaguj 'migration-checkpoint-N'
  3. Uruchom pełny zestaw testów
  4. Zaktualizuj log postępu

Strategia wycofywania

Procedury wycofywania

# Szybkie wycofanie do ostatniego punktu kontrolnego
git reset --hard migration-checkpoint-3

# Pełne wycofanie z czyszczeniem
git checkout pre-migration-backup
rm -rf node_modules package-lock.json
npm install
npm test

# Selektywne wycofanie
git checkout pre-migration-backup -- src/components/
git commit -m "revert: rollback component migration"

Analiza błędów i odzyskiwanie

Gdy operacje wsadowe nie powiodą się:

> Przeanalizuj niepowodzenie migracji:
  1. Przeczytaj logi błędów z failed-migrations.log
  2. Zidentyfikuj wspólne wzorce w niepowodzeniach
  3. Zasugeruj poprawki dla skryptu migracji
  4. Utwórz plan odzyskiwania dla częściowo zmigrowanego stanu

> Wygeneruj skrypt odzyskiwania który:
  1. Identyfikuje częściowo zmigrowane pliki
  2. Kończy lub cofa każdy plik
  3. Zapewnia spójny stan
  4. Ponownie uruchamia dotknięte testy

Optymalizacja wydajności

Użycie tokenów w operacjach wsadowych

Optymalizuj dla efektywności na skalę:

❌ Podejście tokeno-intensywne

"Przeanalizuj całą bazę kodu i
konwertuj wszystkie komponenty na TypeScript"
# Ładuje wszystko do kontekstu

✅ Podejście tokenowo-efektywne

"Konwertuj user.js na TypeScript
zgodnie ze wzorcami w types.md"
# Skoncentrowany kontekst na plik

Optymalizacja rozmiaru partii

Znajdź optymalny punkt dla swoich operacji:

# Testuj różne rozmiary partii
> Przetwarzaj migrację w partiach po:
  - 10 plików: zmierz czas i wskaźnik sukcesu
  - 25 plików: zmierz czas i wskaźnik sukcesu
  - 50 plików: zmierz czas i wskaźnik sukcesu

  Polecaj optymalny rozmiar partii na podstawie:
  - Użycia tokenów na partię
  - Wskaźnika błędów
  - Całkowitego czasu ukończenia

Monitorowanie i raportowanie

Śledzenie postępu

Utwórz kompleksowe raportowanie postępu:

> Wygeneruj migration-dashboard.html który pokazuje:
  - Łączna liczba plików: 500
  - Ukończone: 350 (70%)
  - Nieudane: 12 (2.4%)
  - Pominięte: 38 (7.6%)
  - Pozostałe: 100 (20%)

  Dołącz:
  - Wskaźnik sukcesu według typu komponentu
  - Częste przyczyny niepowodzeń
  - Szacowany czas ukończenia
  - Zmiany pokrycia testów

Automatyczne raportowanie

Skonfiguruj automatyczne powiadomienia dla długotrwałych operacji wsadowych:

(claude -p "Uruchom pełną migrację" && \
  echo "Migracja ukończona pomyślnie" || \
  echo "Migracja nie powiodła się - sprawdź logi") | \
  mail -s "Status migracji Claude" team@company.com

Lista kontrolna najlepszych praktyk

Przed uruchomieniem jakiejkolwiek operacji wsadowej:

Utwórz kompleksowe kopie zapasowe
Testuj na małym podzbiorze najpierw
Skonfiguruj monitorowanie postępu
Przygotuj procedury wycofywania
Udokumentuj oczekiwane wyniki
Powiadom dotknięte zespoły
Zaplanuj w okresach niskiego ruchu
Miej plan interwencji ręcznej

Co dalej?

Kontynuuj opanowywanie Claude Code z:

Automatyzacja skryptów - Tworzenie skryptów automatyzacji wielokrotnego użytku
Strategie debugowania - Obsługa błędów na skalę
Wzorce wdrażania - Zautomatyzowane przepływy wdrażania

Pamiętaj: Operacje wsadowe wzmacniają zarówno sukcesy, jak i porażki. Zacznij małymi krokami, dokładnie weryfikuj i skaluj stopniowo. Dzięki systematycznemu podejściu Claude Code możesz przekształcić bazy kodu, których aktualizacja zajęłaby zespołom tygodnie ręcznej pracy.