Terraform IaC skill for Claude Code

Infrastructure code is done when fmt, validate, and lint pass, the saved plan shows only the intended changes (no surprise destroys or replacements), state is remote and locked, and the same code applies identically in every environment through variables.

Ground rules

• Never run apply, destroy, state rm, state mv, import (CLI), or force-unlock without explicit user confirmation, and always apply a saved plan file that the user has seen.
• Read every -/+ (replace) and - (destroy) line in a plan before proceeding.
• Refactor with moved blocks, adopt with import blocks, detach with removed blocks — all reviewable in a plan, unlike state CLI commands.
• Commit .terraform.lock.hcl. Never commit .tfstate, .terraform/, or *.tfvars containing secrets.
• Pin Terraform/OpenTofu and provider versions; upgrade deliberately with init -upgrade.

Workflow

- [ ] 1. Inspect: versions, backend, workspaces/environments, current drift
- [ ] 2. Make the change in code (module, variables, outputs)
- [ ] 3. fmt, validate, lint, security scan
- [ ] 4. plan -out, then summarize the plan
- [ ] 5. Review destroys/replacements with the user
- [ ] 6. Apply the saved plan (after confirmation)
- [ ] 7. Re-plan: expect "No changes"

1. Inspect

terraform version                         # or: tofu version
cat versions.tf backend.tf 2>/dev/null
terraform init -input=false
terraform workspace show
terraform plan -refresh-only -input=false # drift only: what changed outside Terraform

2. Layout and module design

Default layout: one root module per environment, sharing local modules.

infra/
├── modules/
│   └── service/            # main.tf variables.tf outputs.tf versions.tf README.md
└── envs/
    ├── staging/            # backend.tf main.tf terraform.tfvars
    └── prod/

Choice	Use when
Directory per environment	Default. Different backends/accounts, clear blast radius, easy reviews
Workspaces	Identical short-lived copies (per-branch previews) on the same backend
Terragrunt / Terraform Stacks	Many accounts/regions with heavy repetition; team already uses it

Module rules:

• Inputs typed and validated; no provider blocks inside reusable modules.
• Outputs expose IDs/ARNs consumers need; nothing else.
• Use for_each over maps with stable keys, not count, for collections (removing an item from a count list shifts indexes and recreates everything after it).

# versions.tf
terraform {
  required_version = ">= 1.10"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 6.0" }
  }
}

# backend.tf — S3 with native lockfile (Terraform 1.10+; DynamoDB locking is deprecated)
terraform {
  backend "s3" {
    bucket       = "acme-tfstate-prod"
    key          = "services/orders/terraform.tfstate"
    region       = "eu-west-1"
    encrypt      = true
    use_lockfile = true
  }
}

# variables.tf
variable "instance_count" {
  type        = number
  description = "Number of worker instances"
  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    error_message = "instance_count must be between 1 and 20."
  }
}

Protect stateful resources:

resource "aws_db_instance" "main" {
  # ...
  deletion_protection = true
  lifecycle {
    prevent_destroy = true
    ignore_changes  = [password]   # only for attributes managed elsewhere
  }
}

3. Static checks

terraform fmt -check -recursive
terraform validate
tflint --recursive                 # provider-aware lint
trivy config .                     # or checkov -d . : misconfig scan

4. Plan and summarize

terraform plan -input=false -out=tfplan
terraform show -json tfplan > tfplan.json
python3 scripts/plan_summary.py tfplan.json       # bundled; exits 2 on destroy/replace

The script groups creates, updates, replaces, and deletes by address and prints why each replacement happens (replace_paths). Use it to drive step 5.

5. Review the plan

Plan shows	Ask
must be replaced on a database, volume, bucket, or LB	Which attribute forces it? Can it be changed in place or with create_before_destroy?
Destroy + create of resources you only renamed	Add a moved block
Updates you did not make	Drift: someone changed it in the console. Codify or revert
known after apply on IDs feeding for_each keys	Restructure; keys must be known at plan time
Changes to IAM policies	Read the diff line by line; least privilege still holds?
Sensitive values	Marked (sensitive value); confirm they are not also in outputs

Refactor and adopt without recreation

# Renamed or moved into a module
moved {
  from = aws_s3_bucket.logs
  to   = module.logging.aws_s3_bucket.this
}

# Adopt an existing resource (Terraform 1.5+, OpenTofu 1.5+)
import {
  to = aws_s3_bucket.assets
  id = "acme-assets-prod"
}

# Stop managing without destroying (Terraform 1.7+)
removed {
  from = aws_instance.legacy
  lifecycle { destroy = false }
}

Generate starter config for imports: terraform plan -generate-config-out=generated.tf, then clean the generated code into the real files.

6–7. Apply and confirm convergence

terraform apply tfplan            # only after the user approves this exact plan
terraform plan -detailed-exitcode # 0 = no changes, 2 = changes remain, 1 = error

A non-empty plan right after apply means a perpetual diff (provider normalization, ignore_changes needed, or a computed value in config). Fix it before moving on.

Secrets

• Pass secrets from a secret manager via data sources or, on Terraform 1.11+, write-only arguments / ephemeral resources so they never land in state.
• Assume state contains secrets: encrypt the backend, restrict access, never paste state into chats or tickets. OpenTofu also supports client-side state encryption.
• Mark outputs sensitive = true; this hides them from CLI output, not from state.

CI pattern

• PR: fmt -check, validate, tflint, plan -out, post the plan summary as a comment.
• Merge: apply the exact saved plan artifact from the PR job if still fresh, or re-plan and require a manual approval on the protected environment.
• Authenticate CI with OIDC to the cloud provider, never long-lived keys.
• Schedule plan -refresh-only -detailed-exitcode nightly to alert on drift.

Gotchas

• count = var.enabled ? 1 : 0 turns the address into res[0]; switching an existing resource to this pattern needs a moved block.
• Provider major upgrades (e.g. AWS v5 -> v6) change defaults and schemas; read the upgrade guide and plan in a non-prod environment first.
• terraform state rm followed by forgetting to re-import leaves orphaned cloud resources.
• depends_on on modules makes every data source inside wait until apply, producing known after apply everywhere. Use it sparingly.
• A stale lock after a crashed run: confirm no run is active before force-unlock <ID>.
• Workspaces share the backend config; a mistaken workspace select applies prod changes with staging variables. Print the workspace in every CI log.

Output

**Root module:** envs/prod (Terraform 1.13.x, aws ~> 6.0)
**Checks:** fmt OK, validate OK, tflint 0 issues, trivy 0 HIGH
**Plan:** 3 to add, 2 to change, 0 to replace, 0 to destroy
- + aws_sqs_queue.orders_dlq
- ~ aws_lambda_function.worker (memory_size 512 -> 1024)
**Drift found:** none
**Apply:** pending user approval of tfplan (sha256 1f3c...)