legacy-code-translator · diff
v4.2.1 to v4.3.0
147 added, 71 removed. Audit A to A.
---
- name: legacy-code-translator
- description: "Methodological guide for the AI Agent to safely and systematically translate, refactor, and modernize giant legacy codebases (PHP, Python 2, old React) into modern stacks."
- author: "Roedy Rustam"
- version: "4.2.1"
- ---
-
- # Legacy Code Translator (Refactoring Engine)
-
- [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
-
- ---
-
- <a name="english"></a>
- ## English
-
- ### Orchestration & Integration
- Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `session-memory-manager` to ensure cohesive execution.
-
- ### Description
- A rigid methodology for the AI agent to reverse-engineer and translate legacy codebases into modern architectures without losing business logic. This gives the agent the "superpower" to handle massive enterprise migrations safely, avoiding the common hallucination trap of rewriting everything at once.
-
- ### Trigger Conditions
- Activate this skill when the user says:
- - "Migrate this old PHP codebase to Next.js."
- - "Translate this Python script to Rust."
- - "Refactor this giant React class component into hooks."
-
- ### Core Concepts
-
- #### 1. The 4-Step Migration Protocol
- The agent MUST follow this exact sequence:
- 1. **Understand (AST Map):** Map out the legacy code's inputs, outputs, and side effects. Document this in an artifact (`migration_plan.md`).
- 2. **Isolate Logic:** Separate the core business rules from the legacy framework bindings (e.g., separate the tax calculation logic from the WordPress hook).
- 3. **Translate:** Write the modernized code in the new language/framework.
- 4. **Verify (Shadow Testing):** Compare the output of the new code against the old code using identical inputs.
-
- #### 2. Agent Constraints
- - **NEVER overwrite the legacy file directly.** Always create the new file side-by-side (e.g., `User.legacy.php` and `user.service.ts`).
- - **NEVER attempt to translate a 2000-line file in one shot.** Break it down by functions or modules to prevent context window exhaustion and token truncation.
- - **Preserve quirks:** Sometimes legacy bugs are actually relied-upon business logic. Document suspicious logic before fixing it.
-
- ---
-
- ### Integration with Other Skills (MANDATORY)
- - `prd-architect` — To document the extracted business rules before writing modern code.
- - `session-memory-manager` — To understand how the legacy files intertwine before pulling them apart.
- - `autonomous-tdd-debugger` — To write tests against the old code, ensuring the new code passes the exact same tests.
-
- ### Referenced By Orchestrators (MANDATORY)
- - `brainstorming` — Add to "Architecture & Scale".
- - `zero-to-prod-orchestrator` — Phase 2 (Foundation / Refactoring).
-
- ---
-
- <a name="bahasa-indonesia"></a>
- ## Bahasa Indonesia
-
- ### Integrasi Orkestrasi
- Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `session-memory-manager` untuk memastikan eksekusi yang kohesif.
-
- ### Deskripsi
- Panduan metodologis ketat bagi Agen AI untuk membongkar, menerjemahkan, dan memodernisasi *codebase* warisan (legacy) berskala raksasa (seperti PHP 5 atau React lawas) ke arsitektur modern tanpa kehilangan atau merusak *business logic* yang ada.
-
- ### Kondisi Pemicu
- - Saat diminta memigrasikan sistem lama ke framework baru.
- - Saat harus menerjemahkan kode antar bahasa pemrograman (misal: Python ke Rust, atau PHP ke Go).
-
- ### Panduan Singkat
- - **Jangan Langsung Timpa:** Jangan pernah menulis ulang kode lama di file yang sama. Buat file baru bersisian (`old_logic.js` -> `new_logic.ts`), lalu perlahan pindahkan impornya.
- - **Pecah Skala Raksasa:** LLM akan berhalusinasi jika diminta menerjemahkan 2000 baris kode sekaligus. Pecah tugas tersebut menjadi level fungsi (function-by-function).
- - **Pemetaan Input/Output:** Sebelum menulis kode baru, agen wajib mendaftar semua *input* (argumen, variabel global, request DB) dan *output* (return, modifikasi state, update DB) dari fungsi lama ke dalam dokumen artefak.
+ name: legacy-code-translator
+ description: "Methodological guide for the AI Agent to safely and systematically translate, refactor, and modernize giant legacy codebases (PHP, Python 2, old React) into modern stacks."
+ author: "Roedy Rustam"
+ version: "4.3.0"
+ ---
+
+ # Legacy Code Translator (Strangler Fig & Refactoring Engine)
+
+ [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+ ---
+
+ <a name="english"></a>
+ ## English
+
+ ### Description
+ A systematic, risk-mitigated engineering methodology for migrating large, business-critical legacy codebases (PHP 5/7, Python 2, jQuery, old React Class Components, AngularJS) to modern 2026 enterprise stacks (Next.js 15, TypeScript 5.8+, Bun, Rust, Go) without business downtime or regression. Employs the Strangler Fig pattern, Shadow Execution Harnesses, and AST-driven module decomposition to prevent context exhaustion and hallucinated logic.
+
+ ### Trigger Conditions
+ - Large-scale framework migrations (e.g., PHP monolith -> Next.js + Bun/Hono microservices).
+ - Translating legacy scripts across languages (e.g., Python 2/3 CPU-bound routines -> Rust/Go).
+ - Refactoring sprawling React Class components (>1,000 lines) into modern hooks and Server Components.
+ - Decoupling legacy database queries from direct presentation templates.
+
+ ### The 4-Phase Strangler Migration Protocol
+
+ ```
+ ┌────────────────────────────────────────────────────────┐
+ │ 1. MAP & ISOLATE (AST Boundary Definition) │
+ │ Document I/O contracts in `migration_plan.md` │
+ └───────────────────────────┬────────────────────────────┘
+ │
+ ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 2. SHADOW HARNESS IMPLEMENTATION │
+ │ Run legacy and new code in parallel; log diffs │
+ └───────────────────────────┬────────────────────────────┘
+ │
+ ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 3. SIDE-BY-SIDE REFACTORING (Function-by-Function) │
+ │ Maintain old file while building typed modern clone │
+ └───────────────────────────┬────────────────────────────┘
+ │
+ ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 4. TRAFFIC CUTOVER & CLEANUP │
+ │ 100% parity verified ──► Deprecate legacy file │
+ └────────────────────────────────────────────────────────┘
+ ```
+
+ ### Shadow Testing Harness Example (TypeScript)
+
+ ```typescript
+ // src/migration/shadow-harness.ts
+ export interface ShadowComparison<T> {
+ legacyOutput: T;
+ modernOutput: T;
+ isMatch: boolean;
+ discrepancies?: string[];
+ }
+
+ export async function executeWithShadowTesting<TInput, TOutput>(
+ input: TInput,
+ legacyFn: (data: TInput) => Promise<TOutput>,
+ modernFn: (data: TInput) => Promise<TOutput>,
+ onDiscrepancy?: (diff: ShadowComparison<TOutput>) => void
+ ): Promise<TOutput> {
+ // 1. Run legacy function as ground truth for customer
+ const legacyPromise = legacyFn(input);
+
+ // 2. Execute modern implementation in shadow mode (non-blocking)
+ const modernPromise = modernFn(input).catch((err) => {
+ console.error('[Shadow-Harness] Modern function threw error:', err);
+ return null as unknown as TOutput;
+ });
+
+ const [legacyResult, modernResult] = await Promise.all([legacyPromise, modernPromise]);
+
+ // 3. Compare JSON representation for structural equality
+ const legacyJson = JSON.stringify(legacyResult);
+ const modernJson = JSON.stringify(modernResult);
+
+ if (legacyJson !== modernJson) {
+ const diffReport: ShadowComparison<TOutput> = {
+ legacyOutput: legacyResult,
+ modernOutput: modernResult,
+ isMatch: false,
+ };
+ if (onDiscrepancy) onDiscrepancy(diffReport);
+ console.warn('[Shadow-Harness] Discrepancy detected between legacy and modern outputs.');
+ }
+
+ // Always return the legacy result during the shadow probation phase
+ return legacyResult;
+ }
+ ```
+
+ ### The 4 Non-Negotiable Agent Constraints
+ 1. **Never Overwrite In-Place**: Never directly modify or delete the legacy source file during initial drafting. Always create the modernized file side-by-side (`order-calc.legacy.php` -> `order-calc.service.ts`).
+ 2. **Context Window Token Slicing**: Never attempt to translate a file exceeding 400 lines in a single turn. Decompose the module by distinct subroutines or AST nodes to prevent hallucinated truncations (`// ...rest of code`).
+ 3. **Preserve "Quirks as Features"**: Legacy edge cases (e.g., custom rounding rules or implicit type coercion) are often relied upon by downstream billing systems. Document and preserve them with explicit regression tests.
+ 4. **Enforce Type Contracts**: The modern code MUST be 100% strictly typed (no `any`, no phantom SDK imports).
+
+ ## Orchestration & Integration
+ - **`autonomous-tdd-debugger`**: Runs comparison tests against legacy fixtures to prove zero regression.
+ - **`prd-architect`**: Documents reverse-engineered business rules into `PRD.md` before coding.
+ - **`database-orm-expert`**: Bridges legacy SQL schemas with Prisma or Drizzle ORM models.
+ - **`anti-slop`**: Eliminates lazy mock returns and incomplete stubs during refactoring.
+
+ ---
+
+ <a name="bahasa-indonesia"></a>
+ ## Bahasa Indonesia
+
+ ### Deskripsi
+ Metodologi rekayasa sistematis dan aman bagi agen AI untuk memigrasikan basis kode warisan (*legacy codebase*) skala besar (PHP 5/7, Python 2, jQuery, React Class Component lawas) ke stack modern 2026 (Next.js 15, TypeScript 5.8+, Bun, Rust, Go) tanpa gangguan operasional (*zero downtime*) dan tanpa regresi logika bisnis. Menerapkan pola *Strangler Fig*, *Shadow Execution*, dan dekomposisi berbasis pohon sintaks (AST).
+
+ ### Kondisi Pemicu
+ - Migrasi skala besar (misal: monolit PHP lawas ke microservices Next.js + Bun/Hono).
+ - Penerjemahan kode antar bahasa (misal: skrip kalkulasi Python lambat ke modul Go/Rust berkecepatan tinggi).
+ - Pemecahan komponen React Class raksasa (>1.000 baris) menjadi Server Components dan hooks modular.
+ - Pemisahan kueri database yang menempel langsung pada file template HTML/PHP.
+
+ ### 4 Aturan Ketat Agen Selama Migrasi
+ 1. **Dilarang Menimpa File Asli Secara Langsung**: Jangan pernah langsung mengedit atau menghapus file lama pada langkah pertama. Buat file baru bersisian (`UserService.legacy.php` -> `user-service.ts`) agar kode lama tetap menjadi acuan kebenaran.
+ 2. **Pecah File Raksasa (Token Slicing)**: Jangan pernah meminta LLM menerjemahkan file di atas 400 baris dalam satu giliran. Pecah per fungsi atau blok logika untuk menghindari pemotongan kode (`// TODO: sisa kode`).
+ 3. **Hargai Perilaku Khusus (Quirks)**: Seringkali kejanggalan pada kode lama (misal: pembulatan desimal khusus) merupakan aturan bisnis yang disengaja. Jangan ubah aturan tersebut tanpa bukti pengujian (*regression test*).
+ 4. **Wajib Type-Safe**: Seluruh kode baru wajib menggunakan TypeScript mode ketat tanpa `any`.
+
+ ### Pola Pengujian Bayangan (Shadow Testing)
+
+ ```typescript
+ // Membandingkan output kode lama vs baru secara real-time
+ const total = await executeWithShadowTesting(
+ cartData,
+ (cart) => hitungTotalLegacyPHP(cart),
+ (cart) => hitungTotalModernTS(cart),
+ (diff) => catatKeLogMonitoring(diff)
+ );
+ ```
+
+ ## Integrasi Orkestrasi
+ - **`autonomous-tdd-debugger`**: Memvalidasi kesesuaian output antara fungsi lama dan fungsi baru.
+ - **`prd-architect`**: Mencatat aturan bisnis yang diekstraksi dari kode lama ke dalam dokumentasi formal.
+ - **`database-orm-expert`**: Memetakan kueri SQL lama ke skema ORM modern.
+ - **`anti-slop`**: Memastikan kode modern yang dihasilkan utuh, bersih, dan dapat langsung dieksekusi.