Refaktoryzacja na duza skale z Worktree
Twoj zespol zdecydowal sie na migracje z Express do Hono, przejscie z callbackow na async/await w starszej warstwie danych i zmiane nazwy kazdego getUserById na nowa konwencje findUser — wszystko przed nastepnym duzym wydaniem. To setki plikow w dziesieciach modulow. Zrobienie tego w jednej galezi oznacza dwutygodniowe zamrozenie kodu. Zrobienie tego z worktree Codex oznacza rownolegla, przyrostowa migracje z testami uruchamianymi na kazdym kroku.
Co wyniesiesz z tej lekcji
Dział zatytułowany „Co wyniesiesz z tej lekcji”- Proces refaktoryzacji oparty na planowaniu, ktory rozbija duze zmiany na bezpieczne, rownolegle partie
- Wzorce worktree do izolowania pracy refaktoryzacyjnej, aby glowna galaz pozostala mozliwa do wdrozenia
- Prompty zapewniajace, ze Codex uruchamia testy po kazdym kroku refaktoryzacji, wylapujac regresje natychmiast
- Wzorzec delegowania do chmury dla zadan refaktoryzacyjnych trwajacych dluzej niz lokalna sesja
Workflow
Dział zatytułowany „Workflow”Krok 1: Zaplanuj refaktoryzacje w IDE
Dział zatytułowany „Krok 1: Zaplanuj refaktoryzacje w IDE”Uzyj rozszerzenia IDE lub Codex App w trybie Local, aby stworzyc szczegolowy plan refaktoryzacji. Plan jest krytyczny — bez niego rownolegli agenci beda wprowadzac sprzeczne zmiany.
Jesli skill $plan jest dostepny, wygeneruje on ustrukturyzowany plan z kamieniami milowymi. Przejrzyj i dostosuj plan przed wykonaniem — to tutaj wylapujesz problemy takie jak “middleware auth jest uzywany przez kazda grupe tras, wiec musi byc zmigrowany jako pierwszy.”
Krok 2: Zmigruj wspoldzielona infrastrukture jako pierwsza
Dział zatytułowany „Krok 2: Zmigruj wspoldzielona infrastrukture jako pierwsza”Obsluz wspoldzielone zaleznosci w trybie Local, aby kazdy kolejny worktree odziedziczyI 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 galezi funkcji. Kazdy worktree utworzony od tego momentu bedzie mial dostepne zarowno middleware Express, jak i Hono.
Krok 3: Wykonaj partie w rownoleglych worktree
Dział zatytułowany „Krok 3: Wykonaj partie w rownoleglych worktree”Teraz uruchom watek worktree dla kazdej grupy tras. Kazdy agent migruje swoja partie niezaleznie, a poniewaz dotykaja roznych plikow, wyniki laczasie 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)
Kazdy worktree uruchamia wlasny zestaw testow. Jesli migracja popsuje testy, agent naprawia to w obrebie worktree zanim w ogole zobaczysz diff.
Krok 4: Przejrzyj i merguj przyrostowo
Dział zatytułowany „Krok 4: Przejrzyj i merguj przyrostowo”W miare jak kazdy worktree konczy prace, przejrzyj diff w panelu recenzji App. Szukaj:
- Sciezek importu, ktore nie zostaly w pelni zaktualizowane
- Middleware, ktory zostal pominiety
- Testow, ktore zostaly zmodyfikowane, zeby przechodzily, zamiast faktycznie testowac nowe zachowanie
Uzyj Create branch here na kazdym worktree, wypchnij na remote i otworz PR. To pozwala twojemu zespolowi recenzowac kazda partie niezaleznie, zamiast mierzyc sie z mega-PR-em na 500 plikow.
Krok 5: Deleguj sprzatanie do chmury
Dział zatytułowany „Krok 5: Deleguj sprzatanie do chmury”Po zmigrowaniy wszystkich grup tras faza sprzatania (usuwanie Express, kasowanie warstwy kompatybilnosci, aktualizacja dokumentacji) moze byc uruchomiona w zadaniu chmurowym:
Z CLI wyslij to jako zadanie chmurowe z wieloma probami, aby zapewnic dokladne sprzatanie:
codex cloud exec --env my-env --attempts 2 "Perform post-Express-to-Hono migration cleanup..."Gdy cos sie nie uda
Dział zatytułowany „Gdy cos sie nie uda”Rownolegle worktree modyfikuja ten sam plik. Jesli dwie grupy tras wspoldziela plik narzedzi wymagajacy aktualizacji, oba worktree zmodyfikuja go niezaleznie. Druga synchronizacja bedzie kolidowac. Zapobiegaj temu identyfikujac wspoldzielone pliki w fazie planowania i migrujac je w kroku 2 (krok fundamentowy) przed zrownolegleniem.
Testy przechodza w worktree, ale nie po zmergowaniu. Zazwyczaj oznacza to, ze test dzialal na stanie worktree, ktory nie zawieral zmian z innych worktree. Po zmergowaniu kazdej partii zawsze uruchamiaj pelny zestaw testow z lokalnego checkoutu, aby wylapac problemy integracyjne.
Codex sprawia, ze test przechodzi oslabajac asercje. To subtelna porazka: zamiast naprawiac kod, aby pasowal do testu, Codex zmienia oczekiwana wartosc testu. Dolacz “do NOT weaken or remove existing test assertions. If a test fails, fix the implementation, not the test” w swoich ograniczeniach.
Czyszczenie worktree usuwa partie, ktorej nie zmergowales. Jesli recenzja partii trwa dluzej niz 4 dni (i masz wiecej niz 10 worktree), Codex moze ja usunac. Przypnij watek lub dodaj worktree do paska bocznego, aby zapobiec czyszczeniu. Codex zapisuje migawke przed usunieciem, wiec mozesz przywrocic z widoku watku jesli to konieczne.
Plan refaktoryzacji pomija zaleznosc. Jesli plan mowi “trasy auth nie zaleza od tras users”, ale faktycznie wspoldziela helper walidacji sesji, rownolegla migracja da niespojne wyniki. Zweryfikuj plan pytajac Codex: “Check the dependency graph between these route groups. Are there any shared imports I missed?”