refactor-module

refactor-module 技能概覽

refactor-module 的作用

refactor-module 技能可協助把單一龐大的 Terraform 設定，拆成可重複使用的 module，並讓輸入、輸出、封裝與遷移規劃更清楚。它是為重構工作設計的，不是用來從零做 module 設計；當你手上已經有實際在運作、而且成長到不再安全好維護的 Terraform 程式碼時，這項技能最有價值。

適合誰使用

如果你管理的 Terraform 難以重用、難以測試，或因為邏輯、資源與 state 管理全混在一起而變更風險很高，就適合使用 refactor-module 技能。對平台工程師、基礎架構維運者，以及需要一份實用 refactor-module guide 的審查者來說，它很適合用來把現有堆疊拆進 module 邊界，同時不丟失 state 脈絡。

它有什麼不同

這個 refactor-module 技能是以決策為導向：它預期你提供來源設定、module 名稱、目標抽象層級，以及 state 相容性計畫。這讓它比泛用的「把它模組化」提示更可操作，因為它會逼 agent 一起考慮介面、遷移與 registry 封裝，而不只是單純重新排列檔案。

如何使用 refactor-module 技能

安裝並指向正確的程式碼

在進行 refactor-module install 時，請使用網站上的 hashicorp/agent-skills 技能安裝流程，並將目標對準真正需要重構的 Terraform 設定。這個技能的設計核心是 source_directory、module_name、abstraction_level、preserve_state，以及可選的 target_registry；因此請一開始就把這些值提供完整，不要只丟一句模糊的清理需求。

先讀對的檔案

先看 SKILL.md 了解工作流程，再檢查任何定義慣例、負責人或發佈預期的 repository 脈絡。如果你的環境還有相鄰文件或 module 標準，請在執行技能前先讀過，這樣輸出才能符合你們 repo 的命名、版本控管與 state 遷移慣例。

把模糊需求改寫成可用提示

弱提示會說：「把這份 Terraform 拆成 modules。」更強的 refactor-module usage 提示會說：「重構 source_directory=./infra/prod，建立 module_name=vpc，使用 abstraction_level=intermediate，並為既有線上環境保留 state 相容性。」也要補上目前的痛點，例如資源重複、介面不清楚，或未來需要發佈到 registry，因為這些會影響重構應該做得多激進。

採用能減少返工的工作流程

先請它分析目前設定，再請它提出 module 邊界、variables、outputs 與遷移步驟。若第一次產出的範圍太大，就把焦點縮小，一次只處理一個子系統，例如 networking 或 IAM，這樣 module 設計才更容易測試，state 轉換計畫也才更站得住腳。

refactor-module 技能 FAQ

refactor-module 只適合既有 Terraform 程式碼嗎？

是的，refactor-module 技能主要是給需要拆解成可維護 modules 的既有設定使用。如果你是從零開始，普通的設計提示可能就夠了；但當你已經有資源、相依關係與 state 需要保留時，這項技能會更適合。

使用 refactor-module 前應該提供什麼？

至少要提供來源目錄、module 名稱，以及是否必須保留 state 相容性。如果你有 registry 目標、命名標準，或對抽象層級有任何限制，也一併提供；這些細節能幫助 refactor-module skill 避免產出一個在你的環境裡很難落地的設計。

什麼情況下不該用 refactor-module？

如果你只需要小幅整理、名稱修正，或只是做一個一次性的 Terraform 範例，就不適合使用它。若你也無法提供足夠的現況資訊，例如目前資源或 state 的細節，它同樣不是好選擇，因為 module 重構非常依賴對相依關係與遷移限制的理解。

如何改進 refactor-module 技能

給技能更明確的限制

最好的 refactor-module 結果，來自清楚界定邊界：哪些內容應該放進 module、哪些必須留在 root configuration、以及哪些不能因為 production state 而改動。若你不先講清楚，模型可能會把資源抽象化過頭，或提出一條技術上漂亮、但營運成本很高的遷移路徑。

提供目前的痛點，而不只是理想結果

要告訴技能為什麼要重構：是有重複的堆疊、經常 drift、變更太慢，還是計畫要內部發佈。這能幫助 refactor-module skill 在重用性與簡潔性之間抓到正確取捨，而這通常正是 Terraform module 工作裡最難做的決定。

檢查輸出是否兼顧介面品質與遷移可行性

先檢視 variables、outputs、命名與依賴流向，再確認 state 遷移計畫是否符合你實際的部署方式。若第一次答案太泛，請透過要求更窄的抽象層級，或更保守的 state 保留方式來迭代；這些調整通常比單純要求「更詳細」更能改善最後的 refactor-module guide。