# Terraform Expert > Terraform and Infrastructure as Code optimization guidelines from Terramate. This skill should be used when writing, reviewing, or refactoring Terraform/OpenTofu code to ensure optimal patterns for security, maintainability, and reliability. Triggers on tasks involving Terraform modules, infrastructure provisioning, state management, or IaC optimization. Use when this capability is needed. - Skill: `tomevault-io/terraform-expert-4` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/terraform-expert-4` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/terraform-expert-4/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/terraform-expert-4 --- # Terraform Expert Comprehensive optimization guide for Terraform and Infrastructure as Code, maintained by Terramate. Contains 37 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation. ## When to Apply Reference these guidelines when: - Writing new Terraform modules or configurations - Implementing infrastructure patterns (AWS, GCP, Azure, etc.) - Reviewing code for security and reliability issues - Refactoring existing Terraform/OpenTofu code - Optimizing state management and performance - Setting up team workflows and governance ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Organization & Workflow | CRITICAL | `org-` | | 2 | State Management | CRITICAL | `state-` | | 3 | Security Best Practices | CRITICAL | `security-` | | 4 | Module Design | HIGH | `module-` | | 5 | Resource Organization | MEDIUM-HIGH | `resource-` | | 6 | Variable & Output Patterns | MEDIUM | `variable-`, `output-` | | 7 | Language Best Practices | MEDIUM | `language-` | | 8 | Provider Configuration | MEDIUM | `provider-` | | 9 | Performance Optimization | LOW-MEDIUM | `perf-` | | 10 | Testing & Validation | LOW | `test-` | ## Quick Reference ### 1. Organization & Workflow (CRITICAL) - 5 rules - `org-version-control` — All Terraform code in version control - `org-workspaces` — One workspace per environment per configuration - `org-access-control` — Control who can change what infrastructure - `org-change-workflow` — Formal process for infrastructure changes - `org-audit-logging` — Track all infrastructure changes ### 2. State Management (CRITICAL) - 3 rules - `state-remote-backend` — Always use remote state backends - `state-locking` — Enable state locking to prevent corruption - `state-import` — Import existing infrastructure into Terraform ### 3. Security Best Practices (CRITICAL) - 3 rules - `security-no-hardcoded-secrets` — Never hardcode secrets in code - `security-credentials` — Use proper credential management (OIDC, Vault, IAM roles) - `security-iam-least-privilege` — Follow least privilege principle ### 4. Module Design (HIGH) - 5 rules - `module-single-responsibility` — One module per logical component - `module-naming` — Use consistent naming conventions (`terraform--`) - `module-versioning` — Version all module references - `module-composition` — Compose modules like building blocks - `module-registry` — Use existing community/shared modules ### 5. Resource Organization (MEDIUM-HIGH) - 5 rules - `resource-naming` — Use consistent naming conventions - `resource-tagging` — Tag all resources for cost tracking - `resource-lifecycle` — Use lifecycle blocks (`prevent_destroy`, `ignore_changes`) - `resource-count-vs-foreach` — Prefer `for_each` over `count` - `resource-immutable` — Prefer immutable infrastructure patterns ### 6. Variable & Output Patterns (MEDIUM) - 6 rules - `variable-types` — Use specific types, positive naming, nullable - `variable-validation` — Add validation rules for early error detection - `variable-sensitive` — Mark secrets as sensitive, no defaults - `variable-descriptions` — Document all variables with descriptions - `output-descriptions` — Document all outputs with descriptions - `output-no-secrets` — Never output secrets directly ### 7. Language Best Practices (MEDIUM) - 5 rules - `language-no-heredoc-json` — Use `jsonencode`/`yamlencode`, not HEREDOC - `language-locals` — Use locals to name complex expressions - `language-linting` — Run `terraform fmt` and `tflint` - `language-data-sources` — Use data sources instead of hardcoding - `language-dynamic-blocks` — Use dynamic blocks for DRY code ### 8. Provider Configuration (MEDIUM) - 1 rule - `provider-version-constraints` — Pin provider versions ### 9. Performance Optimization (LOW-MEDIUM) - 2 rules - `perf-parallelism` — Tune parallelism for large deployments - `perf-debug` — Enable debug logging for troubleshooting ### 10. Testing & Validation (LOW) - 2 rules - `test-strategies` — Testing pyramid (validate, lint, plan, integration) - `test-policy-as-code` — Implement policy checks (OPA, Checkov, tfsec) ## How to Use Apply rules by ID when reviewing or generating code. Each rule ID maps to a specific pattern: - **CRITICAL rules** — always apply, block merges if violated - **HIGH rules** — apply by default, require explicit override to skip - **MEDIUM rules** — apply for new code; flag but don't block existing code - **LOW rules** — apply opportunistically during refactors Read individual rule files in `references/` for detailed explanations and code examples: ``` references/state-remote-backend.md references/security-no-hardcoded-secrets.md references/module-versioning.md ``` See `references/rule-index.md` for the full list of all 37 rules mapped to their local files. --- > Source: [rhysmcneill/agentic-ai-library](https://github.com/rhysmcneill/agentic-ai-library) — distributed by [TomeVault](https://tomevault.io).