Terraform — Claude Code rules

Follow the official HashiCorp Terraform Style Guide. These conventions keep configuration readable, reviewable, and safe to apply.

Formatting

• Run terraform fmt and terraform validate before committing. Use terraform fmt -recursive to format subdirectories.
• Indent two spaces per nesting level.
• Align the = signs when consecutive single-line arguments sit at the same level.
• Use # for both single- and multi-line comments. Avoid // and /* */.
• Separate top-level blocks with one blank line; group logically related arguments with blank lines.

File & module structure

• Use the standard file layout so maintainers know where to look:
  • terraform.tf — terraform block with required_version and required_providers.
  • providers.tf — provider blocks (default provider first).
  • backend.tf — backend configuration.
  • main.tf — resources and data sources.
  • variables.tf — variable blocks, alphabetical.
  • outputs.tf — output blocks, alphabetical.
  • locals.tf — local values referenced across files.
• For larger codebases, split main.tf by logical group (network.tf, compute.tf, storage.tf).
• Create a module only when it introduces a new abstraction. Don't write thin wrappers around a single resource type. Keep the module tree flat and prefer composition over deep nesting.
• Name module repositories terraform-<PROVIDER>-<NAME>. Store local modules in ./modules/<name>.

Naming

• Use descriptive nouns with underscores: snake_case.
• Do NOT include the resource type in the resource name — the address already has it: resource "aws_instance" "web_api", not "web_api_instance".
• Order resources for readability. Define data sources before the resources that reference them.

Variables & outputs

• Define a type and description for every variable and output.
• Give optional variables a reasonable default.
• Mark passwords and private keys sensitive = true (note: still stored plaintext in state).
• Use input variable validation only for uniquely restrictive requirements.
• Don't hardcode values that vary by environment — use variables or locals.
• Avoid overusing variables and local values; use locals sparingly.

Resource arguments

• Recommended argument order inside a resource:
  1. count / for_each meta-argument
  2. non-block parameters
  3. block parameters
  4. lifecycle block (if needed)
  5. depends_on (if needed)
• Use count for near-identical resources; use for_each when values can't be derived from an integer. Use both in moderation and comment non-obvious effects.

Versions & dependencies

• Set required_version in the terraform block.
• Pin providers in required_providers with explicit version constraints.
• Pin modules to specific major and minor versions.
• Commit the .terraform.lock.hcl dependency lock file.

Don't

• Don't commit *.tfstate / *.tfstate.*, .terraform/, .terraform.tfstate.lock.info, saved plan files, or *.tfvars with secrets.
• Don't store secrets in code — use env vars, Vault, or your CI secret store.
• Don't include the resource type in resource/output names.
• Don't use // or /* */ comments.