Strategie refaktoryzacji

Twój plik serwisu użytkowników rozrósł się do 800 linii. Obsługuje uwierzytelnianie, zarządzanie profilami, preferencje powiadomień i usuwanie kont — wszystko w jednym pliku. Każdy deweloper w zespole go modyfikuje z różnych powodów, konflikty merge są ciągłe, a plik testowy ma 1200 linii ściśle powiązanych przypadków testowych. Wiesz, że trzeba go podzielić, ale ostatnim razem, gdy ktoś próbował dużej refaktoryzacji, zepsuło to trzy inne serwisy i stabilizacja zajęła tydzień.

Refaktoryzacja wspomagana AI rozwiązuje problem “zbyt ryzykowne, żeby ruszać”, czyniąc duże refaktoryzacje przyrostowymi, weryfikowalnymi i odwracalnymi. Kluczem jest rozbicie refaktoryzacji na małe, bezpieczne kroki, gdzie każdy krok jest weryfikowany przez istniejący zestaw testów przed przejściem do następnego.

Czego się nauczysz

• Przyrostowy workflow refaktoryzacji utrzymujący zielone testy na każdym kroku
• Gotowe prompty do skopiowania dla najczęstszych wzorców refaktoryzacji
• Strategie refaktoryzacji kodu, od którego zależą inne serwisy
• Techniki wykorzystania checkpointów Cursora i gita do bezpiecznej pracy

Przyrostowy workflow refaktoryzacji

Nigdy nie refaktoryzuj wszystkiego naraz. Zamiast tego:

1. Uruchom pełny zestaw testów. Potwierdź, że przechodzi. Zatwierdź.
2. Dokonaj jednej zmiany strukturalnej (wyciągnij funkcję, przenieś plik, zmień nazwę zmiennej).
3. Uruchom pełny zestaw testów. Jeśli przechodzi, zatwierdź. Jeśli nie przechodzi, napraw konkretne uszkodzenie.
4. Powtarzaj, aż refaktoryzacja będzie kompletna.

Każdy commit to checkpoint, do którego możesz wrócić. Jeśli krok 7 z 10-krokowej refaktoryzacji pójdzie źle, tracisz tylko pracę z kroku 7.

Wskazówka

Prompt do skopiowania — bezpieczna przyrostowa refaktoryzacja:

I need to refactor @src/services/user-service.ts (800 lines) into smaller modules.

Let's do this incrementally. For each step:
1. Make one structural change
2. Update all imports across the codebase
3. Run `npm test` to verify nothing broke
4. Tell me the result before moving to the next step

Start with: Extract the authentication functions (login, logout, refreshToken, validateToken) into a new file @src/services/user/authentication.ts. Create a barrel export in @src/services/user/index.ts that re-exports everything so existing consumers do not break.

Typowe wzorce refaktoryzacji

Wzorzec: Wyciągnij moduł

Podziel duży plik na skoncentrowane moduły, zachowując kompatybilność wsteczną:

Wskazówka

Prompt do skopiowania: Wyciągnij moduł

Extract all payment-related functions from @src/services/order-service.ts into a new @src/services/payment-service.ts.

Functions to move: processPayment, refundPayment, validatePaymentMethod, getPaymentStatus.

Requirements:
- Create the new file with the moved functions
- Update order-service.ts to import from payment-service.ts instead of defining them inline
- Update all other files that import these functions directly
- The public API must not change -- any file that imported from order-service should still work
- Run tests after each file change

Do this step by step. Do not change all files at once.

Wzorzec: Wyciągnij interfejs

Gdy potrzebujesz zmienić sygnaturę funkcji używanej w całej bazie kodu:

Wskazówka

Prompt do skopiowania: Wyciągnij interfejs

The createUser function currently takes 6 positional parameters.
Refactor it to take a single options object.

Before: createUser(email, password, firstName, lastName, role, teamId)
After: createUser({ email, password, firstName, lastName, role, teamId })

Update every caller across the codebase. There are approximately 15 call sites.
Run tests after updating each file to catch any mistakes immediately.

Wzorzec: Migracja z callbacków do async/await

Wskazówka

Prompt do skopiowania: Modernizacja kodu asynchronicznego

Refactor @src/services/data-service.ts to replace all callback-based patterns with async/await.

Rules:
- Preserve all error handling behavior (callbacks with (err, result) must become try/catch)
- Do not change function signatures if they are exported
- Internal helper functions can be updated freely
- Update the test file to use async/await as well

Run the tests after refactoring. If any test fails, the refactoring introduced a behavioral change -- fix it.

Wzorzec: Zmiana nazwy w całej bazie kodu

Wskazówka

Prompt do skopiowania: Zmiana nazwy w całej bazie kodu

Rename the `getUserData` function to `getUserProfile` everywhere in the codebase.

This includes:
- The function definition in @src/services/user-service.ts
- All imports and call sites
- All test references
- Any string references in route definitions or documentation

Run tests after the rename to verify nothing broke.

Refaktoryzacja na dużą skalę z trybem Plan

Dla refaktoryzacji dotykających wielu plików użyj trybu Plan, aby stworzyć ustrukturyzowany plan przed wykonaniem:

Wskazówka

Prompt do skopiowania: Zaplanuj dużą migrację

I need to migrate our API from Express middleware pattern to a controller pattern.

Current structure:
- Routes define middleware chains directly
- Business logic is mixed into route handlers
- Validation happens at the route level

Target structure:
- Routes map URLs to controller methods
- Controllers handle request/response
- Services contain business logic
- Validation middleware is applied automatically

Create a detailed plan. For each step, specify:
- Which files to modify
- What the change is
- How to verify it works

Ask me up to 3 clarifying questions before creating the plan.

Przejrzyj plan, dostosuj priorytety, a następnie wykonuj krok po kroku w trybie Agent.

Strategie bezpieczeństwa

Użyj równoległych agentów do porównania podejść

Dla refaktoryzacji, gdzie istnieje wiele poprawnych podejść, użyj równoległych agentów Cursora (funkcja Best-of-N), aby uruchomić jeden prompt na kilku modelach naraz:

1. Wyślij ten sam prompt refaktoryzacji i wybierz dwa lub więcej modeli
2. Każdy model pracuje we własnym worktree Git, więc nigdy sobie nawzajem nie przeszkadzają
3. Przeklikuj się między kartami poszczególnych modeli, aby porównać diffy obok siebie
4. Kliknij “Apply” na karcie, która jest czystsza i przechodzi testy

Weryfikacja przed PR

Po ukończeniu refaktoryzacji uruchom pełny zestaw weryfikacji przed złożeniem:

Wskazówka

Prompt do skopiowania: Weryfikacja przed PR

The refactoring is complete. Run the following checks and fix any issues:

1. `npm run build` -- TypeScript compilation (fix all type errors)
2. `npm run lint` -- ESLint (fix all lint errors)
3. `npm test` -- Full test suite (fix any failures)
4. `npm run format` -- Code formatting

Iterate until all four pass cleanly. Do not skip any step.

Kiedy coś nie działa

Agent zmienia zbyt wiele plików naraz. Krok refaktoryzacji jest zbyt duży. Podziel na mniejsze kawałki. “Przenieś 3 funkcje do nowego pliku” jest lepsze niż “zreorganizuj całą warstwę serwisów.”

Testy nie przechodzą po refaktoryzacji, ale kod wygląda poprawnie. Testy mogą testować szczegóły implementacji zamiast zachowania. Użyj trybu Ask, aby przeanalizować, czy niepowodzenie testu to prawdziwa regresja, czy test wymagający aktualizacji.

Importy się psują po przeniesieniu plików. Upewnij się, że tworzysz eksporty barrel (pliki index.ts), które re-eksportują z nowych lokalizacji. To zachowuje kompatybilność wsteczną podczas przyrostowej aktualizacji importów.

PR-y innych członków zespołu kolidują z refaktoryzacją. Poinformuj zespół o dużych refaktoryzacjach przed rozpoczęciem. Zmerguj refaktoryzację szybko (w małych PR-ach, jeśli to możliwe), aby zminimalizować okno konfliktu.

Co dalej

• Wzorce testowania — Testy to twoja siatka bezpieczeństwa podczas refaktoryzacji
• Workflow debugowania — Diagnozowanie problemów wprowadzonych podczas refaktoryzacji
• Checkpointy i branchowanie — Strategie git dla bezpiecznej refaktoryzacji