Refaktoryzacja na dużą skalę z Worktree
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 tej lekcji
Dział zatytułowany „Co wyniesiesz z tej lekcji”- 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
Dział zatytułowany „Workflow”Krok 1: Zaplanuj refaktoryzację w IDE
Dział zatytułowany „Krok 1: Zaplanuj refaktoryzację w IDE”Użyj rozszerzenia IDE lub Codex App w trybie Local, aby stworzyć szczegółowy plan refaktoryzacji. Plan jest krytyczny — bez niego równolegli agenci będą wprowadzać sprzeczne zmiany.
Jeśli 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ą
Dział zatytułowany „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
Dział zatytułowany „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
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
Dział zatytułowany „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
Dział zatytułowany „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:
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 coś się nie uda
Dział zatytułowany „Gdy coś się nie uda”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ś. Jeśli recenzja partii trwa dłużej niż 4 dni (i masz więcej niż 10 worktree), Codex może ją usunąć. Przypnij wątek lub dodaj worktree do paska bocznego, aby zapobiec czyszczeniu. Codex zapisuje migawkę przed usunięciem, więc możesz przywrócić z widoku wątku jeśli to konieczne.
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?”