terraform-skill

Claude 向け Terraform スキル

Terraform と OpenTofu の診断を優先するガイダンスです。コアファイルはワークフローで、詳細は必要に応じて読み込むリファレンスにあります。

応答の要件

Terraform/OpenTofu に関するすべての応答には、次の内容を含める必要があります。

1. 前提条件と最低バージョン — ランタイム（terraform または tofu）、正確なバージョン、プロバイダー、状態バックエンド、実行経路（ローカル/CI/Cloud/Atlantis）、環境の重要度。ユーザーから情報が提示されていない場合は、前提条件を明示します。
2. 対応するリスクカテゴリ — 次のうち1つ以上：ID の変更、シークレットの露出、影響範囲、CI とのドリフト、コンプライアンスの不備、状態の破損、プロバイダーのアップグレードリスク、テストの盲点。
3. 選択した修正策とトレードオフ — 何を選択し、何をトレードオフとして受け入れたか、その理由。
4. 検証計画 — ランタイムとリスクレベルに合わせた正確なコマンド（fmt -check、validate、plan -out、ポリシーチェック）。
5. ロールバックに関する注意 — 破壊的な変更や状態を変更する変更について、元に戻す方法と保持すべき証跡。

レビュー済みのプラン成果物と承認なしに、本番環境へ直接適用することを推奨してはいけません。

terraform destroy（対象指定または全リソース）を実行する場合は、まず terraform plan -destroy を実行し、削除されるすべてのリソースをユーザーに示してください。これには、locals や for_each を介して暗黙的に含まれる依存リソースも含まれます。続行する前に、明示的な確認を得てください。destroy では -auto-approve を絶対に使用しないでください。

ワークフロー

1. 実行コンテキストを把握する — ランタイムとバージョン、プロバイダー、バックエンド、実行経路、環境の重要度。
2. 以下のルーティング表を使って障害モードを診断する。意図が複数のカテゴリにまたがる場合は、両方のリファレンスを読み込みます。
3. 該当するリファレンスファイルのみを読み込む — タスクに不要な詳細を事前に読み込まないでください。
4. リスク対策を含めて修正を提案する — その修正が障害モードにどう対処するか、残るリスク、ガードレール（テスト/承認/ロールバック）を示します。
5. 成果物を生成する — HCL、移行ブロック（moved、import）、CI の変更、ポリシールール。
6. 最終確定前に検証する — リスクレベルに合わせた検証コマンドを実行します。
7. 最後に応答の要件を提示する。

生成する前に診断する

失敗カテゴリ	症状	主な参考資料
アイデンティティの変動	リファクタリング後にリソースアドレスが変わる、count のインデックスが変動する、moved ブロックがない	コードパターン：count と for_each、コードパターン：moved ブロック、コードパターン：LLM の誤り
シークレットの露出	デフォルト値、state、ログ、CI アーティファクトにシークレットが含まれる	セキュリティとコンプライアンス、コードパターン：書き込み専用、state 管理
影響範囲の拡大	スタックが過大、本番環境と非本番環境で state を共有、安全でない適用	state 管理、モジュールパターン
破棄の連鎖	対象を指定した破棄で想定以上のリソースが削除される。対象リソースを参照する locals により、すべての for_each 利用リソースが暗黙の依存先になる	応答規約：まず plan-destroy を実行する。state 管理：安全な破棄
CI との乖離	ローカルの plan と CI の plan が一致しない、レビュー済みアーティファクトなしで apply する、バージョンが固定されていない	CI/CD ワークフロー、コードパターン：バージョン
コンプライアンスの不足	ポリシーの段階がない、承認モデルがない、証跡を保持しない	セキュリティとコンプライアンス、CI/CD ワークフロー
テストの見落とし	算出値を plan のみで検証する、set 型のインデックス指定、モックと実環境の混同	テストフレームワーク
state の破損／復旧	ロックが解除されない、バックエンドの移行、ドリフトの調整	state 管理
プロバイダーのアップグレードリスク	破壊的変更を伴うプロバイダーの更新、モジュールのバージョンが固定されていない	コードパターン：バージョン、モジュールパターン
プロバイダーのライフサイクル	state にリソースが残ったままプロバイダーを削除する、リソースが孤立する、removed ブロックを使用する	state 管理：プロバイダーの削除
ブートストラップ／オーケストレーションの誤用	ブートストラップに null_resource と local-exec を使う、セットアップスクリプトに remote-exec を使う、プロビジョナーの標準出力から CI ログにシークレットが漏れる	コードパターン：プロビジョナーは最後の手段
ナビゲーション／安全な名前変更の見落とし	シンボルの定義や参照を意味的に特定できない、値シンボルの名前変更をテキストの一括置換で行う、grep のみのリファクタリングで参照が漏れる、rg の代替コマンドを捏造する	コードインテリジェンス
クラウド間／プロバイダーマッピング	「X に相当する Azure／GCP の機能は何か」、クラウドごとにバックエンドや認証モデルを選択する	state 管理：クラウド間の相当機能

このスキルを使用するタイミング

次の場合に有効化します： Terraform／OpenTofu の設定やモジュールの作成・レビュー、テストの設定やデバッグ、複数環境へのデプロイ構成、IaC の CI/CD の実装、モジュールパターンや state 構成の選択、リモート state バックエンドの設定や移行。

次の場合は使用しません： Claude がすでに把握している HCL の基本的な構文に関する質問、プロバイダー API のリファレンス（ドキュメントへのリンクを提示してください）、Terraform／OpenTofu に関係のないクラウドプラットフォームに関する質問。

基本原則

モジュール階層

種類	使用する場面	スコープ
リソースモジュール	関連するリソースをまとめた単一の論理グループ	VPC + サブネット、SG + ルール
インフラストラクチャモジュール	特定の目的に応じたリソースモジュールの集合	1 つのリージョン／アカウント内の複数のリソースモジュール
コンポジション	インフラストラクチャ全体	複数のリージョン／アカウントにまたがる

フロー：リソース → リソースモジュール → インフラストラクチャモジュール → コンポジション。

ディレクトリ構成

environments/   # prod/ staging/ dev/  — per-env configurations
modules/        # networking/ compute/ data/ — reusable modules
examples/       # minimal/ complete/ — docs + integration fixtures

環境とモジュールは分けてください。examples/はドキュメントとテスト用フィクスチャの両方として使用します。モジュールは小さく、単一の責務を持つようにしてください。

アーキテクチャの原則、命名規則、変数／出力の契約については、モジュールパターンを参照してください。

命名規則（概要）

• 内容が分かるリソース名を使用します（aws_instance.mainではなくaws_instance.web_server）
• thisは、本当に単一のリソースの場合にのみ使用します
• 変数名にはコンテキストを付けます（cidrではなくvpc_cidr_block）
• 標準ファイル：main.tf、variables.tf、outputs.tf、versions.tf

例については、モジュールパターン：変数の命名とコードパターン：ブロックの順序を参照してください。

ブロックの順序（概要）

リソースブロック：count／for_each → 引数 → tags → depends_on → lifecycle。 変数ブロック：description → type → default → validation → nullable → sensitive。

完全なルールと例については、コードパターン：ブロックの順序と構造を参照してください。

テスト戦略

判断マトリックス：どのテスト方法を選ぶか？

状況	方法	ツール	コスト
手早い構文チェック	静的解析	validate、fmt	無料
コミット前の検証	静的解析 + リント	validate、tflint、trivy、checkov	無料
Terraform 1.6 以降、単純なロジック	ネイティブテストフレームワーク	terraform test	無料～低
1.6 より前、または Go の知識がある場合	統合テスト	Terratest	低～中
セキュリティ／コンプライアンスを重視	ポリシー・アズ・コード	OPA、Sentinel	無料
コスト重視のワークフロー	モックプロバイダー（1.7 以降）	ネイティブテスト + モック	無料
マルチクラウド、複雑な構成	完全な統合テスト	Terratest + 実インフラ	中～高

ネイティブテストのルール（1.6 以降）

テストコードを書く前に、Terraform MCP を使ってリソーススキーマを検証し、アサーションの対象が実在する属性であることを確認してください。

• command = plan — 高速です。入力から導出される値にのみ使用します
• command = apply — 計算値（ARN、生成された名前）とset 型のネストされたブロックには必須です
• set 型のブロックは[0]でインデックス指定できません — for式を使うか、command = applyで具体化してください
• 一般的な set 型：S3 の暗号化ルール、ライフサイクルの移行設定、IAM ポリシーステートメント

静的解析パイプライン、ネイティブテストのパターン、Terratest の統合、モックプロバイダー、LLM が起こしやすい間違いのチェックリスト全体については、テストフレームワークを参照してください。

Count と For_Each — クイックルール

シナリオ	使用するもの	理由
ブール条件（作成する／しない）	count = condition ? 1 : 0	単一リソースの任意切り替え
要素の並べ替えや削除があり得る	for_each = toset(list)	リソースアドレスが安定する
キーで参照する	for_each = map	名前によるアクセス
複数の名前付きリソース	for_each	ID の安定性が高い

リストのインデックスを、長期間維持する ID として使わないでください — 中間の要素を削除すると、それ以降のすべてのアドレスがずれます。判断マトリックス、安全な移行手順書、movedブロックのパターン、plan 時点で判明する既知の失敗ケースについては、コードパターン：count と for_eachを参照してください。

依存関係管理用のローカル値

try()をローカル値で使用し、親リソースよりも条件付きリソースの属性を優先する方法は、特殊ですが効果の高いパターンです。明示的なdepends_onなしで、正しい削除順序を保証できます。よくある用途は、VPC、セカンダリCIDRの関連付け、サブネットの組み合わせです。

完全なパターンと具体例については、コードパターン：依存関係管理用のローカル値をご覧ください。

モジュール開発

標準的なレイアウト：

my-module/
├── README.md       # Usage documentation
├── main.tf         # Primary resources
├── variables.tf    # Typed inputs with descriptions
├── outputs.tf      # Output values
├── versions.tf     # required_version + required_providers
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── module_test.tftest.hcl   # or Go for Terratest

変数の契約：必ずdescriptionを指定し、typeを明示します。複雑な制約にはvalidationを使用し、シークレットにはsensitive = trueを指定します。型付きのデフォルト値を持つoptional()（1.3以降）を、型指定のないmap(any)より優先します。

出力の契約：必ずdescriptionを指定し、機密性の高い出力にはsensitiveを指定します。プロバイダーオブジェクト全体ではなく、安定した部分集合を公開します。

契約のパターン、モジュールリリースのチェックリスト、LLMによる誤りのチェックリストについては、モジュールパターンをご覧ください。

CI/CD

パイプラインのステージ：validate → test → plan → apply（環境保護を適用）。

コスト管理：PRの検証ではモックプロバイダーを使用し、実際のクラウドとの統合テストはmainまたはスケジュール実行時に限定します。テストリソースにタグを付け、自動クリーンアップを設定します。

ドリフト防止：ランタイムとプロバイダーのバージョンを固定し、.terraform.lock.hclをコミットします。planステージで作成したレビュー済みのplanアーティファクトをapplyします（applyジョブ内でplanを再実行しないでください）。applyに至るすべての経路で、ポリシー／セキュリティのステージを実行します。

GitHub Actions、GitLab CI、AtlantisのテンプレートとLLMによる誤りのチェックリストについては、CI/CDワークフローをご覧ください。

セキュリティとコンプライアンス

必須のチェック：

trivy config .
checkov -d .

**避けること：**シークレットを変数や.tfvarsに保存する、デフォルトVPCを使用する、暗号化を省略する、セキュリティグループを0.0.0.0/0に公開する、aws_security_groupでインラインのingress／egressブロックを使用する。

**実施すること：**クラウドのシークレットマネージャー（AWS Secrets Manager／Azure Key Vault／GCP Secret Manager）からシークレットを取得するか、1.11以降ではwrite_only引数を使用します。専用のVPCを作成し、保存時の暗号化とTLSを強制します。最小権限のSGを使用し、個別のaws_vpc_security_group_{ingress,egress}_ruleリソース（AWS provider v5以降など）を使用します。

変数にsensitive = trueを指定しても、表示がマスクされるだけです。値は引き続きstateに保存されます。1.11以降ではwrite_only／*_woを使用するか、実行時の参照によってシークレット情報をTerraformの管理対象から完全に除外してください。

trivy／checkovのパイプライン、stateファイルの強化、コンプライアンス対応表、LLMによる誤りのチェックリストについては、セキュリティとコンプライアンスをご覧ください。

State管理

**チームや本番環境でローカルstateを使用しないでください。**リモートバックエンドでは、自動ロック、暗号化、バージョン管理、監査ログ、安全な共同作業が提供されます。

リモートバックエンドの選択

AWSの例（Azure azurerm／GCP gcs／TF Cloudの構文については、State管理：リモートバックエンドの選択をご覧ください）：

terraform {
  backend "s3" {
    bucket        = "my-terraform-state"
    key           = "prod/vpc/terraform.tfstate"
    region        = "us-east-1"
    encrypt       = true
    use_lockfile  = true   # Native S3 locking, 1.10+
  }
}

Terraform < 1.10では、use_lockfileの代わりにdynamodb_table = "terraform-state-lock"を使用してください。Azure Storage、GCS、Terraform Cloudにはすべて組み込みのロック機能があります。構文については、State管理のリファレンスをご覧ください。バックエンドとそのロック方式の選択については、リモートバックエンドの選択をご覧ください。

Stateの構成

パターン	使用する状況	パスの例
環境ごと	環境ごとにチームが異なる	prod/terraform.tfstate、staging/...
コンポーネントごと	ライフサイクルが独立している	prod/vpc/、prod/eks/、prod/rds/
ハイブリッド（推奨）	両方の利点を得たい	prod/networking/、prod/compute/、staging/networking/

チームが異なる場合、更新頻度が異なる場合、またはリソース数が500を超える場合は、stateを分割します。密接に結合したリソース、リソース数が100未満の場合、ライフサイクルが同じ場合は、まとめます。

ロック、移行、複数チームの分離、災害復旧、LLMによる誤りのチェックリストについては、State管理をご覧ください。

バージョン管理

コンポーネント	方針	例
Terraform ランタイム	マイナーバージョンを固定	required_version = "~> 1.9"
プロバイダー	メジャーバージョンを固定	version = "~> 5.0"
モジュール（本番環境）	正確なバージョンを固定	version = "5.1.2"
モジュール（開発環境）	パッチバージョンを許可	version = "~> 5.1"

.terraform.lock.hcl は意図を持ってコミットしてください。プロバイダーやランタイムのアップグレードは、機能変更とは別の PR にしてください。制約の構文とアップグレードのワークフローについては、コードパターン：バージョン管理を参照してください。

Terraform の最新機能（1.0+）

機能	最低バージョン	一般的な用途
try()	0.13+	安全なフォールバック。element(concat()) を置き換えます
nullable = false	1.1+	null によってデフォルト値が暗黙的に上書きされるのを防ぎます
moved ブロック	1.1+	リソースの破棄や再作成をせずにリファクタリングします
デフォルト値付きの optional()	1.3+	型指定されたオブジェクト属性
import ブロック	1.5+	宣言的なインポート。VCS でレビューできます
check ブロック	1.5+	実行時アサーション
ネイティブの terraform test	1.6+	組み込みテストフレームワーク
モックプロバイダー	1.7+	コストのかからないユニットテスト
removed ブロック	1.7+	宣言的なリソース削除
プロバイダー定義関数	1.8+	プロバイダー固有の変換（プロバイダーによる関数の宣言が必要）
変数間の検証	1.9+	validation ブロック内で他の var.* を参照します
write_only 引数	1.11+	シークレットをステートに保存しません
S3 ネイティブロックファイル	1.10+	DynamoDB を使わずにステートをロックします

機能を使用する前に、ランタイムの最低バージョンを確認してください。機能ごとの一般的な LLM のエラーパターンを含む完全な表は、コードパターン：機能ガード表を参照してください。

ランタイム固有のガイダンス

• Terraform 1.0-1.5（OpenTofu は 1.6 から）：統合テストには Terratest を使用し、静的解析とプランの検証のみを行います（ネイティブテストはありません）。
• 1.6+：ネイティブの terraform test / tofu test が利用できます。簡単なユニットテストを移行し、複雑な統合テストには Terratest を引き続き使用してください。
• 1.7+：モックプロバイダーでテストコストを削減できます。ユニットテストにはモックを使用し、最終的な統合テストには実際の実行を使用してください。
• 1.10+：新しい構成では S3 ネイティブロックファイル（use_lockfile）をデフォルトとして使用してください。DynamoDB によるロックは不要になりました。
• 1.11+：シークレット処理に write_only 引数を使用すると、認証情報をステートに保存せずに済みます。
• Terraform と OpenTofu：どちらもサポートされています。ライセンス、ガバナンス、機能の違いについては、クイックリファレンス：Terraform と OpenTofuを参照してください。

コードインテリジェンス（terraform-ls）

HCL のセマンティックナビゲーションです。terraform-ls は任意です。使用しない場合、以下のすべての項目は、rg と Read によるフォールバックに劣化することを明示します。

汎用的なコードインテリジェンスの規律に対応する、自己完結型の terraform-ls レイヤーです。以下の項目をそのまま適用してください。推奨される併用プラグイン：code-intelligence プラグイン（同じ antonbabenko/agent-plugins マーケットプレイス）は、汎用的な規律（位置アンカリング、劣化ゲート、開示形式、アンチ・ファントム・シム）を備え、準備状況を確認する /code-intelligence:doctor を提供します。インストールされている場合は、その汎用プロトコルに従ってください。このスキルは、プラグインがなくても完全に自己完結しています。

目的	使用方法	トレードオフ
定義／すべての参照を検索する	terraform-ls goToDefinition ／ findReferences	init と位置アンカーが必要です
値シンボル（var／local／output／provider エイリアス）の名前を変更する	手動：findReferences → ファイルごとに最新の Read → 編集 → validate	名前変更プロバイダーはありません
リソース／モジュールのアドレス名を変更する	moved ブロックと plan で destroy が 0 件であることを確認	テキスト上の名前変更では破棄／再作成が発生します
正確なテキスト／既知の名前／.tfvars ／ HCL 以外	rg + Read	セマンティックなスコープはありません

✅ サポート対象：goToDefinition、findReferences、documentSymbol、hover、workspaceSymbol。 ❌ サポート対象外：goToImplementation、呼び出し階層、名前変更プロバイダー。これらを呼び出したうえで、その不在を調査結果として報告しないでください。

• ✅ 前提条件：ローカルの terraform／tofu が PATH 上にあり、terraform init が実行済みであること。初回起動時は再試行が必要な場合があります。
• ✅ LSP 呼び出しは位置アンカー（file:line:character）を使用します。先に rg でアンカーを特定してください。シンボル名だけで呼び出してはいけません。
• ❌ 劣化ゲートを通過するまでは、「LSP が壊れているため rg を使用」と主張しないでください。ツールを代替する場合は、最初の行で明示してください。

詳細：コードインテリジェンス。

参考ファイル

段階的な情報開示 — ここでは要点を示し、詳細は必要に応じて確認できます。

• テストフレームワーク — 静的解析、ネイティブテスト、Terratest、モックプロバイダー
• モジュールのパターン — 構成、変数／出力の契約、terraform_remote_state のルール、リリースチェックリスト
• CI/CD ワークフロー — GitHub Actions、GitLab CI、Atlantis、コスト管理
• セキュリティとコンプライアンス — trivy／checkov、シークレットの取り扱い、コンプライアンス対応表
• 状態管理 — バックエンド、ロック、移行、複数チーム、復旧
• コードパターン — ブロックの順序、count／for_each の詳細、最新機能、バージョン管理、locals
• コードインテリジェンス - terraform-ls の機能、位置アンカー付き呼び出し、手動での名前変更、劣化ゲート
• クイックリファレンス — コマンド早見表、フローチャート、トラブルシューティング

ライセンス

Apache License 2.0。全文は LICENSE を参照してください。

Copyright © 2026 Anton Babenko