Modernizacja starszego kodu na skalę

Twoja baza kodu ma 80 000 linii JavaScript z 2018 roku — bez TypeScript, callbacki zamiast async/await, komponenty klasowe zamiast hooków i zestaw testów pokrywający 15% kodu. Zarząd chce modernizacji “bez żadnych regresji produkcyjnych”. Ostatni zespół, który próbował przepisania big-bang, spędził sześć miesięcy i nie dostarczył nic. Codex pozwala ci modernizować inkrementalnie: migruj plik po pliku w równoległych worktree, waliduj testami na każdym kroku i używaj zadań w chmurze z wieloma próbami, aby znaleźć najlepszą strategię migracji dla trudnych modułów.

Czego się nauczysz

• Etapowa strategia modernizacji utrzymująca aplikację w stanie wdrażalnym na każdym etapie
• Prompty do typowych migracji: JS do TS, callbacki do async/await, komponenty klasowe do funkcyjnych
• Wzorce zadań w chmurze z podejściem best-of-N dla trudnych decyzji migracyjnych
• Przepis na automatyzację śledzenia postępu migracji co tydzień

Przepływ pracy

Krok 1: Oceń aktualny stan

Przed modernizacją czegokolwiek zrozum, z czym pracujesz. Użyj CLI do szybkiej oceny:

Wskazówka

Prompt do skopiowania — ocena modernizacji:

Assess this codebase for modernization. Report:

1. Language breakdown: how many .js files vs .ts files
2. Module system: CommonJS (require) vs ES modules (import/export)
3. Framework versions: React version, Express version, Node.js target
4. Test coverage: what percentage, what framework, what patterns
5. Dependency age: how many dependencies are more than 2 major versions behind
6. Code patterns: callbacks vs promises vs async/await distribution
7. Component style (if React): class components vs functional components vs hooks

Then propose a prioritized modernization plan with 4-6 phases.
Each phase should be independently deployable (no half-finished migrations).
Estimate the number of files affected by each phase.

Krok 2: Skonfiguruj infrastrukturę migracji

Zanim równoległe agenty zaczną migrować pliki, skonfiguruj narzędzia umożliwiające migrację. Zrób to w trybie Local:

Set up the infrastructure for incremental TypeScript migration:

1. Add tsconfig.json with allowJs: true so existing JS files continue to work
2. Configure the build to handle both .js and .ts files
3. Add @types packages for our dependencies (express, react, etc.)
4. Update ESLint to handle both JS and TS files
5. Create a tsconfig.strict.json that new TS files should target
6. Update CI to run type-check on .ts files only (do not fail on .js files)
7. Add a migration tracking file (scripts/migration-progress.json) that counts JS vs TS files per directory

Run the existing test suite to confirm nothing broke.

Krok 3: Migruj w równoległych partiach

Podziel bazę kodu na partie migracyjne według katalogów. Każda partia działa we własnym worktree. Kluczowa zasada: każda partia musi zostawić aplikację w stanie wdrażalnym.

Worktree 1: Warstwa narzędzi (najniższe ryzyko)

Wskazówka

Prompt do skopiowania — migracja warstwy narzędzi:

Migrate all files in src/utils/ from JavaScript to TypeScript:

For each file:
1. Rename from .js to .ts
2. Add type annotations to all function parameters and return types
3. Replace require() with import statements
4. Replace module.exports with named exports
5. Replace callbacks with async/await where applicable
6. Fix any type errors reported by tsc

Do NOT change the function signatures or behavior.
Run the test suite after each file migration.
If a test fails, fix the migration (not the test).
Update scripts/migration-progress.json with the new counts.

Worktree 2: Warstwa bazodanowa

Migrate all files in src/lib/db/ from JavaScript to TypeScript.
Same approach as the utility migration: rename, add types, convert imports, replace callbacks with async/await.

Additional requirements for database files:
- Type the query results using Drizzle's inferred types
- Replace raw SQL strings with Drizzle query builder calls where possible
- Add return type annotations that match the actual database response shapes

Run tests after each file. Fix any type errors.

Worktree 3: Warstwa serwisów (ten sam wzorzec, src/services/)

Worktree 4: Handlery tras (ten sam wzorzec, src/routes/)

Krok 4: Użyj zadań w chmurze dla trudnych migracji

Niektóre pliki są trudniejsze do migracji niż inne — głęboko zagnieżdżone callbacki, złożone hierarchie klas lub moduły z niejawnym stanem globalnym. Dla nich użyj zadań w chmurze z --attempts, aby eksplorować różne strategie migracji.

Wskazówka

Prompt do skopiowania — trudna migracja (chmura, best-of-N):

Migrate src/services/legacy-payment-processor.js to TypeScript.

This file has:
- Deeply nested callbacks (6 levels deep in some paths)
- Implicit dependency on global config object
- Class inheritance with 3 levels of subclasses
- No existing tests

Migration requirements:
- Convert callbacks to async/await (flatten the nesting)
- Make the config dependency explicit (pass as constructor parameter)
- Add comprehensive type annotations
- Add unit tests that verify the migrated code produces the same results
- The public interface must not change (other files import from this module)

Run the full test suite after migration.

Przekaż pełną treść promptu z powyższego Aside z poradą jako opis zadania (skrócony tutaj dla czytelności):

codex cloud exec --env migration-env --attempts 3 "Migrate src/services/legacy-payment-processor.js to TypeScript: flatten the nested callbacks to async/await, make the global config dependency an explicit constructor parameter, add comprehensive types, add tests, and keep the public interface stable."

Z trzema próbami Codex eksploruje różne podejścia do spłaszczania callbacków i restrukturyzacji klas. Porównaj wyniki: jedna próba może zachować hierarchię klas z generykami TypeScript; inna może spłaszczyć do czystych funkcji; trzecia może użyć podejścia hybrydowego. Wybierz to, które jest najczystsze i najłatwiejsze w utrzymaniu.

Krok 5: Śledź postęp z automatyzacjami

Skonfiguruj cotygodniową automatyzację mierzącą postęp migracji i identyfikującą następną partię:

Wskazówka

Prompt automatyzacji do skopiowania — śledzenie migracji:

Weekly migration progress report:

1. Count .js and .ts files in each directory under src/
2. Compare to last week's counts in scripts/migration-progress.json
3. Calculate overall migration percentage (TS files / total files)
4. Identify the 5 directories with the most remaining .js files
5. For each remaining .js file, estimate migration difficulty (simple rename+types vs complex refactoring needed)

Report:
- Overall progress: X% complete (Y of Z files migrated)
- This week's progress: N files migrated
- Estimated remaining effort by directory
- Recommended next batch for migration

Update scripts/migration-progress.json with current counts.

Migracja komponentów React

Dla modernizacji specyficznej dla React (komponenty klasowe do funkcyjnych z hookami) wzorzec jest ten sam, ale prompty są specyficzne:

Wskazówka

Prompt do skopiowania — migracja z klas do hooków:

Migrate src/components/Dashboard.jsx from a class component to a functional component with hooks:

1. Convert the class to a function component
2. Replace this.state and this.setState with useState hooks
3. Replace componentDidMount, componentDidUpdate, componentWillUnmount with useEffect
4. Replace class methods with const functions or useCallback where appropriate
5. Add TypeScript types for props, state, and any callbacks
6. Rename from .jsx to .tsx

Preserve the exact same rendering behavior and prop interface.
Run the component tests after migration. The tests should pass without changes.
If a test references class-specific APIs (e.g., wrapper.instance()), update the test to use Testing Library patterns.

Kiedy to nie działa

Zmigrowany plik psuje niezmigrowany plik, który go importuje. Zmiana z module.exports na named exports może złamać konsumentów require(). Włącz esModuleInterop w tsconfig.json i powiedz Codex: “When converting exports, ensure backward compatibility with CommonJS consumers. If any .js file imports from this module, verify the import still works after migration.”

Błędy typów kaskadowo rozchodzą się po bazie kodu. Gdy dodajesz typy do funkcji narzędziowej, każdy jej wywołujący może teraz mieć błąd typów. Użyj allowJs: true i sprawdzaj typy tylko w plikach .ts na początku. W miarę migracji kolejnych plików pokrycie sprawdzania typów naturalnie się rozszerza.

Zadanie w chmurze migruje wobec złej bazy. Jeśli twoja gałąź z infrastrukturą migracji nie została scalona do domyślnej gałęzi środowiska chmurowego, zadania w chmurze nie zobaczą tsconfig.json ani pakietów typów. Zaktualizuj mapę repozytoriów środowiska chmurowego, aby używała gałęzi migracji, lub scal zmiany infrastrukturalne do main najpierw.

Migracja wprowadza subtelne zmiany zachowania. Konwersja callbacków na async/await może zmienić kolejność wykonywania. Konwersja komponentów klasowych na hooki może zmienić zachowanie re-renderów. Zawsze uwzględniaj “verify identical behavior” w swoim prompcie i uruchamiaj istniejący zestaw testów — nie polegaj tylko na nowych testach.

Co dalej

Refaktoryzacja na dużą skalę z worktree Zastosuj te wzorce równoległej migracji do refaktoryzacji architektonicznej

Zaplanowana automatyzacja zadań Automatyzuj bieżące śledzenie migracji i monitorowanie jakości kodu