terraform

---
name: terraform
description: >-
  Opinionated guidance for writing clean, safe and maintainable Terraform (HCL) —
  code style, variables, modules, state, security, and AWS specifics. Use when
  writing, reviewing, refactoring, or planning any Terraform / HCL, especially
  for AWS (IAM, security groups, S3, VPC, Lambda, EKS), or when questions come up
  about module structure, remote state, tagging, or handling secrets in Terraform.
---

# Terraform Power Up

Opinionated guidance how to write nice and clean Terraform code that won't bite you in the
ass. Use at your own risk.

## How To Use This Skill

1. **Before any real work**, follow [refs/prelude.md](refs/prelude.md) — check versions,
   read current provider docs, weigh a few approaches, then plan.
2. **While writing code**, apply the conventions in [refs/code.md](refs/code.md).
3. **Consult the topic-specific reference** below for whatever you are touching.
4. **On every change involving access, secrets, or networking**, check
   [refs/security.md](refs/security.md).

Read the relevant reference file *before* writing code for that topic — the conventions are
specific and easy to get subtly wrong from memory.

## References

| Reference | Read it when you are… |
|-----------|------------------------|
| [refs/prelude.md](refs/prelude.md) | Starting any task — the homework to do first |
| [refs/code.md](refs/code.md) | Writing HCL: names, variables, outputs, locals, resources, loops, functions, formatting |
| [refs/modules.md](refs/modules.md) | Structuring code into reusable, instance, composite, or infrastructure modules |
| [refs/state.md](refs/state.md) | Configuring backends and remote state |
| [refs/security.md](refs/security.md) | Handling secrets, IAM, networking, or doing a security pass |
| [refs/aws.md](refs/aws.md) | Writing AWS-specific resources — IAM policies, security groups, tagging |
| [refs/opentofu.md](refs/opentofu.md) | Working on a project that uses OpenTofu (`tofu`) instead of Terraform |

## Core Principles

- **Clarity beats cleverness.** Long, obvious names over terse, mysterious ones.
- **Explicit over implicit.** Explicit tags, explicit types, explicit dependencies — no doubt
  about why a resource exists or who owns it.
- **One responsibility per module.** Small, single-purpose building blocks compose into
  layers; a module that does one thing is easy to reason about, test, and reuse.
- **Least privilege, always.** Start from zero access and add only what is proven necessary.
- **Secrets never touch state.** Prefer write-only attributes and ephemeral values.
- **Predictable plans.** Prefer `for_each` over `count`; keep blast radius small with
  well-scoped state.
- **Verify against the registry.** Argument names and defaults drift between provider
  versions; confirm the current docs before writing a resource.
- **Pin and lock every version.** Constrain Terraform, providers, and modules to known
  versions and commit the lock file, so an apply today matches an apply next month.