migrate-to-shoehorn

migrate-to-shoehorn 技能概覽

migrate-to-shoehorn 技能是做什麼的

migrate-to-shoehorn 技能可以幫你把測試程式碼裡脆弱的 as 轉型，替換成 @total-typescript/shoehorn，讓你能更輕鬆建立部分測試資料，不必一直和 TypeScript 拉扯。當你的 fixture 過大、只在意少數巢狀欄位，或是在整理測試中 as unknown as Type 這類寫法時，這個技能特別適合。

誰適合使用它

如果你在撰寫 TypeScript 測試套件，並且想用更少樣板程式建立更安全的 fixture，就很適合用這個 migrate-to-shoehorn 技能。它尤其適合正在更新既有測試、撰寫新的整合型測試，或想把目前大量依賴 cast 的 mock 統一規範的工程師。

為什麼它有用

它的核心價值不只是語法替換，而是在降低測試設定摩擦的同時，仍然讓型別意圖保持清楚。這個技能會引導你在不完整物件上使用 fromPartial()，在測試刻意破壞型別形狀時使用 fromAny()；這樣一來，取捨是明確的，不會被藏在 cast 裡面。

如何使用 migrate-to-shoehorn 技能

安裝 migrate-to-shoehorn 技能

使用以下指令安裝：

npx skills add mattpocock/skills --skill migrate-to-shoehorn

安裝後，先閱讀 SKILL.md，再視你的環境查看任何有連結的 repository 檔案。對這個 repo 來說，技能內容集中在單一檔案中，所以實作範例旁邊就能看到最實際的操作指引。

把模糊目標轉成好的提示詞

最好的 migrate-to-shoehorn 用法，是先提供一段具體的測試程式片段，而不是一句模糊需求。好的輸入像是：「把這個測試從 as Request 改成 fromPartial()，並保留既有的 assertion 行為」，或者「把這些 as unknown as 的 fixture 改寫成 fromAny()，因為這個測試本來就刻意傳入無效資料」。

這個技能需要你提供什麼

請提供物件結構、測試框架脈絡，以及你想移除的確切 cast 模式。如果 fixture 巢狀很深，請指出真正重要的欄位，因為這個技能最有效的情況，是能只保留必要欄位，把其餘多餘的假結構拿掉。

實際工作流程與 repo 閱讀順序

先從 SKILL.md 確認遷移模式，再找出程式碼中在測試裡使用 as Type 或 as unknown as Type 的地方。套用 migrate-to-shoehorn 指引時，第一步要先判斷測試是要「有效的部分資料」還是「刻意無效的資料」；這個判斷會決定該用 fromPartial() 還是 fromAny() 來替換。

migrate-to-shoehorn 技能常見問答

migrate-to-shoehorn 只適用於測試嗎？

是。這個技能明確是給測試程式碼用的，不是給 production code 用的。如果你需要的是執行期驗證，或是 production safe 的型別轉換，那 migrate-to-shoehorn 就不是對的工具。

什麼時候該用 fromPartial()，什麼時候該用 fromAny()？

當物件是不完整的，但在結構上仍然和目標型別一致時，用 fromPartial()。當測試刻意提供無效或不可能出現的值，而且你需要在那個情境下繞過型別檢查時，用 fromAny()。

migrate-to-shoehorn 技能比一般提示詞更好嗎？

通常是，因為它提供的是明確的遷移模式，而不是寬泛建議。一般提示詞可能只會告訴你「避免 casts」，但 migrate-to-shoehorn 技能會直接指出該用哪個替代方案，以及大型 fixture 要怎麼處理，能減少你猜測怎麼改寫的時間。

這個技能適合初學者嗎？

如果你已經懂基本的 TypeScript 測試，就適合。主要學習門檻在於要分辨你的 fixture 是「部分但有效」，還是「刻意不安全」；因為這會決定要用哪個 helper。

如何改進 migrate-to-shoehorn 技能

給這個技能真正的測試意圖

最有力的 migrate-to-shoehorn 輸入，不只是物件字面值，而是這個測試到底要驗證什麼行為。像是「這個測試只在乎 body.id 和 headers.authorization」這種描述，會比「把這個 fixture 轉掉」更有用，因為技能可以把物件縮到真正有意義的最小形狀。

避開兩種常見失敗模式

第一種失敗，是保留了太多 fixture 雜訊，結果失去使用 migrate-to-shoehorn 的意義。第二種是到處都用 fromAny()，這會削弱型別訊號；應該優先選擇最符合測試意圖、範圍最窄的 helper。

第一次轉換後再迭代

完成第一輪 migrate-to-shoehorn 轉換後，檢查測試是否仍然清楚表達契約。如果輸出裡還有不必要的屬性，就移除它們；如果測試確實需要不安全的值，也要確認選擇 fromAny() 是刻意且能由情境本身說明的。

根據 repo 限制調整提示詞

如果你的 codebase 有特定測試慣例，請一開始就說明：例如 Jest 或 Vitest、factory helper、共用 request 物件，或是 import 的 lint 規則。這些背景資訊能幫助 migrate-to-shoehorn 技能產生更符合你 repo 的改動，而不只是把語法換掉。