Refaktoryzacja na dużą skalę z Worktree

Refaktoryzacja na dużą skalę z worktree dzieli migrację obejmującą setki plików — jak przejście z Express na Hono — na plan, krok współdzielonej infrastruktury najpierw w trybie Local i niezależne partie, z których każda działa we własnym worktree i łączy się przyrostowo. Uruchamianie testów po każdym kroku wyłapuje regresje, a główna gałąź pozostaje możliwa do wdrożenia, zamiast wielotygodniowego zamrożenia kodu.

Twój zespół zdecydował się na migrację z Express do Hono, przejście z callbacków na async/await w starszej warstwie danych i zmianę nazwy każdego getUserById na nową konwencję findUser — wszystko przed następnym dużym wydaniem. To setki plików w dziesiątkach modułów. Zrobienie tego w jednej gałęzi oznacza dwutygodniowe zamrożenie kodu. Zrobienie tego z worktree Codex oznacza równoległą, przyrostową migrację z testami uruchamianymi na każdym kroku.

Co wyniesiesz z refaktoryzacji opartej na worktree

Proces refaktoryzacji oparty na planowaniu, który rozbija duże zmiany na bezpieczne, równoległe partie
Wzorce worktree do izolowania pracy refaktoryzacyjnej, aby główna gałąź pozostała możliwa do wdrożenia
Prompty zapewniające, że Codex uruchamia testy po każdym kroku refaktoryzacji, wyłapując regresje natychmiast
Wzorzec delegowania do chmury dla zadań refaktoryzacyjnych trwających dłużej niż lokalna sesja

Workflow

Krok 1: Zaplanuj refaktoryzację w IDE

Użyj rozszerzenia IDE lub aplikacja desktopowa ChatGPT (tryb Codex) w trybie Local, aby stworzyć szczegółowy plan refaktoryzacji. Plan jest krytyczny — bez niego równolegli agenci będą wprowadzać sprzeczne zmiany.

Gotowy prompt do planu refaktoryzacji:

$plan

We need to migrate our Express routes to Hono. This affects every file in src/routes/.

Constraints:
- No user-visible behavior changes
- Keep all existing tests passing
- Migrate one route group at a time (auth, users, orders, billing, webhooks)
- Each group should be a standalone commit that can be reviewed independently
- Update any shared middleware that changes API shape

For each migration batch:
1. List the exact files to modify
2. Describe the changes needed (import swaps, handler signature changes, middleware updates)
3. Identify any shared dependencies that need to change first
4. Include a rollback strategy

Produce a step-by-step migration plan with clear milestones.

Jeśli wbudowany skill $plan jest dostępny, wygeneruje on ustrukturyzowany plan z kamieniami milowymi. Przejrzyj i dostosuj plan przed wykonaniem — to tutaj wyłapujesz problemy takie jak “middleware auth jest używany przez każdą grupę tras, więc musi być zmigrowany jako pierwszy.”

Krok 2: Zmigruj współdzieloną infrastrukturę jako pierwszą

Obsłuż współdzielone zależności w trybie Local, aby każdy kolejny worktree odziedziczył zmiany:

Implement Milestone 0 from the refactoring plan: migrate the shared middleware layer.

Specifically:
- Install hono and @hono/node-server
- Create src/middleware/hono/ versions of each Express middleware
- Keep the Express versions working (both frameworks coexist temporarily)
- Update the middleware barrel export to expose both
- Run the full test suite to confirm nothing broke

Do NOT migrate any routes yet. Only shared infrastructure.

Zacommituj to do swojej gałęzi funkcji. Każdy worktree utworzony od tego momentu będzie miał dostępne zarówno middleware Express, jak i Hono.

Krok 3: Wykonaj partie w równoległych worktree

Teraz uruchom wątek worktree dla każdej grupy tras. Każdy agent migruje swoją partię niezależnie, a ponieważ dotykają różnych plików, wyniki łączą się czysto.

Worktree 1: Trasy Auth

Gotowy prompt do migracji grupy tras:

Migrate all routes in src/routes/auth/ from Express to Hono:
- Convert each route handler to Hono's handler signature
- Replace Express middleware references with Hono equivalents from src/middleware/hono/
- Update imports throughout
- Update the corresponding tests in tests/routes/auth/
- Run the auth route tests after migration. Fix any failures.
- Run the full test suite to check for regressions.

Follow the migration pattern documented in the refactoring plan.

Worktree 2: Trasy Users

Migrate all routes in src/routes/users/ from Express to Hono. Same approach as the auth migration -- convert handlers, swap middleware, update tests. Run the full test suite after migration.

Worktree 3: Trasy Orders (ten sam wzorzec, inny katalog)

Worktree 4: Trasy Billing (ten sam wzorzec, inny katalog)

Każdy worktree uruchamia własny zestaw testów. Jeśli migracja popsuje testy, agent naprawia to w obrębie worktree zanim w ogóle zobaczysz diff.

Krok 4: Przejrzyj i merguj przyrostowo

W miarę jak każdy worktree kończy pracę, przejrzyj diff w panelu recenzji App. Szukaj:

Ścieżek importu, które nie zostały w pełni zaktualizowane
Middleware, który został pominięty
Testów, które zostały zmodyfikowane, żeby przechodziły, zamiast faktycznie testować nowe zachowanie

Użyj Create branch here na każdym worktree, wypchnij na remote i otwórz PR. To pozwala twojemu zespołowi recenzować każdą partię niezależnie, zamiast mierzyć się z mega-PR-em na 500 plików.

Krok 5: Deleguj sprzątanie do chmury

Po zmigrowaniu wszystkich grup tras faza sprzątania (usuwanie Express, kasowanie warstwy kompatybilności, aktualizacja dokumentacji) może być uruchomiona w zadaniu chmurowym:

Gotowy prompt do sprzątania po migracji (chmura):

The Express-to-Hono migration is complete. All routes now use Hono handlers. Perform cleanup:

1. Remove express and express-related dependencies from package.json
2. Delete the Express middleware compatibility layer in src/middleware/express/
3. Remove any Express-specific type imports across the codebase
4. Update AGENTS.md to reference Hono instead of Express
5. Update the README setup instructions
6. Run npm install to regenerate the lockfile
7. Run the full test suite to confirm everything passes

Report any remaining Express references that were missed.

Z CLI wyślij to jako zadanie chmurowe z wieloma próbami, aby zapewnić dokładne sprzątanie:

codex cloud exec --env my-env --attempts 2 "Perform post-Express-to-Hono migration cleanup..."

Gdy refaktoryzacja na dużą skalę się psuje

Równoległe worktree modyfikują ten sam plik. Jeśli dwie grupy tras współdzielą plik narzędzi wymagający aktualizacji, oba worktree zmodyfikują go niezależnie. Druga synchronizacja będzie kolidować. Zapobiegaj temu identyfikując współdzielone pliki w fazie planowania i migrując je w kroku 2 (krok fundamentowy) przed zrównolegleniem.

Testy przechodzą w worktree, ale nie po zmergowaniu. Zazwyczaj oznacza to, że test działał na stanie worktree, który nie zawierał zmian z innych worktree. Po zmergowaniu każdej partii zawsze uruchamiaj pełny zestaw testów z lokalnego checkoutu, aby wyłapać problemy integracyjne.

Codex sprawia, że test przechodzi osłabiając asercje. To subtelna porażka: zamiast naprawiać kod, aby pasował do testu, Codex zmienia oczekiwaną wartość testu. Dołącz “do NOT weaken or remove existing test assertions. If a test fails, fix the implementation, not the test” w swoich ograniczeniach.

Czyszczenie worktree usuwa partię, której nie zmergowałeś. ChatGPT desktop domyślnie zachowuje 15 ostatnich zarządzanych worktree. Przypnij aktywną pracę albo promuj worktree do stałego projektu, a przy dużej refaktoryzacji zmień retencję w ustawieniach Worktree.

Plan refaktoryzacji pomija zależność. Jeśli plan mówi “trasy auth nie zależą od tras users”, ale faktycznie współdzielą helper walidacji sesji, równoległa migracja da niespójne wyniki. Zweryfikuj plan pytając Codex: “Check the dependency graph between these route groups. Are there any shared imports I missed?”

Dokąd dalej po refaktoryzacji w worktree

Recenzja kodu wspierana przez AI Użyj /review do wyłapywania problemów w zrefaktoryzowanym kodzie zanim trafi do współpracowników

Modernizacja bazy kodu na dużą skalę Zastosuj te wzorce refaktoryzacji do pełnych migracji frameworków i modernizacji kodu legacy