Zmiany w wielu plikach

Praca na wielu plikach w Claude Code rozdziela trzy zadania: tryb planowania wyznacza każdy plik, którego dotknie zmiana, zanim padnie pierwsza edycja; lista kontroli akceptacyjnych definiuje „gotowe” przed rozpoczęciem edycji; a same zmiany idą warstwa po warstwie, rozdzielane przez /batch lub --worktree tylko wtedy, gdy części są niezależne. Wynik potwierdzają kontrole, a nie czytanie linijka po linijce.

Masz zmienić nazwę pola customerId na clientId. Pole przechodzi przez model, serializer, trzy kontrolery, migrację, publiczny kontrakt API i 60 testów. Jeden prompt „zmień to wszędzie” zwraca diff na 40 plików, który wygląda wiarygodnie, a nikt w zespole nie potrafi powiedzieć, czy jutro nie padnie klient mobilny, który wciąż wysyła customerId. Ta strona jest dla programisty, który prowadzi taką zmianę, i dla tech leada, który musi ją zatwierdzić bez czytania wszystkich 40 plików.

Co daje ci uporządkowany proces zmian w wielu plikach

Prompt „najpierw plan”, po którym Claude Code wypisuje zasięg zmiany pogrupowany według warstw, zanim cokolwiek zmieni.
Listę kontroli akceptacyjnych pisaną przed edycją, dzięki której poprawności wyniku dowodzą polecenia, a nie lektura kodu.
Wzorzec zmiany nazwy zgodny wstecz (rozszerz, przenieś, zawęź), który przetrwa klientów, nad którymi nie masz kontroli.
Regułę wyboru między jedną sesją, /batch, równoległymi worktree, subagentami i --add-dir.
Tabelę odzyskiwania po typowych awariach edycji wieloplikowych, z poleceniem, które wyciąga z każdej z nich.

Który mechanizm Claude Code pasuje do twojej zmiany?

Wybieraj mechanizm według tego, jak niezależne są części zmiany, a nie według liczby plików. Zmiana nazwy w 40 plikach to jedna ściśle powiązana zmiana; trzy niezwiązane funkcje to trzy zmiany.

Twoja zmiana	Użyj	Dlaczego
Jedna powiązana zmiana przez warstwy (zmiana nazwy, nowe pole, nowa kontrola ról)	Jednej sesji: tryb planowania, potem edycja warstwa po warstwie	Każda edycja zależy od poprzedniej; podział rodzi konflikty scalania i niespójne nazwy.
Ta sama mechaniczna edycja w wielu niezależnych miejscach (migracja 25 wywołań na nowe API)	`/batch`	Wbudowany skill dzieli zmianę na 5–30 jednostek i uruchamia każdą w subagencie w tle, we własnym worktree.
Kilka niezwiązanych strumieni pracy (auth, płatności, analityka)	Jednej sesji `claude --worktree <nazwa>` na strumień	Każda sesja dostaje własny checkout i gałąź, więc edycje się nie zderzają.
Rozpoznanie przed edycją (kto to wywołuje, co się zepsuje)	Subagenta, np. wbudowanego agenta Explore	Wyniki wyszukiwania nie zapychają głównego okna kontekstu.
Jedna zmiana w sąsiednich katalogach (wspólna biblioteka i aplikacja, która ją importuje)	`--add-dir` w jednej sesji	Claude Code czyta i edytuje oba katalogi według jednego planu.

Zespoły agentów (agent teams), czyli sesja prowadząca koordynująca sesje równorzędne ze wspólnymi zadaniami, są eksperymentalne i domyślnie wyłączone (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Sięgaj po nie dopiero wtedy, gdy powyższe opcje przestaną wystarczać.

Zaplanuj zasięg zmiany przed pierwszą edycją

Pominięty plik w planie poprawiasz jedną linijką, a w diffie na 40 plików szukasz go przez całe popołudnie, dlatego wymuś plan przed pierwszym zapisem. Od Claude Code v2.1.283 na kanale latest sesje interaktywne startują w trybie auto, który edytuje pliki bez pytania (claude -p, Agent SDK, sesje, w których plik ustawień ustawia disableAutoMode, oraz modele nieobsługiwane przez tryb auto nadal startują w trybie Manual). Przełączenie w tryb planowania to więc świadomy krok, a nie ustawienie domyślne.

Uruchom sesję w trybie planowania albo przełącz otwartą sesję przez Shift+Tab lub /plan:
Okno terminala
```
claude --permission-mode plan
```
Poproś o plan, nie o zmianę. Tryb planowania jest tylko do odczytu, więc Claude Code przegląda kod i proponuje, nie zapisując żadnego pliku.
Porównaj listę plików z tym, co wiesz o systemie. Brakującą warstwę (klient mobilny, eksport CSV, zadanie w tle) poprawisz tu za darmo; w diffie znajdziesz ją drogo.
Zapisz zatwierdzony plan w pliku w repozytorium, np. plans/client-id-rename.md. Lista plików staje się kontraktem dla edycji i dla przeglądu.

We are renaming the field `customerId` to `clientId` across this repository.
Do not edit any files. Produce a plan and write it to plans/client-id-rename.md:
1. Every file that reads, writes, serializes, validates or tests `customerId`,
   grouped by layer: database/migrations, models, services, API routes and
   contracts, UI, background jobs, tests, docs.
2. For each file, one line on what changes and why.
3. Every place where an external client sends or reads the field (API input,
   API output, webhooks, exports). Mark these PUBLIC.
4. The order you would make the changes in, one layer per step.
5. What you could not determine from the code (runtime config, other repos).
Search imports and type usages, not only the literal string.

Śledzenie po importach i typach, a nie tylko po tekście, to powód, by pytać agenta zamiast uruchamiać grep: wyszukiwanie tekstowe przeoczy destrukturyzację const { customerId: id } i generyczne wywołanie pick(user, fields). Punkt 5 promptu jest równie ważny: mówi ci, czego plan nie obejmuje.

Napisz kontrole akceptacyjne przed edycją

Diffu na wiele plików nie da się zweryfikować czytaniem. Zdecyduj, co dowodzi poprawności, zanim Claude Code napisze pierwszą linijkę, i niech każda kontrola będzie poleceniem, które przy błędzie kończy się niezerowym kodem wyjścia. Typowe kontrole dla zmiany nazwy:

Przechodzą sprawdzanie typów i linter (npm run typecheck, npm run lint lub odpowiedniki w twoim stosie).
Przechodzi istniejący zestaw testów, bez zmian w asercjach niezwiązanych ze zmianą nazwy.
Wyszukiwanie starej nazwy zwraca tylko linie dozwolone w planie (alias wejściowy i log o wycofaniu).
Nowy test dowodzi, że żądanie wciąż wysyłające customerId dostaje tę samą odpowiedź co dziś.

Ostatnia kontrola łapie awarię produkcyjną i musi istnieć przed zmianą, żeby w ogóle mogła wykryć regresję. Zobacz, jak pisać kryteria akceptacji, które agent potrafi sprawdzić, oraz jak nie dopuścić, by agent edytował testy, które go oceniają.

Read plans/client-id-rename.md. Before changing any production code:
1. Add a section "Acceptance checks" to the plan with the exact shell
   commands that prove the rename is correct: type-check, lint, the test
   command, and a ripgrep command whose only allowed matches for
   `customerId` are the input alias and the deprecation warning.
2. Write one integration test that sends a request with `customerId` in the
   body and asserts the response equals today's response. Run it now and
   show me it passes on the current code.
3. Stop and wait for my approval. Do not modify existing test assertions.

Zmień nazwę publicznego pola, nie psując wywołujących

Zmiana nazwy jest wewnętrzna, dopóki nie zależy od niej żaden zewnętrzny klient. Dla wszystkiego, co plan oznaczył jako PUBLIC, stosuj schemat rozszerz, przenieś, zawęź zamiast prostej podmiany:

Rozszerz. Zwracaj nową nazwę wszędzie i przyjmuj obie nazwy na wejściu, mapując customerId na clientId.
Przenieś. Przestaw wszystkie wewnętrzne wywołania na nową nazwę, podczas gdy API wciąż przyjmuje starą.
Ostrzegaj. Loguj ostrzeżenie o wycofaniu przy każdym żądaniu, które wciąż używa starej nazwy, żeby widzieć, kto jeszcze ją wysyła.
Zawęź. Usuń starą nazwę osobną zmianą, gdy logi przez uzgodniony okres nie pokazują ruchu.

Execute plans/client-id-rename.md, layer by layer, in the order the plan gives.
Rules:
- Produce `clientId` everywhere. Keep accepting `customerId` on API input and
  map it to `clientId`. Log a deprecation warning when `customerId` arrives.
- After each layer, run the acceptance checks from the plan and show me the
  output. If a check fails, fix it before moving to the next layer.
- If you need to edit a file that is not in the plan, stop and tell me which
  file and why before editing it.
- Do not change assertions in existing tests except where they name the field.
After the last layer, print `git diff --stat` and mark each file as
"in plan" or "not in plan".

Reguła „not in plan” to najtańszy detektor regresji, jaki masz. Nieplanowana edycja oznacza, że albo plan był niepełny, albo agent zbacza z kursu, i chcesz wiedzieć, które z nich, zanim następna warstwa na tym zbuduje. Głębsze przepisy na zmianę nazw, wydzielanie i restrukturyzację znajdziesz we wzorcach refaktoryzacji, a zmiany schematu wymagające migracji danych opisuje strona o migracjach bazy danych.

Edytuj warstwa po warstwie i commituj między warstwami

Duże zmiany pozostają dokładne, gdy każdy prompt obejmuje jedną warstwę: migrację i modele, potem serwisy, potem trasy, potem UI, na końcu testy. Każda warstwa to diff na tyle mały, by go sprawdzić, a każdy commit to znany dobry punkt powrotu.

Kontekstem między warstwami zarządzasz poleceniami interaktywnymi:

/context pokazuje, co wypełnia okno kontekstu.
/compact Keep the plan file path, the acceptance checks and the list of files already changed streszcza rozmowę, zachowując to, czego potrzebuje następna warstwa.
/clear zaczyna od zera; zakotwicz sesję ponownie, wskazując Claude Code plik planu.
/usage pokazuje koszt sesji i limity planu.
/rewind albo dwukrotne Esc przy pustym prompcie przywraca kod i rozmowę do wcześniejszego punktu kontrolnego.

Commituj po każdej warstwie, która przeszła kontrole. „Cała zmiana jest zepsuta” zamienia się wtedy w „ostatni commit jest zepsuty”, a git revert jednego commita zastępuje popołudnie rozplątywania.

Rozdziel mechaniczną zmianę przez /batch

Gdy plan pokazuje tę samą edycję w wielu miejscach, które od siebie nie zależą, np. przeniesienie 25 handlerów tras ze starego loggera na nowy, jedna sesja marnuje czas, robiąc to po kolei. Wbudowany skill /batch dzieli zmianę na 5–30 jednostek i uruchamia każdą w subagencie w tle, we własnym worktree.

/batch Replace every call to `legacyLogger.log(level, msg, meta)` in src/routes/
with `logger[level](msg, meta)` from src/lib/logger.ts. One unit per route file.
Each unit must: keep log levels and message text identical, run
`npm run typecheck` and the tests for that route, and report the command output.
Do not touch files outside src/routes/ or src/lib/logger.ts.

/batch pasuje do edycji, których poprawność sprawdzisz dla każdej jednostki osobno. To złe narzędzie do powyższej zmiany clientId, w której każda jednostka zależy od wcześniejszej zmiany modelu. Wiele niezwiązanych zadań w repozytorium, a nie jedną zmianę, opisuje strona o operacjach wsadowych.

Uruchom niezależne strumienie w równoległych worktree

Niezwiązanym strumieniom pracy daj osobne sesje i checkouty. --worktree (-w) tworzy dla sesji git worktree i gałąź, a --tmux otwiera ją we własnej sesji tmux (gdy to możliwe, używa natywnych paneli iTerm2; --tmux=classic wymusza zwykły tmux):

# W terminalu w katalogu głównym repozytorium: jedna sesja, worktree i gałąź na strumień
claude --worktree auth --tmux
claude --worktree payments --tmux
claude --worktree analytics --tmux

W Claude Code 2.1.283 worktree trafiają do .claude/worktrees/, więc dopisz tę ścieżkę do .gitignore, jeśli repozytorium jeszcze jej nie ignoruje. Worktree izolują pliki i gałęzie, ale nie całą resztę: każdy checkout wciąż sięga tej samej deweloperskiej bazy danych, tych samych portów, konta chmurowego i sekretów. Daj każdemu strumieniowi własny blok portów i lokalne dane, a zdalne migracje i wdrożenia trzymaj poza sesjami agentów. Przewodnik po równoległych worktree opisuje przydział portów i kolejność integracji, a tmux dla floty agentów — obserwowanie wielu sesji naraz.

Zmień wspólną bibliotekę i jej konsumentów

Gdy jedna zmiana obejmuje wspólną bibliotekę i aplikacje, które ją importują, prowadź ją w jednej sesji, żeby jeden plan obejmował obie strony. Uruchom sesję z dodatkowymi katalogami, a potem wpisz prompt:

# W terminalu w katalogu apps/web
claude --add-dir ../../packages/shared-logger

Przy osobnych repozytoriach idź od producenta do kolejnych konsumentów, jedna sesja na repozytorium. Utrzymuj etap „rozszerz” u producenta, dopóki każdy konsument nie wyda swojej zmiany, i zapisz migrację w CLAUDE.md każdego repozytorium, żeby następna sesja nie przywróciła starej nazwy:

<!-- CLAUDE.md in each consuming repository -->
## Active migrations
- /users returns `clientId`; `customerId` is still accepted on input until v3. Do not add new reads of `customerId`.

Gdzie umieścić taką notatkę i jak Claude Code ją wczytuje, opisuje strona o systemie pamięci.

Jak zweryfikować diff na 40 plików bez czytania każdej linijki?

Weryfikujesz zmianę względem planu i kontroli, a czytasz tylko tam, gdzie one wskazują. Po ostatniej warstwie wykonaj tę sekwencję:

Zakres. Porównaj git diff --stat main...HEAD z listą plików w planie. Każdy plik spoza planu wymaga uzasadnienia.
Bramki. Uruchom kontrole akceptacyjne z planu samodzielnie, w czystej powłoce, a nie tylko wewnątrz sesji. Hook, który uruchamia sprawdzanie typów po każdej edycji, łapie błędy na poziomie warstwy zamiast na końcu.
Zachowanie. Test zgodności napisany przed zmianą musi nadal przechodzić, bez modyfikacji. Sprawdź to przez git log -p na pliku tego testu.
Niezależny przegląd. Uruchom /code-review na gałęzi, najlepiej w świeżej sesji (/clear albo nowe claude), żeby przegląd nie opierał się na rozumowaniu, które wyprodukowało zmianę. Jak uruchamiać go przy każdym pull requeście, opisuje strona o automatyzacji code review.
Akceptacja. Recenzent zatwierdza plan, wyniki kontroli i uwagi z przeglądu, a czyta tylko pliki, na które wskazuje kontrola lub uwaga. Na tym polega zmiana opisana w artykule dowody zamiast diffów.

Prepare the evidence for reviewing this branch against main. Do not change code.
1. Run `git diff --stat main...HEAD` and list every changed file that is not in
   plans/client-id-rename.md, with the reason it changed.
2. Run every acceptance check in the plan and paste the command and its exit code.
3. Confirm that no existing test assertion changed except field-name updates:
   list every modified `expect`/`assert` line.
4. List the edge cases this change could have missed (null ids, bulk
   endpoints, cached responses, webhook payloads) and, for each, the test that
   covers it or "NOT COVERED".
Write the result to plans/client-id-rename-evidence.md.

Każda linia „NOT COVERED” to albo test do dopisania, albo ryzyko, które recenzent akceptuje na piśmie.

Co psuje się przy edycji wielu plików i jak z tego wyjść?

Objaw	Prawdopodobna przyczyna	Wyjście
Claude Code edytuje plik spoza planu	Śledzenie zależności pominęło wywołanie albo agent zbacza z kursu	Zatrzymaj sesję klawiszem Esc. Poproś o wyjaśnienie edycji, potem zaktualizuj plik planu albo cofnij się przez `/rewind`.
Błędy typów lub brakujące importy po warstwie	Warstwa zmieniła sygnaturę, na której opiera się następna	Wklej wynik sprawdzania: „Fix these errors from the rename without changing behaviour or test assertions.”
Stara nazwa zostaje w komentarzach, fixture’ach lub dokumentacji	Zmiana rozciągnęła się na kilka promptów, a wyszukiwanie było tylko tekstowe	Uruchom kontrolę z ripgrepem i poproś o poprawienie lub uzasadnienie każdego pozostałego trafienia.
Odpowiedzi stają się ogólnikowe, wcześniejsze decyzje giną	Okno kontekstu zapełniło się w długiej sesji	`/compact` z jawnymi instrukcjami, co zachować, albo `/clear` i ponowne zakotwiczenie na pliku planu.
Testy przechodzą, bo zmieniono asercje	Agent „naprawił” test zamiast kodu	Przywróć plik testu (`git restore --source=main -- path/to/test`) i napisz w prompcie, że asercje są tylko do odczytu.
Jeden strumień się psuje, reszta działa	Niezwiązana praca zmieszana w jednej sesji	Cofnij tylko tę część promptem do chirurgicznego odzyskiwania poniżej.

Do cofania używaj najmniejszego narzędzia, które wystarczy:

/rewind                                    # w Claude Code: powrót do punktu kontrolnego, kod i rozmowa
git restore path/to/file.ts                # w terminalu: odrzuć niezacommitowane zmiany w jednym pliku
git revert <commit>                        # cofnij jedną zacommitowaną warstwę, zachowując historię
git stash push -m "failed-rename-attempt"  # odłóż wszystko i zacznij od czystego drzewa

The rename broke the payment flow, but the logging changes on this branch are
correct. Revert only the payment-related edits so those files match main, keep
everything else, and run the acceptance checks. Then explain in three sentences
what the payment change got wrong, and add that as a rule to the plan file so
the next attempt avoids it.

Dokąd dalej przy zmianach w wielu plikach

Przed tą stroną: planowanie funkcji zamienia prośbę w plan, który ten proces wykonuje.
Dalej: wzorce refaktoryzacji z przepisami na wydzielanie, przenoszenie i restrukturyzację.
Praca w dużej bazie kodu, gdy zasięg zmiany jest zbyt duży, by zaplanować go w jednym przebiegu.
Własne subagenty, by przenieść śledzenie zależności i przegląd poza główny kontekst.
Debugowanie, gdy zmiana w wielu plikach wprowadzi błąd, którego kontrole nie złapały.
Kontrola kosztów, by długie, wielowarstwowe sesje nie drożały.
Ten sam proces w innych narzędziach: worktree w Codex i praca na wielu repozytoriach w Cursorze.