Terraform最佳实践指南：37条规则优化基础设施即代码，提升安全与性能

terraform-best-practices by terramate-io/agent-skills

77 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/terramate-io/agent-skills --skill terraform-best-practices

云服务代码规范开发运维

🇨🇳中文介绍

Terraform 最佳实践

由 Terramate 维护的 Terraform 和基础设施即代码综合优化指南。包含 10 个类别共 37 条规则，按影响优先级排序，以指导自动化重构和代码生成。

何时应用

在以下情况下参考这些指南：

编写新的 Terraform 模块或配置时
实施基础设施模式（AWS、GCP、Azure 等）时
审查代码以发现安全和可靠性问题时
重构现有的 Terraform/OpenTofu 代码时
优化状态管理和性能时
设置团队工作流和治理时

按优先级划分的规则类别

优先级	类别	影响	前缀
1	组织与工作流	关键	`org-`
2	状态管理	关键	`state-`
3	安全最佳实践	关键

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 组织与工作流（关键）- 5 条规则

org-version-control - 所有 Terraform 代码都应进行版本控制
org-workspaces - 每个配置的每个环境使用一个工作区
org-access-control - 控制谁可以更改哪些基础设施
org-change-workflow - 基础设施变更的正式流程
org-audit-logging - 跟踪所有基础设施变更

2. 状态管理（关键）- 3 条规则

state-remote-backend - 始终使用远程状态后端
state-locking - 启用状态锁定以防止损坏
state-import - 将现有基础设施导入 Terraform

3. 安全最佳实践（关键）- 3 条规则

security-no-hardcoded-secrets - 切勿在代码中硬编码密钥
security-credentials - 使用适当的凭据管理（OIDC、Vault、IAM 角色）
security-iam-least-privilege - 遵循最小权限原则

4. 模块设计（高）- 5 条规则

module-single-responsibility - 每个逻辑组件对应一个模块
module-naming - 使用一致的命名约定（terraform--）
module-versioning - 对所有模块引用进行版本控制
module-composition - 像构建块一样组合模块
module-registry - 使用现有的社区/共享模块

5. 资源组织（中高）- 5 条规则

resource-naming - 使用一致的命名约定
resource-tagging - 标记所有资源以进行成本跟踪
resource-lifecycle - 使用生命周期块（prevent_destroy、ignore_changes）
resource-count-vs-foreach - 优先使用 for_each 而非 count
resource-immutable - 优先使用不可变基础设施模式

6. 变量与输出模式（中）- 6 条规则

variable-types - 使用特定类型、正向命名、可为空
variable-validation - 添加验证规则以进行早期错误检测
variable-sensitive - 将密钥标记为敏感，不设置默认值
variable-descriptions - 使用描述文档化所有变量
output-descriptions - 使用描述文档化所有输出
output-no-secrets - 切勿直接输出密钥

7. 语言最佳实践（中）- 5 条规则

language-no-heredoc-json - 使用 jsonencode/yamlencode，而非 HEREDOC
language-locals - 使用 locals 命名复杂表达式
language-linting - 运行 terraform fmt 和 tflint
language-data-sources - 使用数据源而非硬编码
language-dynamic-blocks - 使用动态块实现 DRY 代码

8. 提供者配置（中）- 1 条规则

provider-version-constraints - 固定提供者版本

9. 性能优化（低中）- 2 条规则

perf-parallelism - 为大型部署调整并行度
perf-debug - 启用调试日志以进行故障排除

10. 测试与验证（低）- 2 条规则

test-strategies - 测试金字塔（验证、lint、plan、集成）
test-policy-as-code - 实施策略检查（OPA、Checkov、tfsec）

阅读单个规则文件以获取详细解释和代码示例：

rules/state-remote-backend.md
rules/security-no-hardcoded-secrets.md
rules/module-versioning.md

每个规则文件包含：

简要说明其重要性
错误的代码示例及解释
正确的代码示例及解释
其他上下文和参考资料

获取包含所有扩展规则的完整指南：AGENTS.md

2026 年 2 月 1 日

🇺🇸English

Terraform Best Practices

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

Read individual rule files for detailed explanations and code examples:

rules/state-remote-backend.md
rules/security-no-hardcoded-secrets.md
rules/module-versioning.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Weekly Installs

Repository

terramate-io/ag…t-skills

GitHub Stars

First Seen

Feb 1, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

codex71

opencode71

gemini-cli70

github-copilot70

amp69

kimi-cli69