Terraform Skill for Claude

診断第一のアプローチで Terraform と OpenTofu をサポートします。コアファイルはワークフローであり、詳細な情報は必要に応じてロードされるリファレンスに含まれます。

レスポンス契約

すべての Terraform/OpenTofu レスポンスには以下を含める必要があります。

1. 前提条件とバージョン下限 — ランタイム (terraform または tofu)、正確なバージョン、プロバイダー、ステート バックエンド、実行パス (ローカル/CI/クラウド/Atlantis)、環境の重要度。ユーザーが提供しなかった場合は、ステートの前提条件を明示的に述べます。
2. 対処するリスク カテゴリ — identity churn、secret exposure、blast radius、CI drift、コンプライアンス ギャップ、state corruption、プロバイダー アップグレード リスク、テストの盲点のいずれか 1 つ以上。
3. 選択した改善策とトレードオフ — 何を選択したか、何をトレードオフしたか、理由は何か。
4. 検証計画 — ランタイムとリスク レベルに合わせた正確なコマンド (fmt -check、validate、plan -out、policy check)。
5. ロールバック ノート — 破壊的またはステート変更操作の場合、元に戻す方法と保持すべき証拠。

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

ワークフロー

1. 実行コンテキストをキャプチャ — ランタイム + バージョン、プロバイダー、バックエンド、実行パス、環境の重要度。
2. 以下のルーティング テーブルを使用して失敗モードを診断。意図が複数のカテゴリに分かれている場合は、両方のリファレンスをロードします。
3. 一致するリファレンス ファイルのみをロード — タスクが必要としない詳細情報は事前ロードしません。
4. リスク制御を伴う修正案を提案 — これがモードにどのように対処するか、何がまだ問題になるか、ガードレール (テスト/承認/ロールバック)。
5. 成果物を生成 — HCL、マイグレーション ブロック (moved、import)、CI 変更、ポリシー ルール。
6. 最終化前に検証 — リスク レベルに合わせた検証コマンドを実行します。
7. 最後にレスポンス契約を発行。

生成前に診断

失敗カテゴリ	症状	主要なリファレンス
Identity churn	リファクタリング後のリソース アドレス シフト、count インデックス churn、moved ブロック不足	Code Patterns: count vs for_each、Code Patterns: moved blocks、Code Patterns: LLM mistakes
Secret exposure	デフォルト、ステート、ログ、CI 成果物内の秘密情報	Security & Compliance、Code Patterns: write-only、State Management
Blast radius	過度に大きなスタック、本番環境と非本番環境の共有ステート、不安全なアプライ	State Management、Module Patterns
CI drift	ローカル プラン ≠ CI プラン、レビュー済み成果物なしのアプライ、ピン留めされていないバージョン	CI/CD Workflows、Code Patterns: versions
Compliance gaps	ポリシー ステージの不足、承認モデルなし、証拠保持なし	Security & Compliance、CI/CD Workflows
Testing blind spots	プランのみの計算値検証、セット タイプのインデックス、モック/実検証の混同	Testing Frameworks
State corruption / recovery	ロック スタック、バックエンド マイグレーション、ドリフト調整	State Management
Provider upgrade risk	破壊的変更を含むプロバイダー バージョン アップ、ピン留めされていないモジュール	Code Patterns: versions、Module Patterns
Provider lifecycle	ステート内にリソースがある状態でプロバイダーを削除、孤立したリソース、removed ブロック使用法	State Management: Provider Removal

このスキルを使用する時期

以下の場合にアクティベート： Terraform/OpenTofu 構成またはモジュールの作成またはレビュー、テストのセットアップまたはデバッグ、マルチ環境デプロイメントの構造化、IaC CI/CD の実装、モジュール パターンまたはステート 構成の選択、リモート ステート バックエンドの構成またはマイグレーション。

使用しないケース： Claude がすでに知っている基本的な HCL 構文の質問、プロバイダー API リファレンス (ドキュメントへのリンク)、Terraform/OpenTofu に関連しないクラウド プラットフォームの質問。

コア原則

モジュール階層

タイプ	使用する時期	スコープ
リソース モジュール	接続されたリソースの単一の論理グループ	VPC + サブネット、SG + ルール
インフラストラクチャ モジュール	目的のためのリソース モジュールのコレクション	1 つのリージョン/アカウント内の複数のリソース モジュール
Composition	完全なインフラストラクチャ	複数のリージョン/アカウントにまたがる

フロー: リソース → リソース モジュール → インフラストラクチャ モジュール → Composition。

ディレクトリ レイアウト

environments/   # prod/ staging/ dev/  — 環境ごとの構成
modules/        # networking/ compute/ data/ — 再利用可能なモジュール
examples/       # minimal/ complete/ — ドキュメント + 統合フィクスチャ

環境とモジュールを分離します。examples/ をドキュメントとテスト フィクスチャの両方として使用します。モジュールは小さく、単一責任に保ちます。

アーキテクチャ原則、命名規則、変数/出力契約については、Module Patterns を参照してください。

命名規則 (概要)

• 説明的なリソース名 (aws_instance.main ではなく aws_instance.web_server)
• 本当のシングルトン リソースのみに this を予約
• 変数にコンテキストをプレフィックス (cidr ではなく vpc_cidr_block)
• 標準ファイル: main.tf、variables.tf、outputs.tf、versions.tf

例については、Module Patterns: Variable Naming と Code Patterns: Block Ordering を参照してください。

ブロック順序 (概要)

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

完全なルールと例については、Code Patterns: Block Ordering & Structure を参照してください。

テスト戦略

決定マトリックス: どのテスト アプローチを使用するか？

状況	アプローチ	ツール	コスト
簡単な構文チェック	静的分析	validate、fmt	無料
コミット前の検証	静的 + lint	validate、tflint、trivy、checkov	無料
Terraform 1.6+、単純なロジック	ネイティブ テスト フレームワーク	terraform test	無料～低
Pre-1.6 または Go スキル	統合テスト	Terratest	低～中
セキュリティ/コンプライアンス重視	ポリシー コード	OPA、Sentinel	無料
コスト意識が高いワークフロー	モック プロバイダー (1.7+)	ネイティブ テスト + モック	無料
マルチクラウド、複雑	完全な統合	Terratest + 実インフラ	中～高

ネイティブ テスト ルール (1.6+)

テスト コードを書く前に、Terraform MCP を使用してリソース スキーマを検証し、アサーションが実際の属性をターゲットにしていることを確認します。

• command = plan — 高速、入力から導き出された値のみ
• command = apply — 計算値 (ARN、生成名) および セット タイプのネストされたブロック に必要
• セット タイプ ブロックは [0] でインデックスできません — for 式を使用するか、command = apply を使用して具体化します
• 一般的なセット タイプ: S3 暗号化ルール、ライフサイクル遷移、IAM ポリシー ステートメント

静的分析パイプライン、ネイティブ テスト パターン、Terratest 統合、モック プロバイダー、および完全な LLM 誤りチェックリストについては、Testing Frameworks を参照してください。

Count vs For_Each — クイック ルール

シナリオ	使用	理由
ブール条件 (作成 / しない)	count = condition ? 1 : 0	オプションのシングルトン トグル
アイテムが並べ替えられるか削除される可能性がある	for_each = toset(list)	安定したリソース アドレス
キーで参照	for_each = map	名前付きアクセス
複数の名前付きリソース	for_each	より良い ID の安定性

決してリスト インデックスを長寿命の ID として使用しないでください — 中間要素を削除するとその後のすべてのアドレスが並べ替えられます。決定マトリックス、安全なマイグレーション プレイブック、moved ブロック パターン、および既知のプラン時失敗ケースについては、Code Patterns: count vs for_each を参照してください。

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

条件付きリソースの属性をその親に優先する場合、ローカルで try() を使用するのは特殊化された高価値パターンです — 明示的な depends_on なしで正しい削除順序を強制します。一般的な使用: VPC + セカンダリ CIDR 関連付け + サブネット。

完全なパターンと実行例については、Code Patterns: Locals for Dependency Management を参照してください。

モジュール開発

標準レイアウト:

my-module/
├── README.md       # 使用ドキュメント
├── main.tf         # プライマリ リソース
├── variables.tf    # 説明付きの型指定された入力
├── outputs.tf      # 出力値
├── versions.tf     # required_version + required_providers
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── module_test.tftest.hcl   # または Terratest 用 Go

変数契約: 常に description、常に明示的な type、複雑な制約には validation を使用、秘密には sensitive = true を使用、型なしの map(any) ではなく optional() と型指定のデフォルト (1.3+) を優先します。

出力契約: 常に description、機密出力をマーク、安定したサブセットを公開 (プロバイダー オブジェクト全体ではなく)。

モジュール リリース チェックリストと LLM 誤りチェックリストを含む完全な契約パターンについては、Module Patterns を参照してください。

CI/CD

パイプライン ステージ: validate → test → plan → apply (環境保護付き)。

コスト制御: PR 検証ではモック プロバイダーを使用、本番環境またはスケジュール済みでのみ実クラウド統合、テスト リソースにタグ付け、自動クリーンアップ。

ドリフト防止: ランタイムとプロバイダーをピン留め、.terraform.lock.hcl をコミット、プラン ステージからレビュー済みプラン成果物を適用 (適用ジョブ内で plan を再実行しない)、すべての apply パスでポリシー/セキュリティ ステージを実行。

GitHub Actions、GitLab CI、Atlantis テンプレートと LLM 誤りチェックリストについては、CI/CD Workflows を参照してください。

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

重要なチェック:

trivy config .
checkov -d .

しないこと： 変数またはファイルに秘密情報を保存する、デフォルト VPC を使用する、暗号化をスキップする、セキュリティ グループを 0.0.0.0/0 に開く、aws_security_group でインライン ingress/egress ブロックを使用する。

すること： AWS Secrets Manager / Parameter Store から秘密情報をソースする、または 1.11+ で write_only 引数を使用する、専用 VPC を作成する、保存時の暗号化と TLS を強制する、最小権限 SG を使用する、別の aws_vpc_security_group_{ingress,egress}_rule リソースを使用する (AWS プロバイダー v5+)。

変数を sensitive = true としてマークすると、表示のみが隠されます — 値はステート内に存在します。1.11+ では write_only / *_wo を使用するか、Terraform から完全に秘密の材料を除外して、ランタイム ルックアップを使用します。

trivy/checkov パイプライン、ステート ファイル強化、コンプライアンス マッピング、および LLM 誤りチェックリストについては、Security & Compliance を参照してください。

ステート管理

チームまたは本番環境ではローカル ステートを使用しないでください。 リモート バックエンドは自動ロック、暗号化、バージョン管理、監査ログ、および安全なコラボレーションを提供します。

最小実行可能なバックエンド (AWS S3、1.10+)

terraform {
  backend "s3" {
    bucket        = "my-terraform-state"
    key           = "prod/vpc/terraform.tfstate"
    region        = "us-east-1"
    encrypt       = true
    use_lockfile  = true   # ネイティブ S3 ロック、1.10+
  }
}

Terraform < 1.10 では、use_lockfile の代わりに dynamodb_table = "terraform-state-lock" を使用します。Azure Storage、GCS、および Terraform Cloud はすべて組み込みのロックを提供しています — 構文については「ステート管理」リファレンスを参照してください。

ステート構成

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

ステートを分割する時期: 異なるチーム、異なる更新ケーデンス、または >500 リソース。結合する時期: 密接に結合されたリソース、<100 リソース、同じライフサイクル。

ロック、マイグレーション、マルチチーム分離、災害復旧、および LLM 誤りチェックリストについては、State Management を参照してください。

バージョン管理

コンポーネント	戦略	例
Terraform ランタイム	マイナーをピン留め	required_version = "~> 1.9"
プロバイダー	メジャーをピン留め	version = "~> 5.0"
モジュール (本番)	正確にピン留め	version = "5.1.2"
モジュール (開発)	パッチを許可	version = "~> 5.1"

意図的に .terraform.lock.hcl をコミットします。プロバイダー/ランタイム アップグレードを機能変更とは別の PR に保ちます。制約構文とアップグレード ワークフローについては、Code Patterns: Version Management を参照してください。

モダン 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 エラー パターンを含む完全なテーブルについては、Code Patterns: Feature Guard Table を参照してください。

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

• Terraform 1.0-1.5 / OpenTofu 1.0-1.5: 統合には Terratest、静的分析 + プラン検証のみ (ネイティブ テストなし)。
• 1.6+: ネイティブ terraform test / tofu test が利用可能 — 簡単なユニット テストをマイグレート、複雑な統合には Terratest を保持。
• 1.7+: モック プロバイダーはテスト コストを削減 — ユニット テストではモック、最終統合では実行。
• 1.10+: S3 ネイティブ ロック ファイル (use_lockfile) は新しい構成の正しいデフォルト — DynamoDB ロックは不要になりました。
• 1.11+: write_only 引数により、秘密情報をステートから外します。
• Terraform vs OpenTofu: 両方がサポートされています。ライセンス、ガバナンス、機能デルタについては、Quick Reference: Terraform vs OpenTofu を参照してください。

リファレンス ファイル

段階的な開示 — ここでは必須事項、必要に応じて詳細:

• Testing Frameworks — 静的分析、ネイティブ テスト、Terratest、モック プロバイダー
• Module Patterns — 構造、変数/出力契約、terraform_remote_state ルール、リリース チェックリスト
• CI/CD Workflows — GitHub Actions、GitLab CI、Atlantis、コスト制御
• Security & Compliance — trivy/checkov、秘密処理、コンプライアンス マッピング
• State Management — バックエンド、ロック、マイグレーション、マルチチーム、復旧
• Code Patterns — ブロック順序、count/for_each 詳細、モダン機能、バージョン管理、ローカル
• Quick Reference — コマンド チート シート、フローチャート、トラブルシューティング

ライセンス

Apache License 2.0。完全な条項については LICENSE を参照してください。

Copyright © 2026 Anton Babenko