Przepływy wielu plików

Nowoczesny rozwój oprogramowania rzadko obejmuje zmiany w pojedynczych plikach. Niezależnie od tego, czy implementujesz funkcje, refaktoryzujesz kod, czy naprawiasz błędy, zmiany zazwyczaj rozchodzą się po wielu plikach. Claude Code doskonale radzi sobie z koordynowaniem tych złożonych operacji wieloplikowych, utrzymując spójność podczas obsługi skomplikowanych zależności, które sprawiają, że ręczne aktualizacje są podatne na błędy. Ten przewodnik ujawnia wzorce orkiestracji zmian obejmujących całą bazę kodu.

Zrozumienie kontekstu wielu plików

Holistyczny widok Claude

Claude Code nie tylko edytuje pliki w izolacji – rozumie relacje między nimi. Gdy opisujesz zmianę, Claude automatycznie:

• Śledzi zależności aby znaleźć wszystkie dotknięte pliki
• Utrzymuje spójność między interfejsami i kontraktami
• Aktualizuje powiązane testy i dokumentację
• Zachowuje wzorce architektoniczne podczas zmian

Przewaga agentic search

Claude używa “agentic search” aby zrozumieć strukturę Twojej bazy kodu. Zamiast wymagać od Ciebie określenia każdego pliku, aktywnie eksploruje aby znaleźć gdzie zmiany muszą nastąpić. Oznacza to, że może obsłużyć zadania takie jak “refaktoryzuj moduł auth aby używał JWT” bez wymieniania przez Ciebie każdego pliku związanego z auth.

Planowanie operacji wieloplikowych

Przed zagłębieniem się w zmiany kodu, wykorzystaj możliwości planowania Claude:

1. Poproś o plan zmian

   "Musimy dodać role użytkowników do naszej aplikacji.
   Zaplanuj niezbędne zmiany ale jeszcze nie implementuj."

2. Przejrzyj proponowane podejście Claude może odpowiedzieć z:

   • Baza danych: Dodaj tabelę ról i tabelę junction user_roles
   • Backend: Zaktualizuj model User, dodaj middleware sprawdzający role
   • Frontend: Dodaj UI zarządzania rolami, zaktualizuj uprawnienia
   • Testy: Testy jednostkowe dla logiki ról, testy integracyjne

3. Doprecyzuj i zatwierdź

   "Dobry plan. Dołącz też dashboard administratora do zarządzania rolami."

4. Wykonaj systematycznie

   "Zacznijmy od zmian w bazie danych"

Częste wzorce wielu plików

Implementacja funkcji

Podczas implementacji funkcji dotykających wielu warstw:

Funkcja full-stack

"Zaimplementuj system komentarzy dla postów blogowych:
- Baza danych: tabela komentarzy z user_id, post_id, content
- API: endpointy CRUD dla komentarzy
- Frontend: komponenty wyświetlania i wysyłania komentarzy
- Aktualizacje w czasie rzeczywistym używając websockets
- Obsługa zagnieżdżonych odpowiedzi na komentarze"

# Claude będzie:
1. Tworzyć pliki migracji
2. Dodawać definicje modeli
3. Implementować trasy API
4. Budować komponenty React
5. Konfigurować handlery websocket
6. Aktualizować odpowiednie testy

Integracja API

"Zintegruj przetwarzanie płatności Stripe:
- Utwórz moduł serwisu płatności
- Dodaj handlery webhook dla zdarzeń
- Zaktualizuj model użytkownika ze statusem subskrypcji
- Dodaj komponenty UI płatności
- Obsłuż przypadki błędów gracefully
- Zaktualizuj zmienne środowiskowe"

# Claude koordynuje:
- Implementację warstwy serwisowej
- Aktualizacje schematu bazy danych
- Przepływy płatności frontend
- Zmiany konfiguracyjne
- Obsługę błędów między warstwami

Przepływ uwierzytelniania

"Przełącz z uwierzytelniania opartego na sesji na JWT:
- Zaktualizuj endpoint logowania aby zwracał JWT
- Utwórz middleware JWT
- Zaktualizuj wszystkie chronione trasy
- Zmodyfikuj obsługę auth frontend
- Zaktualizuj konfigurację klienta API
- Zachowaj kompatybilność wsteczną"

# Claude obsłuży:
- Systematyczne aktualizacje endpointów
- Refaktoryzację middleware
- Zmiany stanu auth frontend
- Logikę odświeżania tokenów
- Strategię migracji

Operacje refaktoryzacji

Przemianowywanie w bazie kodu

# Proste przemianowanie
"Przemianuj 'customerId' na 'clientId' w całej bazie kodu"

# Claude będzie:
- Znajdować wszystkie wystąpienia w modelach, API, bazie danych
- Aktualizować nazwy zmiennych, parametry funkcji
- Modyfikować migracje bazy danych
- Aktualizować testy i dokumentację
- Zapewniać spójne nazewnictwo

Wyciąganie wspólnej logiki

# Wyciągnij wspólną funkcjonalność
"Wyciągnij logikę walidacji z UserController,
OrderController i ProductController do wspólnego
serwisu walidacji"

# Claude będzie:
- Identyfikować wspólne wzorce
- Tworzyć nowy serwis walidacji
- Aktualizować wszystkie kontrolery
- Utrzymywać istniejące interfejsy
- Dodawać odpowiednie testy

Przekształcanie architektury

# Główna zmiana architektoniczna
"Konwertuj nasz monolityczny serwis na oddzielne
mikrousługi dla użytkowników, zamówień i inwentarza"

# Claude będzie:
- Planować granice serwisów
- Wyciągać logikę domenową
- Tworzyć interfejsy serwisów
- Konfigurować komunikację między serwisami
- Aktualizować konfiguracje wdrożenia

Zagadnienia przekrojowe

Podczas implementacji funkcji wpływających na całą aplikację:

Implementacja logowania

"Dodaj strukturalne logowanie wszędzie:
- Używaj Winston dla serwisów Node.js
- Dołącz śledzenie ID żądania
- Dodaj metryki wydajności
- Upewnij się że PII nie jest logowane
- Zaktualizuj wszystkie handlery błędów"

Obsługa błędów

"Standaryzuj obsługę błędów:
- Utwórz niestandardowe klasy błędów
- Dodaj globalny middleware błędów
- Zaimplementuj error boundaries w React
- Dodaj śledzenie błędów z Sentry
- Zaktualizuj wszystkie bloki try-catch"

Internacjonalizacja

"Dodaj obsługę i18n:
- Skonfiguruj react-i18next
- Wyciągnij wszystkie zakodowane stringi
- Utwórz pliki tłumaczeń
- Dodaj przełącznik języka
- Zaktualizuj formatowanie dat/liczb"

Nagłówki bezpieczeństwa

"Implementuj najlepsze praktyki bezpieczeństwa:
- Dodaj konfigurację CORS
- Ustaw nagłówki bezpieczeństwa
- Zaimplementuj rate limiting
- Dodaj walidację wejścia
- Zaktualizuj sprawdzenia uwierzytelniania"

Zarządzanie zależnościami

Zrozumienie promienia wpływu

Claude doskonale rozumie jak zmiany się propagują:

Wskazówka

Poproś Claude o analizę zależności przed wprowadzaniem zmian:

"Jakie pliki będą dotknięte jeśli zmienię schemat modelu User?"

Obsługa zmian łamiących

Dla zmian które mogą złamać istniejącą funkcjonalność:

1. Dodaj kompatybilność wsteczną

   "Dodaj nowe pole 'clientId' zachowując 'customerId'
   dla kompatybilności wstecznej"

2. Utwórz okres migracji

   "Zaktualizuj cały kod wewnętrzny aby używał 'clientId' ale wciąż
   akceptuj 'customerId' w żądaniach API"

3. Oznacz stare użycie jako przestarzałe

   "Dodaj ostrzeżenia o deprecacji dla użycia 'customerId'"

4. Zakomplektuj migrację

   "Usuń 'customerId' całkowicie po potwierdzeniu
   braku aktywnego użycia"

Koordynowanie zmian typów

Podczas pracy z TypeScript lub innymi językami typowanymi:

// Claude automatycznie obsługuje propagację typów
"Zaktualizuj interfejs User aby zawierał tablicę 'roles'.
Zaktualizuj wszystkie interfejsy i implementacje TypeScript
które używają User."

// Claude będzie:
// 1. Aktualizować interfejs User
// 2. Znajdować wszystkie pliki importujące User
// 3. Aktualizować sygnatury funkcji
// 4. Naprawiać błędy typów
// 5. Aktualizować testy z nowymi typami

Koordynacja między repozytoriami

Podczas gdy Claude pracuje na jednym repozytorium na raz, możesz koordynować zmiany między wieloma repo:

Sekwencyjne aktualizacje repozytoriów

Zmiany kontraktu API

# Repozytorium 1: Serwis API
cd api-service
claude "Zaktualizuj endpoint /users aby zwracał 'clientId'
zamiast 'customerId'"

# Repozytorium 2: Frontend
cd ../frontend-app
claude "API teraz zwraca 'clientId' zamiast
'customerId'. Zaktualizuj wszystkie wywołania API i obsługę danych"

# Repozytorium 3: Aplikacja mobilna
cd ../mobile-app
claude "Zaktualizuj aby obsługiwać nowe pole 'clientId' z API,
utrzymując kompatybilność ze starszymi wersjami aplikacji"

Aktualizacje współdzielonych bibliotek

# Zaktualizuj współdzieloną bibliotekę
cd shared-utils
claude "Dodaj nowe funkcje walidacji dla email i telefonu"

# Zaktualizuj każdy konsumujący serwis
for service in user-service order-service notification-service; do
  cd ../$service
  claude "Zaktualizuj aby używać nowych funkcji walidacji z
  biblioteki shared-utils wersja 2.0"
done

Utrzymywanie spójności

Aby zapewnić spójne aktualizacje między repozytoriami:

1. Utwórz standardowy szablon promptu

   CHANGE_DESC="Zastąp wszystkie console.log naszą klasą Logger"
   
   # Zastosuj do każdego repo
   claude "$CHANGE_DESC"

2. Dokumentuj wzorzec zmiany

   # W CLAUDE.md każdego repo
   Ostatnie aktualizacje:
   - 2024-01-15: Migracja z customerId na clientId
   - API zwraca clientId we wszystkich odpowiedziach
   - Kolumna bazy danych przemianowana z migracją

3. Używaj poleceń weryfikacyjnych

   # Po aktualizacjach, zweryfikuj spójność
   claude "Zweryfikuj że nie pozostały referencje do customerId"

Zaawansowane wzorce

Równoległy rozwój z Git worktrees

Zmaksymalizuj efektywność pracując nad wieloma funkcjami jednocześnie:

# Skonfiguruj worktrees dla równoległej pracy
git worktree add ../feature-auth feature/authentication
git worktree add ../feature-payments feature/payments
git worktree add ../feature-analytics feature/analytics

# Uruchom Claude w każdym worktree
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'

Stopniowe wdrażanie

Dla złożonych zmian wieloplikowych w produkcji:

1. Podejście z flagami funkcji

   "Zaimplementuj nowy system uwierzytelniania za flagą
   funkcji 'USE_NEW_AUTH'. Zaktualizuj wszystkie sprawdzenia auth
   aby warunkowo używały starego lub nowego systemu"

2. Stopniowa migracja

   "Zaktualizuj 10% sprawdzeń auth aby używały nowego systemu.
   Oznacz zaktualizowane lokalizacje komentarzem //NEW_AUTH"

3. Monitoruj i rozwijaj

   "Znajdź wszystkie komentarze //NEW_AUTH i zaktualizuj
   pozostałe stare sprawdzenia auth w pobliżu"

4. Sprzątanie

   "Usuń flagę funkcji i kod starego systemu auth"

Zmiany wieloplikowe oparte na testach

Zapewnij poprawność w złożonych zmianach:

# 1. Napisz testy najpierw
"Utwórz kompleksowe testy dla nowego systemu kontroli
dostępu opartego na rolach"

# 2. Implementuj między plikami
"Zaimplementuj RBAC aby wszystkie testy przechodziły. Zaktualizuj modele,
middleware i komponenty UI w razie potrzeby"

# 3. Zweryfikuj pokrycie
"Sprawdź pokrycie testów i dodaj brakujące przypadki testowe"

Względy wydajnościowe

Zarządzanie oknem kontekstu

Dla dużych operacji wieloplikowych:

Zarządzanie kontekstem

RÓB:

• Używaj /clear między głównymi fazami
• Skup się na jednym podsystemie na raz
• Pozwól Claude zaplanować przed implementacją
• Commituj zmiany przyrostowo

NIE RÓB:

• Próbuj zmieniać wszystko naraz
• Zachowuj niepotrzebny kontekst
• Pomijaj kroki weryfikacji
• Ignoruj sugestie Claude dotyczące rozbicia zadań

Optymalizacja operacji wieloplikowych

# Efektywne podejście
"Wymień wszystkie pliki wymagające aktualizacji dla dodania ról użytkowników"
# Pozwól Claude zidentyfikować pliki

"Zaktualizuj najpierw schemat bazy danych i modele"
# Ukończ jedną warstwę

"Teraz zaktualizuj endpointy API"
# Przejdź do następnej warstwy

"Na koniec, zaktualizuj komponenty UI"
# Zakończ z prezentacją

# Mniej efektywne podejście
"Dodaj kompletną funkcję ról użytkowników do wszystkiego"
# Zbyt szerokie, może przeoczyć przypadki graniczne

Częste pułapki i rozwiązania

Uważaj na

• Zależności cykliczne - Claude ostrzeże ale zweryfikuj
• Brakujące importy - Uruchom swój linter po zmianach
• Niespójne nazewnictwo - Przejrzyj wybory nazewnictwa Claude
• Zapomniane przypadki graniczne - Poproś Claude o wylistowanie przypadków granicznych
• Luki w pokryciu testów - Poproś o aktualizacje testów explicite

Strategie odzyskiwania

Gdy operacje wieloplikowe idą źle:

1. Git na ratunek

   # Przejrzyj wszystkie zmiany
   git status
   git diff
   
   # Selektywne odzyskiwanie
   git checkout -- specific-file.js
   
   # Lub pełny reset jeśli potrzeba
   git reset --hard HEAD

2. Przyrostowe poprawki

   "Refaktoryzacja zepsuła przepływ płatności.
   Napraw tylko zmiany związane z płatnościami zachowując
   inne ulepszenia"

3. Wycofanie z nauką

   "Cofnij ostatni zestaw zmian i zaktualizuj
   CLAUDE.md z tym czego się nauczyliśmy o
   zależnościach które przegapiliśmy"

Podsumowanie najlepszych praktyk

Lista kontrolna mistrzostwa wielu plików

✅ Zawsze poproś o plan przed implementacją złożonych zmian ✅ Dziel duże operacje na logiczne fazy ✅ Utrzymuj spójność w nazewnictwie i wzorcach ✅ Aktualizuj testy wraz z implementacją ✅ Dokumentuj znaczące zmiany architektoniczne ✅ Używaj kontroli wersji strategicznie ✅ Zweryfikuj że zmiany działają razem przed commitem ✅ Utrzymuj skoncentrowany kontekst z /clear ✅ Wykorzystuj zdolność Claude do śledzenia zależności ✅ Testuj przypadki graniczne i warunki błędów

Podsumowanie

Przepływy wieloplikowe to miejsce gdzie Claude Code naprawdę błyszczy, przekształcając złożone, podatne na błędy ręczne aktualizacje w systematyczne, spójne transformacje. Rozumiejąc jak wykorzystać holistyczny widok Claude na Twoją bazę kodu, możesz pewnie podejmować się refaktoryzacji, implementować funkcje przekrojowe i utrzymywać duże aplikacje z łatwością. Kluczem jest praca z Claude jako partnerem – pozwól mu planować, kieruj jego wykonaniem i weryfikuj wyniki. Z tymi wzorcami będziesz obsługiwać zmiany wieloplikowe, które wcześniej zajmowały dni, w zaledwie godziny, z lepszą spójnością i mniejszą liczbą błędów.