Terraform Skill for Claude

Comprehensive Terraform and OpenTofu guidance covering testing, modules, CI/CD, and production patterns. Based on terraform-best-practices.com and enterprise experience.

When to Use This Skill

Activate this skill when:

• - Creating new Terraform or OpenTofu configurations or modules
• Setting up testing infrastructure for IaC code
• Deciding between testing approaches (validate, plan, frameworks)
• Structuring multi-environment deployments
• Implementing CI/CD for infrastructure-as-code
• Reviewing or refactoring existing Terraform/OpenTofu projects
• Choosing between module patterns or state management approaches

Don't use this skill for:

• - Basic Terraform/OpenTofu syntax questions (Claude knows this)
• Provider-specific API reference (link to docs instead)
• Cloud platform questions unrelated to Terraform/OpenTofu

Core Principles

1. Code Structure Philosophy

Module Hierarchy:

Type	When to Use	Scope
Resource Module	Single logical group of connected resources	VPC + subnets, Security group + rules
Infrastructure Module

Collection of resource modules for a purpose | Multiple resource modules in one region/account |
| Composition | Complete infrastructure | Spans multiple regions/accounts |

Hierarchy: Resource → Resource Module → Infrastructure Module → Composition

Directory Structure:
CODEBLOCK0

Key principle from terraform-best-practices.com:

• - Separate environments (prod, staging) from modules (reusable components)
• Use examples/ as both documentation and integration test fixtures
• Keep modules small and focused (single responsibility)

For detailed module architecture, see: Code Patterns: Module Types & Hierarchy

2. Naming Conventions

Resources:
CODEBLOCK1

Singleton Resources:

Use "this" when your module creates only one resource of that type:

✅ DO:
CODEBLOCK2

❌ DON'T use "this" for multiple resources:
CODEBLOCK3

Use descriptive names when creating multiple resources of the same type.

Variables:
CODEBLOCK4

Files:

• - main.tf - Primary resources
• INLINECODE2 - Input variables
• INLINECODE3 - Output values
• INLINECODE4 - Provider versions
• INLINECODE5 - Data sources (optional)

Testing Strategy Framework

Decision Matrix: Which Testing Approach?

Your Situation	Recommended Approach	Tools	Cost
Quick syntax check	Static analysis	INLINECODE6, INLINECODE7	Free
Pre-commit validation

Static + lint | validate, tflint, trivy, checkov | Free | | Terraform 1.6+, simple logic | Native test framework | Built-in terraform test | Free-Low | | Pre-1.6, or Go expertise | Integration testing | Terratest | Low-Med | | Security/compliance focus | Policy as code | OPA, Sentinel | Free | | Cost-sensitive workflow | Mock providers (1.7+) | Native tests + mocking | Free | | Multi-cloud, complex | Full integration | Terratest + real infra | Med-High |

Testing Pyramid for Infrastructure

CODEBLOCK5

Native Test Best Practices (1.6+)

Before generating test code:

1. 1. Validate schemas with Terraform MCP:

CODEBLOCK6

1. 2. Choose correct command mode:

- command = plan - Fast, for input validation - command = apply - Required for computed values and set-type blocks

1. 3. Handle set-type blocks correctly:

- Cannot index with [0] - Use for expressions to iterate - Or use command = apply to materialize

Common patterns:

• - S3 encryption rules: set (use for expressions)
• Lifecycle transitions: set (use for expressions)
• IAM policy statements: set (use for expressions)

For detailed testing guides, see:

• - Testing Frameworks Guide - Deep dive into static analysis, native tests, and Terratest
• Quick Reference - Decision flowchart and command cheat sheet

Code Structure Standards

Resource Block Ordering

Strict ordering for consistency:

1. 1. count or for_each FIRST (blank line after)
2. Other arguments
3. INLINECODE20 as last real argument
4. INLINECODE21 after tags (if needed)
5. INLINECODE22 at the very end (if needed)

CODEBLOCK7

Variable Block Ordering

1. 1. description (ALWAYS required)
2. INLINECODE24
3. INLINECODE25
4. INLINECODE26
5. INLINECODE27 (when setting to false)

CODEBLOCK8

For complete structure guidelines, see: Code Patterns: Block Ordering & Structure

Count vs For_Each: When to Use Each

Quick Decision Guide

Scenario	Use	Why
Boolean condition (create or don't)	INLINECODE28	Simple on/off toggle
Simple numeric replication

count = 3 | Fixed number of identical resources | | Items may be reordered/removed | for_each = toset(list) | Stable resource addresses | | Reference by key | for_each = map | Named access to resources | | Multiple named resources | for_each | Better maintainability |

Common Patterns

Boolean conditions:
CODEBLOCK9

Stable addressing with for_each:
CODEBLOCK10

For migration guides and detailed examples, see: Code Patterns: Count vs For_Each

Locals for Dependency Management

Use locals to ensure correct resource deletion order:

CODEBLOCK11

Why this matters:

• - Prevents deletion errors when destroying infrastructure
• Ensures correct dependency order without explicit INLINECODE33
• Particularly useful for VPC configurations with secondary CIDR blocks

For detailed examples, see: Code Patterns: Locals for Dependency Management

Module Development

Standard Module Structure

CODEBLOCK12

Best Practices Summary

Variables:

• - ✅ Always include INLINECODE34
• ✅ Use explicit type constraints
• ✅ Provide sensible default values where appropriate
• ✅ Add validation blocks for complex constraints
• ✅ Use sensitive = true for secrets

Outputs:

• - ✅ Always include INLINECODE39
• ✅ Mark sensitive outputs with INLINECODE40
• ✅ Consider returning objects for related values
• ✅ Document what consumers should do with each output

For detailed module patterns, see:

• - Module Patterns Guide - Variable best practices, output design, ✅ DO vs ❌ DON'T patterns
• Quick Reference - Resource naming, variable naming, file organization

CI/CD Integration

Recommended Workflow Stages

1. 1. Validate - Format check + syntax validation + linting
2. Test - Run automated tests (native or Terratest)
3. Plan - Generate and review execution plan
4. Apply - Execute changes (with approvals for production)

Cost Optimization Strategy

1. 1. Use mocking for PR validation (free)
2. Run integration tests only on main branch (controlled cost)
3. Implement auto-cleanup (prevent orphaned resources)
4. Tag all test resources (track spending)

For complete CI/CD templates, see:

• - CI/CD Workflows Guide - GitHub Actions, GitLab CI, Atlantis integration, cost optimization
• Quick Reference - Common CI/CD issues and solutions

Security & Compliance

Essential Security Checks

CODEBLOCK13

Common Issues to Avoid

❌ Don't:

• - Store secrets in variables
• Use default VPC
• Skip encryption
• Open security groups to 0.0.0.0/0

✅ Do:

• - Use AWS Secrets Manager / Parameter Store
• Create dedicated VPCs
• Enable encryption at rest
• Use least-privilege security groups

For detailed security guidance, see:

• - Security & Compliance Guide - Trivy/Checkov integration, secrets management, state file security, compliance testing

Version Management

Version Constraint Syntax

CODEBLOCK14

Strategy by Component

Component	Strategy	Example
Terraform	Pin minor version	INLINECODE41
Providers

Pin major version | version = "~> 5.0" | | Modules (prod) | Pin exact version | version = "5.1.2" | | Modules (dev) | Allow patch updates | version = "~> 5.1" |

Update Workflow

CODEBLOCK15

For detailed version management, see: Code Patterns: Version Management

Modern Terraform Features (1.0+)

Feature Availability by Version

Feature	Version	Use Case
INLINECODE45 function	0.13+	Safe fallbacks, replaces INLINECODE46
INLINECODE47

1.1+ | Prevent null values in variables | | moved blocks | 1.1+ | Refactor without destroy/recreate | | optional() with defaults | 1.3+ | Optional object attributes | | Native testing | 1.6+ | Built-in test framework | | Mock providers | 1.7+ | Cost-free unit testing | | Provider functions | 1.8+ | Provider-specific data transformation | | Cross-variable validation | 1.9+ | Validate relationships between variables | | Write-only arguments | 1.11+ | Secrets never stored in state |

Quick Examples

CODEBLOCK16

For complete patterns and examples, see: Code Patterns: Modern Terraform Features

Version-Specific Guidance

Terraform 1.0-1.5

• - Use Terratest for testing
• No native testing framework available
• Focus on static analysis and plan validation

Terraform 1.6+ / OpenTofu 1.6+

• - New: Native terraform test / tofu test command
• Consider migrating from external frameworks for simple tests
• Keep Terratest only for complex integration tests

Terraform 1.7+ / OpenTofu 1.7+

• - New: Mock providers for unit testing
• Reduce cost by mocking external dependencies
• Use real integration tests for final validation

Terraform vs OpenTofu

Both are fully supported by this skill. For licensing, governance, and feature comparison, see Quick Reference: Terraform vs OpenTofu.

Detailed Guides

This skill uses progressive disclosure - essential information is in this main file, detailed guides are available when needed:

📚 Reference Files:

• - Testing Frameworks - In-depth guide to static analysis, native tests, and Terratest
• Module Patterns - Module structure, variable/output best practices, ✅ DO vs ❌ DON'T patterns
• CI/CD Workflows - GitHub Actions, GitLab CI templates, cost optimization, automated cleanup
• Security & Compliance - Trivy/Checkov integration, secrets management, compliance testing
• Quick Reference - Command cheat sheets, decision flowcharts, troubleshooting guide

How to use: When you need detailed information on a topic, reference the appropriate guide. Claude will load it on demand to provide comprehensive guidance.

License

This skill is licensed under the Apache License 2.0. See the LICENSE file for full terms.

Copyright © 2026 Anton Babenko