extract

extract 技能總覽

extract 會做什麼

extract 技能可協助你把重複出現的 UI 程式碼整理成可重用的 Design System 資產。實務上，它會找出重複元件、硬編碼的設計值，以及不一致的實作模式，接著提出或建立可共用的元件與 tokens。

extract 適合誰

這個 extract 技能最適合已經出現一定程度重複程式碼、並想用更系統化方式整併的產品 UI、元件庫或 Design Systems 團隊。對前端工程師、Design System 維護者，以及使用 AI 輔助重構的工作流程尤其有幫助。

真正要解決的工作

多數使用者要的不是泛泛的重構，而是想回答這類問題：「哪些東西應該抽成共用元件？」「哪些值應該變成 tokens？」「要怎麼遷移才不會把 app 弄壞？」extract 技能是圍繞這條決策路徑設計的，不只是單純清理程式碼。

extract 技能的差異在哪裡

和只會說「把這段做成可重用」的一般 prompt 不同，extract 是從盤點開始：先找出目前的 design system、檢查命名與 token 慣例、辨識重複模式、評估到底值不值得抽，再規劃遷移方式。相較於臨時性的元件生成，它更適合 Design Systems 工作。

什麼情況下 extract 特別適合

當你需要以下工作時，可以使用 extract：

• 把重複的 UI 模式整併成共用元件
• 找出像是顏色、間距、字體等 token 候選值
• 統一同一概念下實作不一致的不同變體
• 在既有 design system 上補強，而不是從零發明一套新的
• 在大幅修改多個檔案之前，先規劃抽取策略

安裝前要先知道的重要邊界

extract 最大的導入限制在於：它預設你的專案裡可能已經有一套 design system 或共用 UI 結構可以延伸。如果完全沒有，這個技能會明確要求你先釐清應該在哪裡、用什麼方式建立，再繼續往下做。如果你的需求是從零開始做 greenfield 的 design-system 架構，這個技能只能算是部分適配。

如何使用 extract 技能

安裝 extract 技能

可用以下指令從 repository 安裝此技能：

npx skills add pbakaus/impeccable --skill extract

安裝後，當你的任務是抽出可重用的 UI 模式或 tokens，而不是單次使用的畫面實作時，就可以呼叫它。

呼叫 extract 前，先準備理想輸入

extract 技能在你提供以下資訊時效果最好：

• 目標區域、功能資料夾，或一組疑似重複的檔案
• 目前 design system 或共用 UI library 的位置
• 使用中的 framework 與 styling stack
• 你想解決的具體重用問題
• 任何遷移限制，例如「不要重新命名 public exports」

像「幫我整理一下」這種模糊請求，會留下太多猜測空間。更好的做法是直接點出重複模式，以及預計要收斂到哪個系統。

把粗略需求變成高品質的 extract prompt

弱的 prompt：

• 「Refactor these components.」

較好的 extract 用法：

• 「Use the extract skill on src/features/billing and src/features/settings to find repeated form-row and card patterns. Our shared components live in src/ui. We use React, TypeScript, and CSS modules. Prefer extracting tokens for spacing and colors only if they appear in 3+ places. Propose a migration plan before editing.」

這類 prompt 能讓技能取得足夠資訊去盤點、評估價值，並避免過度抽象化。

extract 一開始需要先檢查什麼

一開始請先把技能指向以下位置：

• 疑似有重複 UI 的區域
• 共用元件目錄
• 任何 token 或 theme 檔案
• 既有文件或 stories（如果有）

原始技能特別強調要先找到 design system。這點很重要，因為抽取品質取決於能否對齊既有的命名、結構、import 慣例與文件模式。

給 Design Systems 使用的 extract 建議流程

實務上，一個可行的 extract 流程通常會是：

1. 找出目前的 design system 或 shared UI 資料夾
2. 掃描目標區域中的重複元件與硬編碼值
3. 將相近模式分組，而不是看到視覺上相似就全部抽出
4. 判斷哪些應該成為 shared primitive、組合式元件或 token
5. 提出抽取計畫
6. 謹慎遷移使用端檔案

這個流程正是技能的核心價值：能降低過早抽象化的風險。

先讀 repository 裡哪些內容

這個技能本身相當輕量。請先讀 SKILL.md，並把它當成主要操作指南。最值得先看的關鍵段落是：

• Discover
• Plan Extraction
• Extract & Enrich
• Migrate

由於這個 skill 資料夾裡沒有額外的 helper scripts 或參考資源，真正的價值大多來自你是否依照正確的決策順序使用它。

extract 如何判斷某個東西值不值得重用

要不要安裝 extract，很大一部分取決於你是否認同它的基本傾向：不是所有東西都該抽出來。它最擅長的情境是模式已經出現多次、之後還可能 повтор、語意相對穩定，而且集中維護確實划算。如果你的 codebase 充滿一次性的行銷頁版型，這個技能的幫助就會比較有限。

你應該期待 extract 產出什麼

一次好的 extract 執行結果，通常會包含以下幾項中的某些內容：

• 找出的元件候選項
• token 候選項
• 為何值得整併的理由
• 建議的目標 API 或命名方案
• 遷移順序

如果輸出一開始就直接改程式，卻沒有先確認共用資產應該放在哪裡，通常代表你的 prompt 沒提供足夠上下文。

能提升 extract 使用效果的實務技巧

想讓結果更好，可以補上這些資訊：

• 指定重用門檻，例如「只有在出現 3+ 次時才抽」
• 指定標準的目標資料夾
• 說明是否要保留現有 public APIs
• 要求先出計畫再動手修改
• 如果 codebase 很混亂，把 token 抽取與元件抽取分開處理

這些細節都會實際影響抽取方案的品質。

extract 技能常見誤用

以下情況不建議用 extract：

• 沒有重複來源模式，卻要憑空發明全新元件
• 大範圍視覺改版
• 在沒有利害關係人指引下，從零建立完整 design-system 架構
• 只是一個小檔案的微幅清理，根本不需要共用抽象層

在這些情況下，一般的 implementation prompt 可能反而比 extract 更快。

extract 技能 FAQ

extract 比一般 prompt 更好嗎？

如果是 Design Systems 工作，通常是的。一般 prompt 很容易太快過度抽象，或忽略既有系統結構。當真正的任務是找出哪些東西應該集中管理，以及如何遷移進既有 UI 系統時，extract 會更合適。

extract 對新手友善嗎？

算中等。流程本身很清楚，但如果你無法辨識 design system 的位置、token 檔案或命名慣例，新手可能會卡住。如果你對前端架構還不熟，建議提供明確路徑，並要求技能在變更前先說明取捨。

我一定需要既有的 design system 嗎？

不一定，但 extract 很明確地預設專案裡「可能已經有一套」，並會要求你在建立新系統前先確認。如果你的 repo 沒有共用 UI layer，建議把 extract 主要用在盤點與規劃，而不是讓它自行做架構決策。

extract 最擅長處理哪些模式？

它最擅長處理重複元件、硬編碼的設計值、同一個 UI 概念下不一致的實作，以及可重用的組合模式。若是與可重用 UI 結構無關的 business logic 重構，它的說服力就沒那麼強。

什麼時候不該用 extract？

當重複程式碼只是表面相似、重用反而會產生更差的 API，或這個模式還不夠穩定、不適合集中管理時，就應該跳過 extract。抽取本身會增加維護成本，所以它最有價值的情境，是那些重用價值能長期成立的地方。

extract 只適合用在元件嗎？

不是。原始指引明確包含 design tokens 與可重用模式，不只限於元件而已。這也是為什麼用在 Design Systems 時，extract 會比只會找 JSX 重複的一般 prompt 更有價值。

如何改進 extract 技能的使用效果

給 extract 更完整的架構脈絡

想快速提升 extract 的輸出品質，最有效的方法是提供：

• component library 路徑
• token/theme 路徑
• framework 與 styling stack
• 需要保留的命名慣例
• 遷移限制

沒有這些脈絡，技能仍然可以找出重複，但很難把結果自然地安放進你的系統。

先要求盤點，再要求實作

如果你想要更高品質的輸出，可以明確要求模型分兩階段使用 extract：

1. discovery and recommendation
2. implementation after approval

這能降低最常見的失敗模式：太早抽取，結果抽到錯的抽象層。

明確設定重用門檻

最有效的改善方式之一，就是加上這類規則：

• 「Only extract patterns used in 3 or more places」
• 「Only create tokens for values repeated across features」
• 「Do not centralize one-off layout wrappers」

這能讓 extract 維持在「好維護」的方向，而不只是機械式追求 DRY。

把元件抽取與 token 抽取分開

這兩者相關，但不是同一件事。如果你在混亂的 codebase 裡一次要求 extract 同時處理兩者，結果很容易混在一起。更好的 prompt 會拆開：

• 先辨識共用元件
• 再辨識 token 候選項
• 最後規劃遷移

這通常會帶來更乾淨的輸出，也能減少來回修改。

留意 API 被過度泛化

extract 常見的失敗模式之一，是為了硬要統一幾個「差不多」的實作，結果做出 props 過多的共用元件。如果提議中的 API 看起來比原本重複的程式碼還複雜，請要求技能縮小範圍，或把變體維持分開。

第一輪之後，進一步改善遷移品質

在第一輪輸出後，你可以追問這些問題：

• 「Which consumers should migrate first?」
• 「What breaks if we replace the old implementations?」
• 「Which props or styles should stay local?」
• 「Can you propose a compatibility layer?」

這時候，extract 就不只是幫你找模式，還能進一步協助你降低導入風險。

讓 extract 針對具體目標資料夾工作

不要只說「scan the app」，而是改成：

• 「Use extract on src/features/checkout against src/components」
• 「Review apps/web/src/account for token extraction into packages/ui/tokens」

具體範圍能提高訊號品質、控制分析成本，也會讓最後的 extract 計畫更可執行。

驗證抽取是否真的有幫助

任何 extract 工作流程中，最好的一項改進，就是要求技能為每個建議的抽象層提出理由：

• 它消除了哪些重複
• 它出現了多頻繁
• 為什麼這個共用 API 是穩定的
• 為什麼保留在 local code 會更差

這個簡單檢查，可以有效過濾掉那些看似聰明、實際價值卻不高的抽取。