terraform-module-library

terraform-module-library スキルの概要

terraform-module-library でできること

terraform-module-library スキルは、使い捨ての .tf ファイルを作るのではなく、クラウドインフラ向けの再利用可能な Terraform モジュールを設計するためのスキルです。AWS、Azure、GCP、OCI 向けに社内モジュールカタログを整備したいチームに向いており、モジュール構成、サンプル配置、テスト方針を一貫した形で揃えやすくなります。

terraform-module-library を使うべき人

特に相性が良いのは、VPC/VNet、Kubernetes、データベース、ストレージ、ロードバランサーなどの Terraform の部品を、繰り返し使える形で整えたいプラットフォームエンジニア、クラウドアーキテクト、DevOps チーム、コンサルタントです。単一環境のスタックを出したいのではなく、保守しやすいモジュールリポジトリの形で成果物を揃えたい場合に、terraform-module-library は特に有効です。

実際に解決したい仕事は何か

多くのユーザーが欲しいのは、抽象的な意味での「Terraform コード」ではありません。あとから別のチームが安全に利用できるように、入力、出力、バージョン、サンプル、テストが明確なモジュールです。terraform-module-library の価値は、会話の焦点を単なるリソース記述ではなく、モジュールのインターフェース、デフォルト値、構成の分離、プロバイダーごとの実践的な設計に向けてくれる点にあります。

このスキルが他と違う理由

最大の差別化ポイントは、構造が明確なことです。元のソースでは、main.tf、variables.tf、outputs.tf、versions.tf、README.md、examples/complete、tests を含む標準的なモジュール構成がはっきり示されています。さらに AWS と OCI についてはクラウド固有の参照ガイドもあり、単なる「Terraform を書いて」という汎用プロンプトより、具体的な方向づけがしやすくなっています。

terraform-module-library が強くハマる場面

次のようなときは terraform-module-library が有力です。

• 再利用可能なモジュールをゼロから作りたい
• チーム間でモジュール構成を標準化したい
• クラウドプロバイダーごとの慣例を 1 つのモジュールインターフェースに落とし込みたい
• モジュール本体と一緒にサンプルやテストも整えたい
• 複数環境にまたがる Cloud Architecture 業務向けにモジュールライブラリを作りたい

向いていないケース

次のような用途だけが目的なら、このスキルはやや不向きです。

• 1 ファイルですぐ試せる Terraform の PoC を作りたい
• 実運用中の依存関係を多数含むフル環境構成を作りたい
• 参照資料を超えるレベルで、プロバイダー固有の深い実装知識が必要
• モジュール向けのデプロイ自動化、CI/CD、リリース設計まで欲しい

terraform-module-library スキルの使い方

terraform-module-library の導入コンテキスト

スキルは wshobson/agents リポジトリからインストールします。

npx skills add https://github.com/wshobson/agents --skill terraform-module-library

その後、エージェント環境から呼び出すときは、「インフラコード」ではなく「再利用可能な Terraform モジュール」が欲しいことを明確に伝えてください。このスキルは Terraform provider や CLI plugin として入るものではなく、モジュール指向の出力を得るためのプロンプトベースのガイダンスとパターン集です。

プロンプト前にまず読むべきファイル

最初に確認したいのは次の 3 つです。

1. plugins/cloud-infrastructure/skills/terraform-module-library/SKILL.md
2. plugins/cloud-infrastructure/skills/terraform-module-library/references/aws-modules.md
3. plugins/cloud-infrastructure/skills/terraform-module-library/references/oci-modules.md

SKILL.md には、狙うべきモジュール構成が示されています。参照ファイルには、実践的なモジュール候補やベストプラクティスがまとまっており、特に AWS のデフォルト設計や OCI のインターフェース設計を具体化するのに役立ちます。

うまく機能させるために必要な入力

terraform-module-library スキルは、次の情報を渡すと精度が上がります。

• クラウドプロバイダー: AWS、Azure、GCP、OCI
• モジュール種別: VPC、EKS、RDS、object storage、load balancer など
• 想定利用者: platform team、app teams、shared services
• 必要な inputs と outputs
• セキュリティ要件: encryption、IAM、logging、backups
• 命名規則と tagging 標準
• Terraform と provider のバージョン制約
• examples と Terratest のひな形が必要かどうか

これらがないと、もっともらしいモジュール形状は出ても、インターフェース設計が弱くなりがちです。

あいまいな要望を強い terraform-module-library プロンプトに変える

弱いプロンプト:

Create a Terraform module for AWS networking.

より良いプロンプト:

Use terraform-module-library to design a reusable AWS VPC module for internal platform teams. Include main.tf, variables.tf, outputs.tf, versions.tf, README.md, examples/complete, and tests/module_test.go. Support public and private subnets, NAT gateways, route tables, VPC flow logs, standard tags, and encryption where applicable. Target Terraform 1.x and aws provider ~> 5.0. Expose outputs needed by EKS and RDS modules. Keep the interface stable and avoid environment-specific values.

後者のほうが出力品質が上がるのは、利用者、互換性、対象範囲、他モジュールとの接続先が明確になるからです。

実案件でのおすすめワークフロー

実務での terraform-module-library usage は、次の流れが実用的です。

1. まず 1 つのモジュール境界を決める
2. 最初に公開インターフェースを定義する
3. provider / version 制約を明示する
4. モジュールのフォルダ構成を出させる
5. 実装詳細より先に variables.tf と outputs.tf を固める
6. 利用者が理解しやすいよう examples/complete を追加する
7. 基本検証用に tests/module_test.go を追加する
8. デフォルト値、任意機能、outputs を反復調整する

この順序にすると、入力が不安定で肥大化したモジュールになりにくくなります。

リソース数より先にインターフェース設計から始める

よくある失敗は、「全部入りにして」と頼んでしまうことです。再利用可能なモジュールで重要なのは、リソース数より API のきれいさです。

• どの入力が必須か
• どのオプションが安全なデフォルトか
• どの出力が下流モジュールの合成に効くか
• どの機能をスコープ外に残すべきか

たとえば AWS の VPC モジュールなら、subnet IDs や VPC ID を素直に取り出せることが重要です。OCI のネットワークモジュールなら、compartment に関する入力を明示的に持ち、他モジュールで必要になる OCIDs を返す設計が求められます。

組み込みの provider 参照を活かすコツ

AWS の参照は、次のようなモジュールで特に有用です。

• vpc
• eks
• rds
• s3
• alb
• lambda
• security-group

あわせて、実運用で重視されやすいデフォルトも示されています。たとえば provider ~> 5.0、暗号化のデフォルト有効化、最小権限の IAM、tagging、logging、backups、AWS Well-Architected に沿った考え方です。

OCI の参照は、terraform-module-library for Cloud Architecture の作業で次のような要件があるときに役立ちます。

• compartment を明示的にモデリングする
• 広い security lists より NSGs を優先する
• dynamic groups と最小権限 IAM を使う
• 合成しやすいように OCIDs を公開する
• logging、metrics、backup のデフォルトを持たせる

モジュールのひな形を明示して依頼する

このスキルは、標準パターンを明示して出させると一番効果を発揮します。

• main.tf
• variables.tf
• outputs.tf
• versions.tf
• README.md
• examples/complete/main.tf
• examples/complete/variables.tf
• tests/module_test.go

このひな形を明示しないと、多くのエージェントは docs、examples、tests を省きがちで、結果として再利用性が落ちます。

出力品質を上げる実践的なプロンプトパターン

次のような依頼の仕方が有効です。

• Generate only the module interface first: variables, outputs, versions, and README table.
• Keep environment values out of the module and move them to examples.
• Mark optional features clearly and prefer secure defaults.
• Show how this module composes with EKS, RDS, or OKE consumers.
• Explain which features should be separate modules instead of inlining everything.

こうしたパターンは、境界を明確にし、過剰に盛り込まれたモジュールを防ぐのに効きます。

初稿で確認すべきポイント

出力を採用する前に、次を確認してください。

• variable 名は安定していて読みやすいか
• outputs は下流モジュールに十分か
• 実用上無理のない範囲で secure defaults が有効になっているか
• example は本当に利用可能な形になっているか
• tests はモジュールのインターフェースに沿っているか
• 再利用可能なモジュールに environment stack のロジックが混ざっていないか

ここを見ておくと、導入初期でよくあるつまずきをかなり防げます。

terraform-module-library スキル FAQ

terraform-module-library は初心者にも向いている？

はい。Terraform モジュールの構造を学びたいなら有用です。レイアウトが明確で、具体的なモジュール例もあります。ただし、provider 引数、リソースの挙動、テスト実行を自分で検証するための基本的な Terraform 知識は必要です。

AI に Terraform を書かせるのと何が違う？

汎用的なプロンプトだと、モジュール境界が弱いまま resource コードだけが返ってくることがよくあります。terraform-module-library skill は、再利用可能なインターフェース、examples、tests、ライブラリ向けの構成が必要な場面でより有効です。コード量を増やすというより、保守性を上げることに価値があります。

terraform-module-library は Terraform に何かインストールするの？

いいえ。terraform-module-library install で追加されるのは Terraform 自体ではなく、エージェントの作業フローに組み込むスキルです。terraform fmt、terraform validate、テスト、provider 初期化といった通常の Terraform ツール実行は、引き続き自分の環境で行います。

どのクラウドプロバイダーのサポートが強い？

スキルとしては AWS、Azure、GCP、OCI を高水準で対象にしています。ただし、リポジトリ上の根拠として具体的な参照ファイルがあるのは AWS と OCI なので、現時点ではこの 2 つが最もガイダンスが強いと考えられます。

terraform-module-library は本番用途に向いている？

本番運用を見据えたモジュールの設計・生成補助としては十分使えます。特に testing、examples、versions、secure defaults を重視している点は実務向きです。ただし、provider の公式ドキュメント確認、validation 実行、組織のポリシー適用、CI チェックは別途必要です。

terraform-module-library を避けるべきなのはどんなとき？

次のような要件が主目的なら、別の手段のほうが向いています。

• 実運用のフル live environment root module が必要
• 深い policy-as-code や CI pipeline 設計が必要
• 参照資料で触れていない高度な provider のエッジケースを扱う
• module registry 向けの、強い方針を持った release / version 公開フローが必要

terraform-module-library スキルを改善する方法

モジュールのスコープをもっと狭くする

terraform-module-library の結果を最も手早く良くする方法は、モジュール境界を 1 つに絞ることです。「a full networking and app platform library」ではなく、「an AWS ALB module」や「an OCI Object Storage module」のように依頼してください。スコープが狭いほど、インターフェースはきれいになり、前提の食い違いも減ります。

下流の利用者を明示する

そのモジュールに何が依存するのかを伝えてください。たとえば次のように指定します。

• This VPC module must support EKS and RDS consumers.
• This OCI VCN module must expose subnet and security outputs for OKE.

これだけで出力品質は変わります。outputs が汎用的な羅列ではなく、利用目的を持った設計になるからです。

譲れない標準を最初に書く

次のような基準は最初から明示しておくのが効果的です。

• provider versions
• tag schema
• encryption defaults
• backup/logging requirements
• IAM least-privilege expectations
• compartment または account boundary のルール

このスキルはもともとこうした観点を重視しやすいですが、明文化しておくと後工程の手直しが減ります。

再利用ロジックと examples を分離する

よくある失敗は、環境固有の値が再利用モジュールに入り込むことです。初稿を改善するときは、次のように依頼すると効果的です。

• 固定の CIDRs、names、environment labels は examples/complete に移す
• module variables は汎用的で型付きに保つ
• outputs はデバッグ用のノイズではなく、合成に必要なものに絞る

こうすると、公開しやすく再利用しやすいモジュールになります。

追加要件だけでなく、除外すべきことも聞く

より良い terraform-module-library guide の使い方は、「何を入れるか」だけでなく「何を入れないか」も確認することです。たとえば次のような判断です。

• security groups は VPC module から分離する
• network modules に database 設定を抱き合わせない
• IAM が重すぎて責務が増えるなら別 module に分ける

こうした問いかけが、巨大な “kitchen sink” モジュール化を防ぎます。

2 回目のやり取りでテストとドキュメントを強化する

最初の出力のあと、次の成果物を追加で求めてください。

• usage と inputs/outputs を簡潔にまとめた README.md
• 現実的な examples/complete を 1 つ
• 最小限の tests/module_test.go
• edge cases と upgrade-safe defaults に関するメモ

生成モジュールがチームに採用されるかどうかは、こうした補助成果物で決まることが少なくありません。

クラウド固有の前提を検証する

AWS なら、暗号化、logging、tagging、provider ~> 5.0 といったパターンに沿っているかを確認してください。OCI なら、compartment の明示的な扱い、OCID outputs、NSG 優先、observability のデフォルトが入っているかを見ます。これは terraform-module-library usage の品質を大きく底上げする、特に効果の高い確認ポイントです。

全再生成ではなく差分ベースで改善する

毎回すべてを書き直させるのではなく、絞った修正依頼を出すほうが安定します。たとえば次のような形です。

• Tighten variable types and validations.
• Reduce required inputs to the true minimum.
• Add outputs needed by downstream EKS consumers.
• Refactor optional features behind booleans or maps.
• Split this into two modules if responsibilities are mixed.

この進め方のほうが、全面的な再生成を繰り返すより着実に品質を上げられます。