Przepływy wielu plików

Musisz przemianować pole, które przewija się przez kilkanaście plików — model, serwis, trzy kontrolery, migrację, kontrakt API i ścianę testów. Zrób to ręcznie, a przeoczysz dwóch wywołujących i wypuścisz błąd 500. To dokładnie ten rodzaj zmiany, do którego stworzono Claude Code: śledzi graf zależności, edytuje każdy plik spójnie i aktualizuje testy w tym samym przebiegu. Cała sztuka polega na tym, by sterować nim tak, aby zachował dokładność na całym obszarze rażenia.

Co z tego wyniesiesz

• Prompt zaczynający od planu, który zmusza Claude do zmapowania obszaru rażenia, zanim dotknie choćby jednego pliku
• Powtarzalny wzorzec bezpiecznego, kompatybilnego wstecznie przemianowywania pól i API
• Gotowe do wklejenia prompty do refaktoryzacji przekrojowych (wyciąganie wspólnej logiki, propagacja typów, śledzenie zależności)
• Prawdziwy sposób na równoległe uruchamianie niezależnych zadań wieloplikowych przy użyciu git worktrees
• Plan odzyskiwania na wypadek, gdy edycja wielu plików pójdzie nie tak w trakcie

Zaplanuj, zanim dotkniesz kodu

Największy pojedynczy zysk dokładności przy zmianach wieloplikowych to oddzielenie planowania od edycji. Najpierw uruchom Claude w trybie planowania (claude --permission-mode plan lub naciśnij Shift+Tab, aby się do niego przełączyć), pozwól mu eksplorować i zaproponować rozwiązanie, a potem zatwierdź zanim zapisany zostanie jakikolwiek plik.

1. Poproś o plan zmiany, a nie o samą zmianę. Claude eksploruje bazę kodu i raportuje, czego zamierza dotknąć — bez edytowania.

2. Przejrzyj obszar rażenia. To tutaj wyłapiesz brakujące pliki lub błędne założenia, gdy poprawienie ich jest darmowe, zamiast w diffie 40 plików.

3. Dopracuj, potem zatwierdź. Dodaj wszystko, co pominął, a następnie pozwól mu wykonać zatwierdzony plan warstwa po warstwie.

Wskazówka

Gotowy do wklejenia prompt do zmiany wieloplikowej zaczynającej od planu:

We need to add user roles to the app. Before changing anything, produce a plan:
- list every file you'll modify, grouped by layer (DB migration, models, middleware, API routes, UI, tests)
- name the new tables/columns and the role-check seam
- call out anything that could break existing callers
Do NOT edit any files yet. Wait for my approval.

Tryb planowania jest z założenia tylko do odczytu, więc można go bezpiecznie uruchomić nawet na main. Gdy plan wygląda dobrze, zatwierdź go, a Claude przełączy się na wykonanie.

Najpierw prześledź graf zależności

Przed przemianowaniem lub zmianą schematu każ Claude wydobyć wszystko, co zależy od rzeczy, którą zaraz przeniesiesz. To szybsze i bardziej niezawodne niż grep, bo podąża za importami i typami, a nie tylko za tekstem.

Wskazówka

Gotowy do wklejenia prompt do zmapowania wpływu przed zmianą schematu:

What files will break if I change the `User` model schema to add a `roles: string[]`
field? Trace importers, type usages, serializers, and tests. Return a grouped checklist
of files with a one-line reason each. Don't edit anything yet.

Użyj zwróconej listy kontrolnej jako kontraktu dla przebiegu edycji. Jeśli Claude później zedytuje plik, którego nie było na liście, to sygnał, by się zatrzymać i ponownie sprawdzić plan.

Bezpieczne przemianowania w całej bazie kodu

Przemianowanie wygląda na błahostkę, dopóki nie chodzi o publiczne pole, od którego zależą zewnętrzni klienci. Wzorzec, który przeżyje na produkcji, to dodaj-potem-wycofaj, a nie wyrwij-i-zastąp.

1. Dodaj nową nazwę obok starej. Niech obie działają, żeby nic się nie zepsuło przy wdrożeniu.

2. Zmigruj wewnętrznych wywołujących na nową nazwę, podczas gdy API nadal akceptuje starą.

3. Oznacz starą nazwę jako przestarzałą z ostrzeżeniem, żebyś widział pozostałe użycia.

4. Usuń starą nazwę, gdy telemetria potwierdzi brak aktywnych wywołujących.

Wskazówka

Gotowy do wklejenia prompt do kompatybilnego wstecznie przemianowania:

Rename `customerId` to `clientId` across the codebase, but keep backward compatibility:
- add `clientId` everywhere the value is produced
- have the API still ACCEPT `customerId` on input and map it to `clientId`
- update models, serializers, and tests to use `clientId`
- add a deprecation log line wherever inbound `customerId` is still received
Show me the file list you'll change before editing.

W językach typowanych oprzyj się na zdolności Claude do propagowania typów, zamiast ręcznie gonić za błędami kompilatora:

Wskazówka

Gotowy do wklejenia prompt do propagacji typów w TypeScript:

Add a `roles: Role[]` field to the `User` interface. Then find every file that imports
`User`, update function signatures and call sites, and fix the resulting type errors.
Run the type-checker when you're done and fix anything that's still red.

Refaktoryzacje przekrojowe

Gdy logika jest zduplikowana w kontrolerach lub serwisach, poproś Claude o jej skonsolidowanie z zachowaniem istniejących publicznych interfejsów — konsolidacja powinna być niewidoczna dla wywołujących.

Wyciąganie wspólnej logiki

Extract the validation logic duplicated in UserController, OrderController, and
ProductController into a single ValidationService. Keep each controller's existing
method signatures unchanged. Add unit tests for the extracted service.

Ujednolicanie obsługi błędów

Standardize error handling across the API: introduce a small set of typed error
classes, route them through one error-handling middleware, and replace ad-hoc
try/catch + res.status(...) blocks with throws. Keep response shapes identical so
clients don't break. Update affected tests.

Przeprowadzenie request ID

Add a request-id that's generated per request and included in every structured log
line for that request. Wire it through the logger and the error handler. Don't log
PII. Show me the middleware and one updated handler before doing the rest.

Gdy refaktoryzacja dotyka systemu połączonego przez MCP — na przykład przemianowania kolumny istniejącej w Twojej rzeczywistej bazie danych — podłączenie serwera MCP Postgres pozwala Claude odczytać żywy schemat zamiast zgadywać z migracji. Ten przepływ opisuje lekcja o wzorcach refaktoryzacji.

Pracuj warstwa po warstwie

Przy dużych zmianach prowadź Claude przez stos po kolei, zamiast prosić o wszystko naraz. Wąskie, sekwencyjne prompty utrzymują skupiony kontekst i sprawiają, że każdy diff da się przejrzeć.

1. "List every file that needs to change for user roles, grouped by layer."
2. "Implement the database migration and model changes only."
3. "Now the role-check middleware and the protected routes."
4. "Now the role-management UI."
5. "Now update and run the tests."

Między niepowiązanymi fazami uruchom /clear, aby porzucić przestarzały kontekst, lub /compact Focus on the role-check seam and the files we've already changed, aby podsumować, zachowując to, co istotne. Użyj /context, aby zobaczyć, co naprawdę zjada okno, oraz /cost, aby obserwować wydatki. To prawdziwe interaktywne polecenia ze slashem — uruchamiaj je wewnątrz REPL claude, a nie jako flagi terminala.

Równoległe uruchamianie niezależnych zadań

Jeśli masz kilka naprawdę niezależnych strumieni pracy — nowy system uwierzytelniania, przepisanie płatności, przegląd analityki — uruchom każdy we własnym git worktree, aby dostały odizolowane katalogi robocze i gałęzie. To udokumentowany sposób na równoległość i utrzymuje kontekst każdego zadania w czystości.

# Jedno worktree (i gałąź) na strumień pracy
git worktree add ../feature-auth feature/authentication
git worktree add ../feature-payments feature/payments
git worktree add ../feature-analytics feature/analytics

# Uruchom Claude Code w każdym worktree (osobne terminale lub panele tmux)
tmux new-session -d -s auth     'cd ../feature-auth && claude'
tmux new-session -d -s payments 'cd ../feature-payments && claude'
tmux new-session -d -s analytics 'cd ../feature-analytics && claude'

Każda sesja to własna rozmowa względem własnego checkoutu, więc edycje nigdy nie kolidują. Gdy skończysz z danym drzewem, użyj git worktree remove ../feature-auth.

Wybierz właściwy mechanizm równoległości:

Mechanizm	Najlepsze do
Git worktrees + jeden claude na drzewo	Niezależne zadania na osobnych gałęziach, które nie mogą dotykać swoich plików.
Subagenty	Wyspecjalizowani pomocnicy w jednej sesji (czysty pod-kontekst, szybkie handoffy) — uruchamiani flagą --agents lub definiowani w .claude/agents/.
Agent teams	Wielu agentów, którzy się koordynują i wymieniają wiadomości; ustaw --teammate-mode i włącz przez CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Jeśli zamiast tego potrzebujesz, by Claude czytał z kilku katalogów w jednej sesji (aplikacja monorepo plus wspólna biblioteka), nie używaj worktrees — dodaj katalogi przez --add-dir:

claude --add-dir ../apps ../lib "Update the shared logger and every app that imports it"

Koordynowanie zmian między repozytoriami

Claude pracuje nad jednym repozytorium naraz, więc zmiany między repozytoriami są sekwencyjne. Najpierw poprowadź producenta, potem każdego konsumenta, i przypnij kontrakt w pliku CLAUDE.md każdego repo, aby przyszłe sesje wiedziały, co się zmieniło.

Zmiana kontraktu API

cd api-service
claude "Update the /users endpoint to return clientId instead of customerId,
but keep accepting customerId on input for one release."

cd ../frontend-app
claude "The /users API now returns clientId (customerId is deprecated).
Update all calls and data handling to read clientId."

cd ../mobile-app
claude "Update to read clientId from the /users API, keeping a fallback to
customerId so older app builds keep working."

Podbicie wersji wspólnej biblioteki

cd shared-utils
claude "Add validateEmail and validatePhone helpers, exported from the package root."

for service in user-service order-service notification-service; do
  cd "../$service"
  claude "Bump shared-utils to the version that adds validateEmail/validatePhone
  and replace local validation with those helpers."
done

Zapisz migrację w każdym repo, aby następna sesja miała kontekst:

<!-- in each repo's CLAUDE.md -->
## Recent migrations
- clientId replaces customerId in /users responses; customerId still accepted on input until v3.

Kiedy to się psuje

Edycje wielu plików zawodzą w przewidywalny sposób. Oto jak wyłapać i odzyskać każdy z nich.

Uwaga

• Edytuje plik, którego nie było w planie. Zatrzymaj się i ponownie uruchom śledzenie zależności — plan był niekompletny, a nieplanowane edycje to miejsce, gdzie kryją się regresje.
• Brakujące importy lub zepsute typy po przemianowaniu. Uruchom linter i type-checker, a potem wklej błędy z powrotem: “Fix these type errors from the rename, don’t change behavior.”
• Niespójne nazewnictwo, bo zmiana objęła kilka promptów. Zapytaj: “Verify no references to customerId remain anywhere, including comments and tests.”
• Dryf kontekstu w długich sesjach. Jeśli odpowiedzi robią się mgliste albo zapomina o wcześniejszych decyzjach, użyj /compact z instrukcjami skupienia lub /clear i zakotwicz ponownie listą kontrolną z planu.
• Zapomniane przypadki graniczne. Zanim zacommitujesz, poproś Claude o ich wyliczenie: “List the edge cases this change might have missed and check each one.”

Gdy przebieg edycji pójdzie nie tak, git jest Twoim cofnięciem:

git status                       # zobacz wszystko, co się zmieniło
git diff                         # przejrzyj, zanim czemukolwiek zaufasz
git checkout -- path/to/file.ts  # cofnij pojedynczy plik
git reset --hard HEAD            # skasuj wszystkie niezacommitowane zmiany i zacznij od nowa

Przy częściowym odzyskiwaniu — zachowaj dobre, porzuć zepsute — opisz to precyzyjnie:

Wskazówka

Gotowy do wklejenia prompt do chirurgicznego odzyskiwania:

The refactor broke the payment flow but the logging changes are fine. Revert only the
payment-related edits to match origin/main, keep everything else, then explain what
the payment change got wrong so we don't repeat it.

Commituj w logicznych fazach w miarę postępów (po migracji, po middleware, po UI). Małe, częste commity zamieniają „cała zmiana jest zepsuta” w „ostatni commit jest zepsuty”.

Co dalej

• Wzorce refaktoryzacji — głębsze przepisy na przemianowywanie, wyciąganie i restrukturyzację
• Przepływy debugowania — gdy zmiana wieloplikowa wprowadza błąd
• Niestandardowe subagenty — wyspecjalizowani pomocnicy do dużych zmian w obrębie jednej sesji
• Kontrola kosztów — utrzymuj duże sesje wieloplikowe tanimi