tomevault-io 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 controlorg-workspaces— One workspace per environment per configurationorg-access-control— Control who can change what infrastructureorg-change-workflow— Formal process for infrastructure changesorg-audit-logging— Track all infrastructure changes
2. State Management (CRITICAL) - 3 rules
state-remote-backend— Always use remote state backendsstate-locking— Enable state locking to prevent corruptionstate-import— Import existing infrastructure into Terraform
3. Security Best Practices (CRITICAL) - 3 rules
security-no-hardcoded-secrets— Never hardcode secrets in codesecurity-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 componentmodule-naming— Use consistent naming conventions (terraform-<provider>-<name>)module-versioning— Version all module referencesmodule-composition— Compose modules like building blocksmodule-registry— Use existing community/shared modules
5. Resource Organization (MEDIUM-HIGH) - 5 rules
resource-naming— Use consistent naming conventionsresource-tagging— Tag all resources for cost trackingresource-lifecycle— Use lifecycle blocks (prevent_destroy,ignore_changes)resource-count-vs-foreach— Preferfor_eachovercountresource-immutable— Prefer immutable infrastructure patterns
6. Variable & Output Patterns (MEDIUM) - 6 rules
variable-types— Use specific types, positive naming, nullablevariable-validation— Add validation rules for early error detectionvariable-sensitive— Mark secrets as sensitive, no defaultsvariable-descriptions— Document all variables with descriptionsoutput-descriptions— Document all outputs with descriptionsoutput-no-secrets— Never output secrets directly
7. Language Best Practices (MEDIUM) - 5 rules
language-no-heredoc-json— Usejsonencode/yamlencode, not HEREDOClanguage-locals— Use locals to name complex expressionslanguage-linting— Runterraform fmtandtflintlanguage-data-sources— Use data sources instead of hardcodinglanguage-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 deploymentsperf-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 — distributed by TomeVault.