Operacje wsadowe

Twój zespół migruje z moment.js do date-fns. Jest 147 plików importujących moment, każdy używający innego podzbioru API. Znajdź-i-zamień nie zadziała, ponieważ moment().format('YYYY-MM-DD') staje się format(new Date(), 'yyyy-MM-dd') — powierzchnia API jest kompletnie inna. Ręczne wykonanie tego zajmuje tydzień. Przy odpowiednim wzorcu operacji wsadowych zajmuje to popołudnie.

Co wyniesiesz

Równoległe przetwarzanie oparte na podagentach dla zmian wieloplikowych
Wzorzec planuj-następnie-wykonaj dla bezpiecznych modyfikacji na dużą skalę
Bezgłowe skrypty wsadowe dla operacji typu codemod
Strategie weryfikacji, które wychwycą błędy przed produkcją

Wzorzec planuj-następnie-wykonaj

Nigdy nie pozwól Claude wprowadzić 50 zmian w plikach bez wcześniejszego przeglądu planu.

Określ zakres zmiany

Znajdź wszystkie pliki importujące z 'moment'. Wylistuj każdy plik, konkretne używane funkcje moment
i równoważną funkcję date-fns. Wypisz jako tabelę. Nie wprowadzaj jeszcze żadnych zmian.

Przejrzyj plan Claude pokazuje tabelę każdego pliku, każdego importu i planowanej zamiany. Przejrzyj pod kątem przypadków brzegowych.

Wykonaj w partiach

Dobrze. Teraz zmigruj pliki w src/utils/ jako pierwsze (jest ich 8).
Po każdym pliku uruchom testy w tym katalogu do weryfikacji.

Weryfikuj i kontynuuj

Wszystkie testy przechodzą. Kontynuuj z src/components/ (23 pliki). To samo podejście:
migruj, testuj, raportuj wszelkie niepowodzenia.

Prompt do skopiowania do określania zakresu migracji wsadowej:

Muszę zmigrować wszystkie importy z [STARA_BIBLIOTEKA] do [NOWA_BIBLIOTEKA]. Przed wprowadzeniem jakichkolwiek zmian:

1. Znajdź każdy plik importujący z [STARA_BIBLIOTEKA]
2. Dla każdego pliku wylistuj konkretne używane funkcje/metody
3. Zmapuj każde użycie na jego równoważnik [NOWA_BIBLIOTEKA]
4. Oznacz użycia które NIE mają bezpośredniego odpowiednika
5. Oszacuj całkowitą liczbę zmian

Wypisz to jako tabelę markdown. Nie modyfikuj jeszcze żadnych plików.

Równoległe przetwarzanie oparte na podagentach

Dla dużych baz kodu deleguj pracę wsadową do podagentów, aby każda grupa plików miała własne okno kontekstu:

Zmigruj importy moment.js na date-fns w całym projekcie. Użyj podagentów do
przetwarzania każdego katalogu równolegle:

1. src/utils/ (8 plików) -- deleguj do podagenta
2. src/components/ (23 pliki) -- deleguj do podagenta
3. src/api/ (12 plików) -- deleguj do podagenta
4. src/services/ (15 plików) -- deleguj do podagenta

Każdy podagent powinien: zmigrować importy, zaktualizować wywołania funkcji i uruchomić
testy w tym katalogu. Raportuj: zmienione pliki, testy przeszły/niepowodzenia.

To działa, ponieważ podagenci mają niezależne okna kontekstu, więc nie wypełniają głównej sesji wartością 50 plików diffów.

Bezgłowe skrypty wsadowe

Dla powtarzalnych operacji użyj trybu print, aby budować zautomatyzowane skrypty:

#!/bin/bash
# migrate-moment.sh -- Uruchom bezgłową migrację w katalogach

DIRS=("src/utils" "src/components" "src/api" "src/services")

for dir in "${DIRS[@]}"; do
  echo "Migruję $dir..."
  claude -p "Zmigruj wszystkie importy moment.js w $dir/ na date-fns. \
    Zaktualizuj wywołania funkcji aby pasowały do API date-fns. \
    Po migracji uruchom: npx jest $dir/ --no-coverage" \
    --max-turns 20 \
    --dangerously-skip-permissions \
    --output-format json > "results/$dir.json" 2>&1

  echo "Ukończono $dir"
done

echo "Migracja zakończona. Przejrzyj wyniki w results/"

Częste operacje wsadowe

Migracja wersji API

Deprecjonujemy /api/v1/ i wszystkie klienci zostali zmigrowani na /api/v2/.
Usuń wszystkie handlery tras v1, ich testy i middleware specyficzne dla v1.
Zachowaj współdzielone middleware używane przez obie wersje.

Proces:
1. Wylistuj wszystkie pliki w src/api/v1/
2. Dla każdej trasy v1 zweryfikuj że istnieje odpowiednik v2
3. Usuń pliki v1 i ich testy
4. Usuń wpisy v1 z konfiguracji routera
5. Uruchom pełny zestaw testów do weryfikacji że nic się nie psuje

Refaktoryzacja zmiany nazwy

Zmień nazwę klasy UserService na AccountService w całej bazie kodu.
To obejmuje:
- Definicję klasy i nazwę pliku
- Wszystkie importy odwołujące się do UserService
- Wszystkie nazwy zmiennych używające userService lub UserService
- Pliki testowe i opisy testów
- Referencje w CLAUDE.md i dokumentacji

Użyj git mv dla zmian nazw plików, aby git śledził historię.
Uruchom pełny zestaw testów i kompilator TypeScript po wszystkich zmianach.

Prompt do skopiowania dla masowych aktualizacji ścieżek importów:

Przenieśliśmy współdzielone narzędzia z src/lib/utils do src/shared/utils.
Zaktualizuj każdą ścieżkę importu w bazie kodu odwołującą się do starej lokalizacji.

Reguły:
- Zmień 'src/lib/utils' na 'src/shared/utils' we wszystkich instrukcjach import
- Zaktualizuj też aliasy ścieżek w tsconfig.json
- Zaktualizuj też mapowania modułów w jest.config.js
- NIE zmieniaj zawartości plików samych narzędzi
- Uruchom kompilator TypeScript do weryfikacji że wszystkie importy się rozwiązują

Dodawanie boilerplate do wielu plików

Każda trasa API w src/api/routes/ potrzebuje mieć:
1. Blok komentarza JSDoc OpenAPI nad handlerem
2. Walidację wejścia używając wzorca schematu Zod z src/api/routes/orders.ts
3. Obsługę błędów opakowaną w narzędzie asyncHandler

Proces: Przeczytaj src/api/routes/orders.ts jako implementację referencyjną.
Następnie zastosuj te same wzorce do wszystkich innych plików tras, którym ich brakuje.
Wylistuj każdy plik i co dodałeś przed kontynuacją.

Strategie weryfikacji

Progresywne testowanie

Uruchamiaj testy po każdej partii zmian, nie na końcu:

Dla każdego katalogu który migrujesz:
1. Wprowadź zmiany
2. Uruchom: npx jest [katalog] --no-coverage
3. Jeśli testy nie przechodzą, napraw niepowodzenia przed przejściem do następnego katalogu
4. Raportuj: nazwa katalogu, zmienione pliki, testy przeszły, testy niepowodzenia

Sprawdzanie typów jako bariera ochronna

Po wprowadzeniu wszystkich zmian uruchom: npx tsc --noEmit
Jeśli są błędy typów, napraw je. Kompilator TypeScript jest źródłem prawdy
czy importy i sygnatury funkcji są poprawne.

Weryfikacja oparta na Git

Po ukończeniu migracji:
1. Uruchom: git diff --stat aby pokazać wszystkie zmienione pliki
2. Uruchom: git diff aby pokazać rzeczywiste zmiany
3. Zweryfikuj że nie ma niezamierzonych modyfikacji
4. Uruchom pełny zestaw testów
5. Jeśli wszystko przechodzi, stwórz commit z opisowym komunikatem

Gdy to się psuje

Claude modyfikuje pliki, których nie powinien dotykać: Użyj ograniczeń na początku promptu: “Modyfikuj tylko pliki w src/api/. Nie dotykaj src/core/ ani żadnych plików konfiguracyjnych.” Dla dodatkowego bezpieczeństwa użyj --disallowedTools "Edit(src/core/**)" aby zablokować edycje konkretnych ścieżek.

Operacja wsadowa kończy kontekst: Długie operacje wsadowe wypełniają okno kontekstu. Użyj podagentów dla równoległej pracy lub podziel operację na wiele sesji z /clear między partiami.

Testy przechodzą ale zachowanie się zmienia: Operacje wsadowe mogą wprowadzić subtelne zmiany zachowania, których testy nie wychwycą. Zawsze wykonuj ręczny przegląd git diff przed commitowaniem zmian wsadowych.

Claude utyka w pętli: Jeśli Claude ciągle naprawia błędy jednego pliku tylko po to, żeby zepsuć inny, zatrzymaj operację. Zmiany wymagają innego podejścia — prawdopodobnie planu uwzględniającego kolejność zależności między plikami.

Co dalej

Automatyzacja skryptów — Zamień wzorce wsadowe w skrypty automatyzacji wielokrotnego użytku
Automatyzacja przeglądów — Zautomatyzuj przegląd zmian generowanych wsadowo
Wskazówki dla dużych baz kodu — Wskazówki zarządzania Claude Code w dużych bazach kodu