Terraform Specialist Agent

Your focused agent for Terraform infrastructure automation, module design, state management, and provider configuration across cloud environments.

When to Use This Agent

Choose Terraform Specialist Agent when:

• Quick Terraform tasks: writing resource blocks, fixing syntax errors, debugging providers
• Module scaffolding and variable/output design
• State operations: import, move, remove, refresh
• Provider configuration and version constraint management
• Workspace strategies for multi-environment setups

Consider alternatives when:

• You need deep Azure-specific Terraform patterns — use a Terraform Azure agent
• You need comprehensive IaC review and policy — use a Terraform strategist agent
• You need cloud architecture without IaC focus — use a cloud architect agent

Quick Start

Copy
# .claude/agents/terraform-specialist.yml
name: Terraform Specialist Agent
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Terraform automation specialist for module design, state management, and provider configuration

Example invocation:

claude "Create a reusable Terraform module for an S3 bucket with versioning, encryption, lifecycle rules, and access logging"

Core Concepts

Terraform Workflow

Stage	Command	Purpose
Init	terraform init	Download providers, configure backend
Validate	terraform validate	Check syntax and internal consistency
Format	terraform fmt -recursive	Standardize formatting
Plan	terraform plan	Preview infrastructure changes
Apply	terraform apply	Execute the planned changes
Destroy	terraform destroy	Tear down managed infrastructure

Module Structure

modules/s3-bucket/
├── main.tf          # Resource definitions
├── variables.tf     # Input variables with types and defaults
├── outputs.tf       # Output values for consumers
├── versions.tf      # Terraform and provider version constraints
├── README.md        # Usage documentation
└── tests/
    └── main.tftest.hcl  # HCL-based tests

Configuration

Parameter	Description	Default
terraform_version	Terraform CLI version	>= 1.5.0
module_source	Module source (local, git, registry)	local
workspace_mode	Workspace strategy (single, per-env, per-team)	per-env
state_backend	State storage backend	s3
format_on_save	Auto-format Terraform files	true

Best Practices

1. Use type constraints and validation rules on every variable. Define type, description, and where applicable, validation blocks for all input variables. This catches misconfigurations at plan time rather than at apply time, saving debugging cycles.

2. Output everything downstream modules might need. When designing modules, output resource IDs, ARNs, endpoints, and names. It's much cheaper to output too much than to refactor the module later when a consumer needs an attribute you didn't expose.

3. Keep provider blocks in the root module only. Child modules should declare required_providers but never configure providers directly. This allows root modules to control authentication, regions, and aliases without conflicts.

4. Use workspaces for environment isolation carefully. Terraform workspaces are lightweight but share the same configuration. They work well for identical environments; for environments with structural differences, use separate directories with shared modules instead.

5. Write HCL tests for module contracts. The native terraform test command (HCL-based tests) validates that modules produce expected outputs given specific inputs. Test the contract — not the cloud API — for fast, reliable feedback.

Common Issues

Module changes break consumers without warning. Removing or renaming a variable or output is a breaking change for any configuration that references it. Follow semantic versioning — breaking changes get a major version bump, and add deprecation notices before removing interfaces.

State drift causes plan to show unexpected changes. When resources are modified outside Terraform (console clicks, CLI commands), the next plan shows changes Terraform didn't make. Run terraform plan -refresh-only to detect drift, then decide whether to update your config or import the changes.

Provider authentication works locally but fails in CI. Local auth uses your CLI credentials; CI environments need explicit configuration. Set provider credentials via environment variables, OIDC tokens, or instance roles — never hardcode credentials in provider blocks.