provider-resources

provider-resources 技能總覽

provider-resources 是一個 Terraform Provider 開發技能，用來搭配 Terraform Plugin Framework 實作 resources 與 data sources。它特別適合後端工程師用來打造有 CRUD 支援的 provider endpoint、設計 schema 與 state，或加入 acceptance tests，而且比起通用提示詞，能少走很多冤枉路。

真正要解決的不是抽象地「寫 Terraform code」，而是幫你把 provider 功能整理成符合 HashiCorp 慣例、能正確對應遠端 API、而且在上線前就可測試的形式。也就是說，provider-resources skill 最有價值的情境，是你已經知道目標 API 長什麼樣、需要實作指引的時候；如果你還在猶豫 provider 應該暴露哪些內容，這個技能就不是最對焦的選擇。

provider-resources 涵蓋哪些內容

這個技能聚焦在 resource 與 data source 的實作模式、檔案佈局、schema 組織、state 處理，以及 acceptance-test 工作流程。對於 provider-resources for Backend Development 這類工作來說，它很適合拿來對接以後端 API 為準、而 Terraform 需要持續讓 state 與之對齊的情境。

什麼情況下最適合使用 provider-resources

當你需要協助處理 resource CRUD、importer 行為、computed 與 optional attributes、巢狀 schema 設計，或 provider repository 的 package 結構時，就該用 provider-resources。如果你想替一個新的 endpoint 建立一致的實作路徑，而不是從多個範例東拼西湊，這個技能也很有幫助。

安裝前先注意什麼

這個技能預設你是在做 Terraform provider，且會使用 Plugin Framework。如果你需要的是 modules、registry 發佈，或從零開始做 provider scaffolding，這就不是它的焦點。它也不能取代特定產品的 API 知識；你仍然需要知道 endpoint contract、錯誤模式，以及識別規則。

如何使用 provider-resources 技能

將 provider-resources 安裝到你的技能集合中

先依照 repo 的安裝流程把技能加進去，再在特定的 provider 任務脈絡中引用它：

npx skills add hashicorp/agent-skills --skill provider-resources

如果你的環境使用不同的 skill loader，也請保留相同的 skill 名稱，並指向 terraform/provider-development/skills/provider-resources 路徑。

先從正確的來源檔案開始

先讀 SKILL.md，再檢視定義實作形狀與慣例的章節。在這個 repository 裡，代表你應該先注意 overview 與檔案結構指引，再進到 code generation。如果你的本地副本還有額外的 provider templates 或相鄰 skills，請等你理解這個 skill 的 resource 工作流程之後再比較。

給這個技能完整的任務說明

provider-resources usage 在你提供遠端 object type、必要識別碼、CRUD 行為，以及任何特殊 state 規則時，效果最好。差的提示會說「幫我建一個 resource」。更好的提示則會說清楚：

• API object 與 endpoint
• 哪些欄位是 required、optional、computed，或 ForceNew
• 如何偵測 drift
• update 是怎麼套用的
• read 是否 eventual consistent
• acceptance tests 必須驗證什麼

這些資訊可以讓技能產出的 code 與建議真正貼合後端，而不是憑空假設。

採用以 repository 為核心的工作流程

要得到最佳結果，先請它提出一份把 resource 映射到既有 provider 佈局的計畫，接著一次實作一個部分：schema、create/read/update/delete、importer、tests。若 repository 裡已經有相似的 resources，請直接指出來，讓技能能沿用本地慣例，而不是套用泛用範例。

provider-resources 技能 FAQ

provider-resources 只適合新 resource 嗎？

不是。這個技能同樣適合重構、在既有 resource 旁新增 data source，或修正成熟 provider 裡的 state 與 test 問題。當 API 本身已經存在，而工作重點是如何在 Terraform 裡把它清楚表達出來時，它最強。

我需要先有 Plugin Framework 經驗嗎？

不一定需要。這個技能可以幫初學者抓到正確結構，但前提是你能清楚描述 API 與 provider 行為。如果你連 identity、lifecycle 或 update semantics 都說不清楚，最好先補齊這些資訊，否則第一次產出很可能不夠準。

這和一般提示詞有什麼不同？

一般提示詞常常會產生看起來合理的 provider code，卻缺少本地慣例與測試紀律。provider-resources 更有價值的地方，在於它會把方向推向 Terraform 原生的佈局、resource 與文件的配對，以及 acceptance-test 思維，這能明顯減少 review 時的返工。

什麼情況下不該用這個技能？

不要拿它來處理無關的後端 CRUD app、一般 Go 架構設計，或 Terraform module authoring。如果你的任務主要是 packaging、release automation，或 registry 文件，請改用專注於那些需求的技能。

如何改善 provider-resources 技能

提供 API 事實，而不只是功能名稱

要讓 provider-resources 的輸出更準，最快的方法是精確描述 object contract：ID、create inputs、read shape、可變欄位，以及 delete semantics。如果 API 有非典型行為，例如非同步建立、部分更新，或伺服器生成名稱，也要一開始就說明。這些細節會直接改變 provider 的設計。

指定你想沿用的本地模式

如果 repository 裡已經有很接近的對照範例，請直接指出確切的檔案或 resource。這能幫技能對齊既有 provider 慣例，而不是自己發明一套新風格。這一點對 schema 命名、test helpers，以及 state transitions 特別重要。

先要求最容易出錯的部分

最容易失敗的通常是 import/state 處理、computed fields，以及 acceptance tests。先請技能把這些部分處理好，再去修飾文件或 helper functions。如果第一次的答案已經接近但還不完整，可以把失敗的 test output 或 schema diff 一起貼上，讓下一輪精準修正不一致的地方。