migrate-to-shoehorn

migrate-to-shoehorn skill 概覽

migrate-to-shoehorn skill 可協助你把 TypeScript 測試程式碼 中脆弱的 as 斷言，重構成使用 @total-typescript/shoehorn 的寫法。它特別適合那些測試裡已經充滿 as Type 或 as unknown as Type 的情境，尤其是當物件型別很大，導致測試資料準備又吵又誤導時，migrate-to-shoehorn skill 的價值會很明顯。

migrate-to-shoehorn 適合處理什麼問題

當你的真正需求不是「學一個新函式庫」，而是在不重寫整個測試套件的前提下，整理掉不安全的測試 fixture，就很適合使用 migrate-to-shoehorn。這個 skill 聚焦在一個很明確的重構任務：

• 用 fromPartial() 取代 as Type
• 用 fromAny() 取代 as unknown as Type
• 減少測試中大型輸入物件的假資料樣板程式碼

哪些人適合安裝這個 skill

如果你符合以下情況，這個 migrate-to-shoehorn skill 會很對路：

• 維護大量使用 casting 的 TypeScript 測試
• 想把部分 fixture 改得更安全
• 需要判斷哪一種斷言模式該對應哪個 shoehorn helper
• 想要 agent 幫你做有目標的重構，或給出具體遷移指引，而不是泛泛的 TypeScript 建議

採用前最重要的判斷點

最大的決策點在於範圍：這個 skill 明確是為了測試，不是 production code。這點很重要，因為 shoehorn 的價值在於：當你刻意用不完整、甚至不合法的資料來驅動測試案例時，仍然能比直接寫原始斷言得到更清楚、更有意識的型別表達。

為什麼用 migrate-to-shoehorn，而不是下通用重構提示

一般的 prompt 很可能只是機械式把 as 拿掉，卻忽略原本的測試意圖。migrate-to-shoehorn 更實用，因為它是依照開發者實際會遇到的遷移模式來設計的：

• 大型物件型別的部分測試輸入
• 負向測試中刻意放入的錯誤資料
• 刪掉那些與測試無關的假屬性

聚焦範圍越窄，通常就代表猜測越少，也比較不會做出不安全的替換。

如何使用 migrate-to-shoehorn skill

migrate-to-shoehorn skill 的安裝情境

如果你要在專案中使用底層函式庫，請安裝：

npm i @total-typescript/shoehorn

如果你是要把這個 skill 裝進支援 skills 的環境，就照你所在平台平常的 skill 安裝流程進行，之後在處理測試重構時呼叫 migrate-to-shoehorn 即可。

先讀這個檔案

先從 migrate-to-shoehorn 資料夾裡的 SKILL.md 開始看。在這個 repository 中，它是主要的權威來源，裡面整理了驅動這個 skill 的遷移模式。

建議閱讀順序：

1. migrate-to-shoehorn/SKILL.md
2. 你準備修改的測試檔案
3. 專案中實際使用到的 as Type 與 as unknown as Type

這個 skill 需要哪些輸入

如果你提供以下資訊，這個 skill 會發揮得最好：

• 目前的測試程式片段
• 被呼叫的目標函式或 component
• 相關型別名稱（如果已知）
• 測試資料預期是合法資料，還是刻意非法
• 你要的是一次性修正，還是一套可重複套用的遷移模式

少了這些脈絡，agent 仍然可以建議 fromPartial() 或 fromAny()，但很可能會選錯 helper。

可以直接要求的核心遷移模式

實務上的 migrate-to-shoehorn usage 很單純：

• as Type → 通常用 fromPartial()
• as unknown as Type → 通常用 fromAny()
• 假物件很大、但實際只在乎少數欄位 → 用 fromPartial()

這正是這個 skill 的核心價值：把模糊的「幫我整理這些測試 cast」需求，轉成一致、可判斷的重構方法。

怎麼寫出有效的 migrate-to-shoehorn prompt

弱的 prompt：

Replace as with shoehorn.

更強的 prompt：

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

這種寫法有把意圖、邊界與判斷規則都交代清楚。

範例：部分 fixture 的 migrate-to-shoehorn 遷移

Before:

getUser({ body: { id: "123" } } as Request);

After:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

當 fixture 在結構上不完整，但對這個測試來說概念上是合法資料時，就適合這樣改。

範例：刻意錯誤資料的遷移

Before:

getUser({ body: { id: 123 } } as unknown as Request);

After:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

當測試是刻意傳入非法資料，以驗證 validation 或 failure path 時，就應該這樣用。

大型重構時最穩妥的工作流程

如果你要做 repo 範圍的 migrate-to-shoehorn guide，不要一口氣盲目批次改完整個專案。比較安全的流程是：

1. 在測試檔中搜尋 as 與 as unknown as
2. 先把 casts 分類成 partial-valid 與 intentionally-invalid
3. 先遷移一個 test folder
4. 跑測試與 typecheck
5. 統一 import 風格與 helper 選擇
6. 再擴大到其餘測試套件

這樣可以避免把本來合理的負向測試 cast，和一般 fixture 清理混在一起處理。

能提升輸出品質的實務提示

請 agent 保留以下細節：

• 既有的測試名稱與 assertions
• 非法輸入測試的語意意圖
• 盡量維持最小 fixture 形狀，而不是展開成完整的假物件
• 若同時用到多個 helper，幫忙去重複 imports

另外也要明確說明，你是否希望這個 skill 優先產出能運作的最小 fixture。這通常會得到最乾淨的 shoehorn 重構結果。

哪些情況下 migrate-to-shoehorn 不適合

如果你的真正問題是 production type safety、domain modeling，或 API contract correctness，就不要把 migrate-to-shoehorn for Refactoring 拿來硬套。這個 skill 不是用來「全面修正型別」的；它是專注於測試重構的輔助工具。

migrate-to-shoehorn skill 常見問題

migrate-to-shoehorn 只能用在測試嗎？

是的。這是最重要的邊界。這個 skill 是圍繞測試的可讀性與測試意圖設計的，不是為了 production 的 typing 模式。

如果我的測試已經能通過，還需要 shoehorn 嗎？

不一定。當你目前的測試很難讀、充滿吵雜的假物件，或依賴會掩蓋意圖的不安全 cast 時，再安裝 migrate-to-shoehorn 會比較有價值。若你的測試 setup 本來就很乾淨，這次遷移未必划算。

fromPartial 和 fromAny 有什麼差別？

fromPartial() 適合不完整、但本質上合理的 fixture 資料。
fromAny() 適合刻意非法的資料，也就是測試需要繞過較嚴格 typing，去模擬執行期錯誤輸入的情境。

這個區分正是使用這個 skill，而不是下寬泛「移除 assertions」prompt 的主要理由之一。

migrate-to-shoehorn 對新手友善嗎？

算是友善，只要你已經理解基本的 TypeScript 測試。它的範圍很小，遷移規則也不難跟。新手最常見的風險反而是把 shoehorn 用到測試以外的地方。

我可以把這個 skill 用在整個 repository 的遷移嗎？

可以，但前提是你要按類別逐步檢查。大型遷移最常見的失敗模式，就是把所有 cast 都當成同一回事。實際上有些是部分 fixture，有些是刻意壞掉的 payload，也有些可能屬於 production code，不應該套用這種遷移模式。

這真的比一般 prompting 更好嗎？

通常是的，尤其當你的任務明確就是「把測試中的 assertions 遷移到 shoehorn」。一般 prompt 也許知道這個函式庫，但當你要的是把舊 cast 風格一致地對應到正確 helper 時，migrate-to-shoehorn usage 會更準確。

如何改善 migrate-to-shoehorn skill 的使用效果

給 agent 測試意圖，而不只是程式碼

提升 migrate-to-shoehorn 結果品質最快的方法，就是直接說明每個測試在檢查什麼：

• 以部分 setup 驗證 happy-path 行為
• 以刻意錯誤的輸入驗證 validation failure
• 只需要少數欄位的 edge case

這一小段脈絡，往往就足以決定該用 fromPartial() 還是 fromAny()。

一開始就標明哪些檔案只屬於測試

如果某個檔案混合了 helper code 與 production code，請明說。當你明確告訴 agent：

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

這個 skill 會安全很多。

這樣可以避免修改意外擴散到非測試路徑。

先要求列出 cast 清單，再動手改

面對很亂的測試套件時，可以先這樣下指令：

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

先審查、後改寫，能在真正重構前先抓出邊界案例。

型別推斷不清楚時，補上附近的型別資訊

如果光靠片段看不出預期型別，請把函式簽名或相關型別定義一起提供。型別脈絡越完整，import 選擇越準，也更不容易產生彆扭的改寫。

留意這些常見失敗模式

在 migrate-to-shoehorn install 與導入過程中，常見問題包括：

• 把 shoehorn 用到 production code
• 把刻意非法的資料錯改成 fromPartial()
• 把 fixture 物件越改越大，而不是越改越精簡
• 一邊「整理型別」一邊改壞測試原本的意義

這些通常不是函式庫本身的問題，而是 prompt 與 review 不夠精準。

對第一版輸出再做一次收斂

跑完第一輪之後，可以再要求第二次精修，例如：

• 把每個 fixture 縮到只保留測試真正需要的欄位
• 整理並合併 imports
• 解釋哪些剩下的 casts 應該保留
• 把合法的 partial data 與非法測試資料分開處理

這樣就能把一次性的基本遷移，進一步整理成更乾淨、可長期維護的測試模式。