Migrate

Migration Assistant | 遷移助手

Guide systematic code migration, framework upgrades, and technology modernization.

引導系統性程式碼遷移、框架升級與技術現代化。

Usage | 使用方式

Migration Types | 遷移類型

Risk Assessment Matrix | 風險評估矩陣

Workflow | 工作流程

1. ASSESS - Evaluate current state, identify breaking changes
2. PLAN - Create migration checklist with dependencies
3. PREPARE - Set up codemods, compatibility layers, feature flags
4. MIGRATE - Execute migration in phases with tests
5. VERIFY - Run full test suite, check for regressions
6. CLEANUP - Remove compatibility shims, old dependencies

1. 評估 - 評估現狀、識別破壞性變更
2. 規劃 - 建立含依賴關係的遷移清單
3. 準備 - 設定 codemods、相容層、功能旗標
4. 遷移 - 分階段執行遷移並測試
5. 驗證 - 執行完整測試套件、檢查回歸
6. 清理 - 移除相容層、舊依賴

API Migration Contract Tests | API 遷移合約測試

When migrating an API endpoint from one tech stack to another (PHP → .NET, Express → Spring, Python → Go), unit tests on the new implementation verify against the new DTO — they cannot catch fields that the legacy returned but the new implementation forgot. Missing fields, renamed fields, type drift, and top-level vs nested placement drift will silently survive into production and break the existing frontend that still expects the legacy shape.

This is NOT caught by unit tests, integration tests, or code review alone. A real 2026-05-24 production incident shipped with 67/67 green tests and was discovered by the customer.

當 API endpoint 從一個技術棧遷至另一個（PHP → .NET、Express → Spring 等），對新實作的單元測試只驗證新 DTO——無法捕捉「舊版有但新版漏掉」「欄位 rename」「型別漂移」「頂層 vs nested 層級漂移」等問題。這些缺陷會靜默流入生產，導致前端（仍預期舊版回應 shape）失靈。

僅靠單元測試、整合測試或 code review 無法防止。2026-05-24 真實 PROD 事故：67/67 測試全綠流入正式環境，由客戶發現缺漏。

Mandatory rule | 強制規則

Every migrated API endpoint MUST ship with at least one contract test that compares the new implementation's response against a fixture captured from the legacy implementation. Structural equivalence (keys, types, placement), not value equality, is verified.

每個被遷移的 API endpoint 必須至少有一份 contract test，比對新實作的 response 與從 legacy 捕獲的 fixture。驗證的是結構性等價（keys、type、層級位置），而非值等價。

Fixture capture protocol | Fixture 捕獲協議

While legacy is still running (typical migration window) | Legacy 仍運行（典型遷移窗口）:

# 1. Capture ≥3 representative inputs (happy path, edge case, empty result)
curl -X POST $LEGACY_BASE/endpoint -d @input1.json \
  > tests/fixtures/migration/endpoint/scenario1.json
curl -X POST $LEGACY_BASE/endpoint -d @input2_empty.json \
  > tests/fixtures/migration/endpoint/scenario2_empty.json
curl -X POST $LEGACY_BASE/endpoint -d @input3_edge.json \
  > tests/fixtures/migration/endpoint/scenario3_edge.json

# 2. Scrub PII and volatile values (timestamps, generated IDs)
jq 'walk(if type == "string" and test("@") then "redacted@example.com" else . end)' \
  tests/fixtures/migration/endpoint/scenario1.json > tmp && mv tmp ...

# 3. Commit fixtures
git add tests/fixtures/migration/endpoint/

When legacy is already retired but source-readable | Legacy 已退役但 source 可讀:

• Trace through legacy source code, manually construct the expected response shape
• Document each field's origin (SQL column, computed expression, hardcoded) in a sibling .notes.md file
• 從 legacy source code 推導預期 response shape；每個欄位來源（SQL 欄位 / 計算式 / hardcoded）記錄於同位置 .notes.md

Contract test template

C# / xUnit:

[Theory]
[InlineData("scenario1")]
[InlineData("scenario2_empty")]
[InlineData("scenario3_edge")]
public async Task Endpoint_ResponseShape_MatchesLegacyFixture(string scenario)
{
    var fixture = LoadFixture($"migration/endpoint/{scenario}");
    var response = await CallNewImpl(fixture.Input);
    // StructuralEquivalence checks keys + types + placement, ignores values
    StructuralEquivalence.Assert(response, fixture.ExpectedShape);
}

TypeScript / Jest:

import { structuralEquivalence } from "./test-utils/structural-equivalence";

describe.each([
  ["scenario1"],
  ["scenario2_empty"],
  ["scenario3_edge"],
])("Endpoint response shape vs legacy fixture (%s)", (scenario) => {
  test("matches", async () => {
    const fixture = loadFixture(`migration/endpoint/${scenario}.json`);
    const response = await callNewImpl(fixture.input);
    structuralEquivalence(response, fixture.expectedShape);
  });
});

structuralEquivalence / StructuralEquivalence.Assert rule: same set of keys at each level (no missing, no extra unless explicitly opted in), same primitive type per key, same placement (top-level vs nested). Values can differ (timestamps, IDs); types and structure cannot.

Field-by-field migration audit checklist

Before merging any migrated endpoint:

• All legacy response fields mapped to new DTO (no silent drops)
• Naming preserved where possible (avoid TotalX rename that drops the "per-member" semantic)
• Top-level vs nested placement preserved
• Type compatibility verified (string→int conversions explicit, not coincidental)
• Error path return codes match legacy (509 not 506; 404 not 400)
• Contract test fixture committed under tests/fixtures/migration/
• Cross-link to contract-test-assistant for ongoing consumer-side verification

合併前必確認：

• 所有 legacy response 欄位 mapping 至新 DTO（無 silent drop）
• 命名儘量保留
• 頂層 vs nested 層級保留
• 型別相容性已明確驗證
• Error path return code 與 legacy 一致
• Contract test fixture 已 commit
• Cross-link 至 contract-test-assistant 做持續消費端驗證

Post-Cutover Data Reconciliation | Cutover 後生產資料對帳

Implements: XSPEC-284 R2 (axis ③ persisted-data semantics) / closes UDS issue #134.

Contract tests (above) and behavior-snapshot catch interface divergence but are blind to persisted-data semantic divergence. Two blind spots both share:

1. You can only assert what you thought to enumerate. The rules that actually ship broken are the implicit, undocumented ones — especially the semantics of a persisted field (when is it non-zero? when is it overwritten?). Nobody writes a scenario for a rule they don't know exists.
2. Per-request parity ≠ data-at-rest parity. A field written by an asynchronous process (delivery-receipt sync, settlement job, status reconciler) against a live external provider is not a deterministic request you can replay. Its correctness only emerges in aggregate over real production volume, not in a single happy-path snapshot.

Contract test 與 behavior-snapshot只能捕捉介面分歧，對持久化資料語義分歧視而不見。兩者共有兩個盲區：(1) 你只能驗證你想得到要列舉的規則——真正出包的永遠是沒人寫下來的隱含規則（某欄位何時非零、何時被覆寫）；(2) per-request parity ≠ data-at-rest parity——由非同步程序（DR sync、結算批次、狀態對帳器）對 live 外部供應商寫入的欄位，不是可重放的確定性請求，其正確性只在真實生產量的聚合中浮現。

Failure fingerprint | 事故指紋（#134）

某企業 SMS 平台 PHP→.NET 重寫：每筆金額由非同步 DR sync 覆寫（record.Cost = gatewayDr.Cost）。legacy 對 carrier-failure 仍計費，rewrite 寫 gateway 回報的 0 → cutover 邊界兩側同一失敗狀態的金額分歧。所有既有 gate 全部漏接（response shape 相同 → contract test 過；無人 curated「失敗仍計費」場景；欄位由背景作業對 live gateway 寫入 → 不可重放）。最後靠 ops 跑生產 SUM(cost) GROUP BY status, day 跨邊界彙總才發現。單日抽樣甚至誤判「失敗不計費＝正常」——只有跨 cutover 邊界的多週聚合才揭露真相。

Mandatory rule | 強制規則

When a migration loads legacy data into the same store as new data, the old/new boundary is a free differential oracle. For each business-critical persisted field you MUST:

• Define aggregate reconciliation invariants comparing the distribution of legacy-origin vs new-origin rows along key dimensions (e.g. SUM(money) / COUNT(*) GROUP BY status, period).
• Run them on a schedule against production and alert when divergence exceeds a declared tolerance.
• Investigate over a multi-week window spanning the cutover — never a single-day sample (a sampled check can confirm a wrong conclusion).

當 migration 將 legacy 資料載入與 new 相同的儲存，新舊邊界即是免費差分神諭。對每個 business-critical 持久化欄位必須：定義聚合對帳不變量（比對 legacy-origin vs new-origin 列沿關鍵維度的分佈）、對生產排程執行並於分歧超過宣告容差時告警、以跨 cutover 的多週窗口調查（切忌單日抽樣，抽樣可能坐實錯誤結論）。

Cutover-boundary reconciliation SQL template | 對帳 SQL 模板

-- Reconcile a money/state field across the migration cutover boundary.
SELECT status,
       SUM(CASE WHEN created < @cutover THEN 1 ELSE 0 END)                          AS legacy_rows,
       SUM(CASE WHEN created < @cutover AND money_field > 0 THEN 1 ELSE 0 END)      AS legacy_nonzero,
       SUM(CASE WHEN created >= @cutover THEN 1 ELSE 0 END)                         AS new_rows,
       SUM(CASE WHEN created >= @cutover AND money_field > 0 THEN 1 ELSE 0 END)     AS new_nonzero
FROM records GROUP BY status;
-- Invariant: nonzero-ratio per status must not differ across the boundary beyond tolerance.

Tolerance & alerting guidance | 容差與告警指引

Gate 0 — Implicit-rule capture for persisted business fields | 隱含規則擷取

Before migrating any feature that writes a persisted business field, explicitly answer for each such field three questions, then lock the answer as a snapshot scenario or a reconciliation invariant:

1. When is this value SET? 何時設值？
2. When is it OVERWRITTEN? 何時被覆寫？（尤其非同步路徑）
3. When is it ZEROED / nulled? 何時歸零／清空？

High-risk implicit-rule checklist — empirically recurring fingerprints | 高風險隱含規則檢查清單（經驗反覆出現的指紋）：

• Billing / charge semantics — charged on submit vs on delivery; refund-on-failure? | 計費語義（提交時計費 vs 送達時計費；失敗退費？）
• Enum / status-code mapping — every legacy code mapped; "success set" defined identically | 列舉／狀態碼對映（每個 legacy 碼都對映；「成功集合」定義一致）
• Null / empty handling — empty string vs null vs absent; default-on-missing | 空值處理（空字串 vs null vs 不存在；缺值預設）
• Field-name casing / serialization — snake_case vs camelCase binding | 欄位命名大小寫／序列化（snake_case vs camelCase 綁定）
• Timezone — stored UTC vs local; report boundaries | 時區（存 UTC vs local；報表邊界）
• Rounding / type coercion — "2.00" (text) parsed as int → dropped to 0 | 四捨五入／型別強轉（"2.00" 文字被當 int 解析 → 掉成 0）

3-gate positioning | 3-gate 定位表

Make the boundary between gates explicit so each axis has an owner and nothing falls into the seam:

Cross-ref: behavior-snapshot (curated golden masters), observability-assistant (reconciliation schedule + alert templates).

Background Job / Side-Effect Completeness | 背景作業／副作用完整性

Implements: XSPEC-284 R3 (axis ⑤).

Migration inventories (/vo-inventory, XSPEC-200 type:background_job) and Devil's-Advocate grep (XSPEC-201 Step 4) annotate cron / queue consumers / scheduled batches / webhooks / mail-send points — but annotation alone proves nothing. A background job can be listed in the manifest, exist in code, and still never actually run in the new system.

遷移清單與副作用 grep 只是標注背景作業——標注本身不證明任何事。背景作業可能在 manifest 列出、程式碼存在，卻在新系統從未真正執行。

Mandatory rule | 強制規則

For every background side-effect carried over from legacy, verify two things — annotation is not enough:

If either check fails, mark the feature not_implemented (XSPEC-199) and block UAT / cutover — do not treat a silent, never-fired job as "done".

對每條由 legacy 帶過來的背景副作用，須驗證兩件事（標注不夠）：(a) 存在——cron／queue consumer／webhook／寄信點在新系統實際實作（source grep + 註冊檢查）；(b) 已執行——post-cutover 已被觸發／執行至少一次且有可觀測證據（log、heartbeat、queue depth 排空、telemetry counter）。任一不過即標 not_implemented（XSPEC-199）並 block UAT／cutover——絕不把沉默、從未觸發的作業當「完成」。

Cross-ref: structured-log mandatory events heartbeat / business_event (logging-standards) provide the observable execution evidence for check (b).

State-Machine & Temporal Parity | 狀態機與時序對等

Implements: XSPEC-284 R8 (axis ⑧) → split out as XSPEC-287.

Legacy state-transition rules and temporal preconditions are implicit: a single-record snapshot "looks legal", and a violation only surfaces across a sequence of operations. So per-request functional parity and behavior-snapshot parity both miss them (same blind-spot class as "per-request ≠ data-at-rest" / "per-request ≠ concurrency"). feature-manifest has only a status field — it does not validate transition legality.

legacy 的狀態轉移規則與時序前提多為隱性：單筆記錄的快照「看起來合法」，違規只在一連串操作的轉移序列中浮現，因此 per-request 功能對等與 behavior-snapshot 對等都抓不到（與「per-request ≠ data-at-rest」「per-request ≠ 並發」同源盲區）。feature-manifest 只有 status 欄，不驗證轉移合法性。

Step 1 — State-machine list source (derive, R3) | 狀態機清單來源

Legacy transitions are scattered across controllers / services / DB triggers. Derive the state enumeration + legal-transition set mechanically via three-way cross-reference (do not rely on memory):

legacy 狀態轉移散落於 controller／service／DB trigger。以三方交叉機械化擷取狀態列舉 + 合法轉移集（不靠人腦回憶）：

Authority on conflict: when the three disagree, treat production-observed transitions as the legacy ground truth (echoes #134 "production is the oracle"). A transition the code allows but production never produced is a latent path; a production transition the new enum forbids is a regression.

權威性：三者不一致時，以生產實際出現過的轉移為 legacy 真實行為基準（呼應 #134「以生產為準」）。程式碼允許但生產從未產生的轉移是潛在路徑；生產出現過但新 enum 禁止的轉移是回歸。

Step 2 — Legal-transition validation (oracle, R1) | 合法轉移驗證

From the derived transition graph, assert the new system forbids illegal transitions that legacy forbade. Block when the new system allows a transition legacy prohibited (a rewrite routinely loosens implicit guards):

依萃取出的轉移圖，斷言新系統禁止 legacy 禁止的非法轉移。當新系統允許 legacy 禁止的轉移即 block（重寫常放寬隱性護欄）：

• cancelled → pending (reviving a cancelled order)
• refunded → paid (un-refunding)
• shipped → draft (backward past a point-of-no-return)

Gate timing: pre-UAT.

Step 3 — Temporal invariant detection (oracle, R2) | 時序不變量偵測

Assert temporal invariants that a single-row snapshot cannot reveal; violation → alert:

斷言單筆快照無法揭露的時序不變量；違反即告警：

• created_at ≤ updated_at (no record updated before it existed)
• no future timestamps (clock skew / bad default)
• monotonic status-timestamp progression (paid_at ≤ shipped_at ≤ delivered_at)
• event-ordering guarantees preserved (no reordered event log)

Gate timing: pre-UAT and post-cutover (shares the reconciliation schedule of axis ③ Post-Cutover Data Reconciliation above).

Gate 時機：pre-UAT 與 post-cutover（與上方軸③ Post-Cutover 對帳共用排程）。

Step 4 — Sequence / ordering parity (R4) | 序列／順序對等

Verify the new system preserves idempotency (a repeated operation does not produce a duplicate state change) and critical event ordering, so the rewrite does not introduce order-sensitive bugs:

驗證新系統保留冪等性（重複操作不產生重複狀態變更）與關鍵事件順序，避免重寫引入順序敏感 bug：

• Replaying the same event/message twice yields one state change, not two
• Out-of-order delivery is rejected or reconciled, not silently applied
• Idempotency keys / dedup windows match legacy semantics

Boundary with XSPEC-286 axis ⑥ | 與 XSPEC-286 軸⑥ 邊界

287 (this section, axis ⑧) owns transition legality + temporal correctness (a domain question). XSPEC-286 axis ⑥ owns concurrency race / isolation (a performance/contention question). An overlap case — a concurrent operation causing an illegal transition — has its concurrency aspect in 286 and its transition-legality aspect here; assign the primary owner per the dominant failure mode at landing time.

287（本節，軸⑧）負責轉移合法性 + 時序正確性（領域問題）；XSPEC-286 軸⑥負責並發競態／隔離（效能/競爭問題）。重疊案例（並發導致非法轉移）的並發面歸 286、轉移合法性面歸本節；落地時依主導失敗模式指派主責。

Error-Path Completeness | 錯誤路徑完整性

Implements: XSPEC-284 R9 (axis ⑨) → split out as XSPEC-288.

The most common migration omission is "happy path migrated, error / degradation / fallback branches dropped in bulk". The happy path has an explicit requirement; error branches are scattered (try/catch layers, custom exception hierarchies, specific error codes) and silently lost. This skill owns the migration derive + degradation parity (R1/R3); the systematic missing-branch gap analysis + error-response differential (R2/R4) lives in full-coverage-testing "Migration Error-Path Completeness".

最常見的遷移遺漏是「happy path 移了、錯誤／降級／fallback 分支整批被漏」。happy path 有明確需求，錯誤分支散落（try/catch 階層、自訂例外階層、特定錯誤碼）而被靜默遺失。本 skill 負責遷移 derive + 降級對等（R1/R3）；系統性遺漏分支 gap 分析 + 錯誤回應差分（R2/R4）落在 full-coverage-testing「Migration Error-Path Completeness」。

Step 1 — Mechanized legacy exception / error-code list (derive, R1) | 機械化例外/錯誤碼清單

Enumerate the legacy error surface mechanically (not from recall): grep catch/except/rescue blocks, the custom exception/error class hierarchy, all error/status codes, and error response shapes (serializers/DTOs). This list is the error-path to-verify checklist handed to the gap analysis in full-coverage-testing.

機械化列舉 legacy 錯誤面（不靠回憶）：grep catch／except／rescue 區塊、自訂例外/錯誤類階層、所有錯誤/狀態碼、錯誤回應形狀（serializer／DTO）。此清單即交給 full-coverage-testing gap 分析的錯誤路徑待驗清單。

Step 2 — Degradation / fallback parity (R3) | 降級／Fallback 對等

legacy degradation modes only run on failure, so they are easy to drop. Verify the new system preserves them — fail closed on parity, not "consistent on happy path, wildly different on failure":

legacy 降級模式只在失敗時執行，容易被漏。驗證新系統保留——對等上 fail closed，而非「正常路徑一致、失敗時行為迥異」：

• External-service-failure fallback matches legacy | 外部服務失敗 fallback 與 legacy 一致
• Retry policy (count / backoff / give-up) matches legacy | 重試策略（次數／backoff／放棄）與 legacy 一致
• Partial-result handling matches legacy | 部分結果處理與 legacy 一致
• Circuit-breaker / timeout degradation matches legacy | 斷路器／逾時降級與 legacy 一致

Importance ranking: rank legacy error branches by production-actual trigger frequency (#134 "production is the oracle"). A high-frequency prod error branch with no new-system mapping is a hard block; never-fired latent branches are still listed but lower priority. 重要性分級：依生產實際觸發頻率排序（#134「以生產為準」）。高頻生產錯誤分支無對映即硬 block；從未觸發的潛在分支仍列入但較低優先。

Cross-ref: full-coverage-testing Migration Error-Path Completeness (gap report + error-response differential, R2/R4); behavior-snapshot (error-response parity).

Rollback Strategy | 回滾策略

Usage Examples | 使用範例

User: /migrate "Vue 2 to 3"
AI: Migration Assessment: Vue 2 → Vue 3
    Breaking changes found: 12
    - Options API → Composition API (47 components)
    - Filters removed (8 usages)
    - Event bus removed (3 usages)
    Risk: Medium-High
    Estimated effort: 2-3 weeks
    Recommended: Staged migration with @vue/compat

Next Steps Guidance | 下一步引導

After /migrate completes, the AI assistant should suggest:

遷移分析完成。建議下一步 / Migration analysis complete. Suggested next steps:

• 執行 /reverse 深入理解現有程式碼 — Understand current codebase
• 執行 /testing 確保遷移後測試通過 ⭐ Recommended / 推薦 — Verify post-migration tests
• 執行 /commit 提交遷移變更 — Commit migration changes

Appendix — 9-Axis Completeness Matrix | 附錄：9 軸完整性矩陣

Source: XSPEC-284 Legacy Refactor Completeness Framework. "Ensuring nothing is missing cannot be proven by enumeration" — you can only verify what you thought to enumerate. Strategy = two legs: (1) mechanically derive the to-do list from real legacy artifacts (schema / routes / cron config / prod logs), and (2) differential oracles (shadow run / replay / cutover-boundary reconciliation) that make divergence self-report.

「確保沒有遺漏」無法用列舉證明——你只能驗證你想得到要列舉的東西。策略＝兩條腿：(1) 從 legacy 真實 artifact 機械化推導待辦清單；(2) 差分神諭讓分歧自報。

Each migration declares, per axis, three things: derive (list source) · detect (oracle) · gate timing. Axes marked here as covered map to existing UDS standards — do not re-invent.

每軸宣告〔清單來源 derive｜oracle detect｜gate 時機〕；標為已覆蓋者對映既有 UDS 標準，勿重複造輪子。未宣告的軸視為已知遺漏風險。本框架 P0 落地＝軸③④⑤（本 skill）；軸⑥已拆 XSPEC-286（落地於 performance-standards）、軸⑧已落地於本 skill State-Machine & Temporal Parity（XSPEC-287）、軸⑨已落地（XSPEC-288）＝本 skill Error-Path Completeness（R1/R3 derive + 降級）+ full-coverage-testing（R2/R4 系統性 gap 分析 + 錯誤回應差分）。

Reference | 參考

• Core standard: refactoring-standards.md
• Related: contract-test-assistant — Strategy for ongoing contract verification post-migration
• Related: behavior-snapshot — Curated golden-master parity (3-gate axis ②)
• Related: observability-assistant — Reconciliation schedule + alert rules for post-cutover oracle
• Framework: XSPEC-284 Legacy Refactor Completeness Framework — 9-axis SSOT

Version History | 版本歷史

AI Agent Behavior | AI 代理行為

完整的 AI 行為定義請參閱對應的命令文件：/migrate

For complete AI agent behavior definition, see the corresponding command file: /migrate

License | 授權

CC BY 4.0