provider-resources

provider-resources 概览

provider-resources 是一个用于 Terraform Provider 开发的 skill，专门帮助你基于 Terraform Plugin Framework 实现 resources 和 data sources。它特别适合后端工程师：在要构建带 CRUD 的 provider 端点、设计 schema 和 state，或者补充 acceptance tests 时，能比通用提示更少走弯路。

它真正要解决的，并不是抽象意义上的“写 Terraform 代码”，而是帮你把 provider 功能组织成符合 HashiCorp 约定、能干净映射到远程 API、并且在上线前可测试的形态。也因此，provider-resources skill 最适合你已经知道目标 API 长什么样、需要实现层面的指导时使用，而不是在你还在决定 provider 应该暴露什么能力的时候使用。

provider-resources 覆盖什么

这个 skill 重点覆盖 resource 和 data source 的实现模式、文件布局、schema 组织、state 处理，以及 acceptance-test 工作流。对于 provider-resources for Backend Development 这类场景尤其合适：后端 API 是事实来源，Terraform 需要保持 state 与之同步。

什么时候这个 skill 最适合

当你需要处理 resource CRUD、importer 行为、computed 和 optional 属性、嵌套 schema 设计，或者 provider 仓库里的包结构时，用 provider-resources 最合适。它也适合在新增端点时，希望沿着一条一致的实现路径推进，而不是从多个示例里东拼西凑。

安装前先注意什么

这个 skill 默认你正在做 Terraform provider 工作，并且使用 Plugin Framework。如果你需要的是 modules、registry 发布，或者从零搭建 provider 骨架，那它的关注层级就不对。它也不会替你补齐产品/API 领域知识；你仍然需要清楚端点契约、错误模式和标识规则。

如何使用 provider-resources skill

将 provider-resources 安装到你的 skill 集合中

按仓库提供的安装流程添加这个 skill，然后在具体的 provider 任务上下文里引用它：

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

如果你的环境使用的是不同的 skill loader，也保持同样的 skill 名称，并指向 terraform/provider-development/skills/provider-resources 路径。

先从正确的源文件看起

先读 SKILL.md，再查看定义实现形态和约定的部分。在这个仓库里，这意味着在开始代码生成前，先关注概览和文件结构指引。如果你的本地副本里还有额外的 provider 模板或相邻 skills，最好等你真正理解这个 skill 的 resource 工作流之后，再去对比它们。

给 skill 一份完整的任务说明

provider-resources usage 的效果最好，是在你明确提供远程对象类型、必需标识符、CRUD 行为，以及任何特殊 state 规则的时候。一个弱提示只会说“做一个 resource”。更强的提示应该说明：

• API 对象和端点
• 哪些字段是 required、optional、computed 或 ForceNew
• 如何检测 drift
• update 是如何应用的
• read 是否最终一致
• acceptance tests 必须验证什么

这些信息能让 skill 输出真正贴合后端的代码和建议，而不是凭空假设。

采用 repository-first 的工作方式

为了获得最佳结果，先让它给出一份计划，把这个 resource 映射到现有 provider 布局中，然后再一块一块实现：schema、create/read/update/delete、importer 和 tests。如果仓库里已经有相似 resources，明确指出来，这样 skill 就能复用本地模式，而不是套用泛化示例。

provider-resources skill 常见问题

provider-resources 只适合新资源吗？

不是。这个 skill 同样适合重构、在现有 resource 旁边新增 data source，或者修复成熟 provider 中的 state 和测试问题。只要 API 已经存在，工作重点是把它清晰地表达成 Terraform，这个 skill 就很有价值。

我必须先有 Plugin Framework 经验吗？

不一定。这个 skill 可以帮助初学者沿着正确结构推进，但前提是你能清楚描述 API 和 provider 行为。如果你还说不清 identity、lifecycle 或 update semantics，最好先补齐这些信息，否则第一版结果往往会比较粗糙。

它和普通提示有什么不同？

普通提示通常会生成看起来“差不多”的 provider 代码，但缺少本地约定和测试纪律。provider-resources 更有用，是因为它会推动你采用 Terraform 原生的目录布局、resource/documentation 配对，以及 acceptance-test 思维，从而减少评审阶段的返工。

什么时候不该用这个 skill？

不要把它用在无关的后端 CRUD 应用、通用 Go 架构设计，或者 Terraform module 编写上。如果你的任务主要是打包、发布自动化，或者 registry 文档，那就应该选更聚焦这些主题的 skill。

如何改进 provider-resources skill

提供 API 事实，而不只是功能名称

想最快提升 provider-resources 的输出质量，关键是把对象契约说清楚：ID、create 输入、read 返回结构、可变字段，以及 delete 语义。如果 API 有异步创建、部分更新、服务端生成名称之类的特性，也要尽早说明。这些细节会直接改变 provider 的设计。

指向你希望它复用的本地模式

如果仓库里已经有一个很接近的类比，直接说出准确的文件或 resource 名称。这样 skill 才能对齐现有 provider 约定，而不是另起一套风格。尤其是在 schema 命名、测试 helper 和 state transition 方面，这一点最重要。

先要求最容易出错的部分

最容易失败的通常是 import/state 处理、computed 字段和 acceptance tests。先让 skill 解决这些问题，再去润色文档或 helper functions。如果第一版已经接近但还不完整，就结合失败的测试输出，或者贴一份 schema diff，让下一轮精确修正不匹配的地方。