provider-resources

provider-resources の概要

provider-resources は、Terraform Plugin Framework を使って resources と data sources を実装するための Terraform Provider 開発スキルです。CRUD ベースの provider エンドポイントを実装するバックエンドエンジニア、schema や state の設計を進めたい人、あるいは汎用プロンプトよりも試行錯誤を減らしながら acceptance test を追加したい人に最適です。

本当に解くべき課題は、抽象的に「Terraform コードを書く」ことではありません。HashiCorp の規約に沿う形で provider の機能を組み立て、リモート API にきれいに対応させ、リリース前にテスト可能な状態にすることです。そのため、provider-resources skill が特に役立つのは、対象 API の形がすでに分かっていて実装の指針が欲しい場合であり、provider が何を公開すべきかをまだ検討している段階ではありません。

provider-resources で扱う範囲

このスキルは、resource と data source の実装パターン、ファイル配置、schema の整理、state の扱い、acceptance test の進め方に重点を置いています。バックエンド API が正となり、Terraform 側で state をそれにきちんと一致させる必要がある provider-resources for Backend Development の作業と特に相性が良いです。

このスキルが向いているケース

resource の CRUD、importer の挙動、computed 属性や optional 属性、ネストした schema 設計、あるいは provider リポジトリ内のパッケージ構成で迷っているなら、provider-resources を使う価値があります。複数の例を寄せ集めて手作業でパターンを組み立てる代わりに、新しい endpoint に対して一貫した実装方針を取りたいときにも有効です。

インストール前に確認したい点

このスキルは Terraform provider の実装と Plugin Framework を前提にしています。modules、registry への公開、あるいはゼロからの provider scaffold が目的なら、焦点が合っていません。また、製品固有の API 知識を置き換えるものでもありません。endpoint の契約、エラーの出方、識別子のルールは、別途必要です。

provider-resources skill の使い方

provider-resources を skill セットに追加する

リポジトリの install フローでこの skill を追加し、特定の provider 作業の文脈で参照します。

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

環境が別の skill loader を使う場合でも、skill 名は同じままにして terraform/provider-development/skills/provider-resources を指すようにしてください。

まずは適切なソースファイルから読む

最初に SKILL.md を読み、次に実装の形や規約を定めているセクションを確認します。このリポジトリでは、コード生成に入る前に overview と file-structure のガイダンスへ目を通すことが重要です。ローカルコピーに追加の provider template や隣接する skill が含まれている場合も、このスキルの resource ワークフローを理解してから比較してください。

スキルに十分なタスクブリーフを渡す

provider-resources usage が最も力を発揮するのは、remote object の型、必須 identifier、CRUD の挙動、特有の state ルールを明確に渡したときです。弱い指示は「resource を作って」です。より強い指示は、たとえば次のようになります。

• API object と endpoint
• 必須、optional、computed、ForceNew の各フィールド
• drift の検出方法
• update の適用方法
• read が eventually consistent かどうか
• acceptance test で何を証明すべきか

こうした情報があれば、スキルは勝手な前提を置かず、バックエンドに合ったコードとガイダンスを出せます。

repository-first のワークフローで進める

最良の結果を得るには、まず既存の provider レイアウトに resource をどう当てはめるかの計画を出させ、そのうえで schema、create/read/update/delete、importer、tests の順に一つずつ実装します。リポジトリ内に似た resource があるなら、必ず明示的に示してください。そうすることで、スキルは一般論ではなくローカルのパターンを再利用しやすくなります。

provider-resources skill の FAQ

provider-resources は新しい resource 専用ですか？

いいえ。既存 resource のリファクタリング、既存 resource の横に data source を追加する作業、またはすでにある provider の state や test の問題を直す用途にも同じように役立ちます。API 自体はすでに存在していて、それを Terraform でどうきれいに表現するかが作業の中心なら、特に強みを発揮します。

Plugin Framework の経験が先に必要ですか？

必須ではありません。スキルは初心者が正しい構造に沿う助けになりますが、API と provider の振る舞いを明確に説明できるほど、効果は高くなります。identity、lifecycle、update の意味を説明できないなら、先に情報を整理するか、最初の案は粗くなる前提で使ってください。

通常のプロンプトと何が違いますか？

通常のプロンプトは、ローカル規約や test の厳密さがないまま、それらしい provider コードを出しがちです。provider-resources は Terraform ネイティブなレイアウト、resource と documentation の対応、acceptance test を意識した考え方へ寄せるため、レビュー時の手戻りを減らしやすいのが利点です。

どんなときにこのスキルを使うべきではありませんか？

関連のない backend CRUD アプリ、一般的な Go アーキテクチャ、Terraform module の作成には使わないでください。主な作業が packaging、release automation、registry docs であれば、それらに特化した別の skill を選ぶべきです。

provider-resources skill を改善する方法

機能名だけでなく API の事実を渡す

provider-resources の出力を最も早く改善する方法は、対象 object の契約を正確に説明することです。ID、create の入力、read 時の形、変更可能な field、delete の意味を具体的に伝えてください。API に async creation、部分更新、server-generated name などの癖があるなら、それも早めに共有します。そうした細部が provider の設計を左右します。

そのまま真似してほしいローカルパターンを示す

リポジトリ内に近い実装例があるなら、該当する file や resource を明示してください。そうすると、スキルは新しい流儀を作るのではなく、既存の provider 規約に寄せやすくなります。特に schema の命名、test helper、state transition ではこの差が大きく出ます。

まずは失敗しやすい部分から頼む

最も壊れやすいのは、たいてい import/state の扱い、computed field、acceptance test です。docs や helper function を整える前に、まずそこを解決するよう依頼してください。最初の回答が惜しいが不完全なら、失敗した test 出力や schema の diff を渡して、次の試行で具体的な不一致を直せるようにします。