terraform-skill

面向 Claude 的 Terraform 技能

以诊断为先的 Terraform 和 OpenTofu 指导。核心文件是一套工作流；更深入的内容放在按需加载的参考资料中。

响应约定

每条 Terraform/OpenTofu 响应都必须包含：

1. 假设与最低版本要求 — 运行时（terraform 或 tofu）、确切版本、提供商、状态后端、执行路径（本地/CI/Cloud/Atlantis）、环境关键性。如果用户未提供这些信息，须明确说明假设。
2. 所应对的风险类别 — 以下一项或多项：身份变更、机密泄露、影响范围、CI 漂移、合规性缺口、状态损坏、提供商升级风险、测试盲区。
3. 所选修复方案与权衡 — 说明选择了什么、权衡了什么，以及原因。
4. 验证计划 — 根据运行时和风险等级定制的确切命令（fmt -check、validate、plan -out、策略检查）。
5. 回滚说明 — 对于任何破坏性或会修改状态的变更，说明如何撤销以及要保留哪些证据。

绝不要在没有经过审查的计划产物并获得批准的情况下，建议直接对生产环境执行 apply。

运行 terraform destroy（指定目标或完整销毁）之前，绝不要执行销毁操作；必须先运行 terraform plan -destroy，并向用户展示所有将被删除的资源，包括通过 locals 或 for_each 纳入的隐式依赖项。继续操作前，必须获得明确确认。销毁时绝不要使用 -auto-approve。

工作流

1. 收集执行上下文 — 运行时和版本、提供商、后端、执行路径、环境关键性。
2. 根据下方路由表诊断故障模式。如果意图涉及多个类别，请加载相应的多份参考资料。
3. 仅加载匹配的参考文件 — 不要预先加载任务用不到的深入内容。
4. 提出带风险控制的修复方案 — 说明方案如何应对相应模式、仍可能出现的问题，以及防护措施（测试/审批/回滚）。
5. 生成产物 — HCL、迁移块（moved、import）、CI 变更、策略规则。
6. 完成前进行验证 — 根据风险等级运行相应的验证命令。
7. 最后给出响应约定中的内容。

生成前先诊断

故障类别	症状	主要参考资料
标识 churn	重构后资源地址发生变化、count 索引 churn、缺少 moved 块	代码模式：count 与 for_each、代码模式：moved 块、代码模式：大模型常见错误
密钥泄露	密钥出现在默认值、状态、日志和 CI 工件中	安全与合规、代码模式：只写参数、状态管理
影响范围过大	栈过大、生产与非生产环境共用状态、不安全的 apply	状态管理、模块模式
级联销毁	定向销毁删除了超出预期的内容；引用了被定向资源的局部值会使所有 for_each 使用者隐式成为依赖项	响应约定：先执行 plan-destroy；状态管理：安全销毁
CI 漂移	本地 plan ≠ CI plan、未使用经过审核的工件就执行 apply、版本未固定	CI/CD 工作流、代码模式：版本
合规缺口	缺少策略阶段、没有审批模型、未保留证据	安全与合规、CI/CD 工作流
测试盲点	仅通过 plan 验证计算值、索引集合类型、混淆 mock 与真实对象	测试框架
状态损坏 / 恢复	锁定卡住、后端迁移、漂移协调	状态管理
Provider 升级风险	Provider 升级带来破坏性变更、模块未固定版本	代码模式：版本、模块模式
Provider 生命周期	状态中仍有资源时移除 Provider、资源孤立、使用 removed 块	状态管理：移除 Provider
引导 / 编排误用	使用 null_resource + local-exec 进行引导、使用 remote-exec 执行设置脚本、provisioner 的标准输出在 CI 日志中泄露密钥	代码模式：仅在最后手段使用 Provisioner
导航 / 安全重命名盲点	无法通过语义定位符号定义/引用、仅通过盲目替换文本来重命名值符号、仅用 grep 重构导致遗漏引用、臆造 rg 替代命令	代码智能
跨云 / Provider 映射	“X 在 Azure/GCP 中的对应方案是什么”、为各云选择后端/身份验证模型	状态管理：跨云等效方案

何时使用此技能

适用于： 创建或审查 Terraform/OpenTofu 配置或模块、设置或调试测试、构建多环境部署、实现 IaC CI/CD、选择模块模式或状态组织方式、配置或迁移远程状态后端。

不适用于： Claude 已掌握的基础 HCL 语法问题、Provider API 参考（请链接文档）、与 Terraform/OpenTofu 无关的云平台问题。

核心原则

模块层级

类型	适用场景	范围
资源模块	一组逻辑上相互关联的资源	VPC + 子网、SG + 规则
基础设施模块	为特定用途组合多个资源模块	一个区域/账户中的多个资源模块
组合	完整的基础设施	涉及多个区域/账户

流程：资源 → 资源模块 → 基础设施模块 → 组合。

目录布局

environments/   # prod/ staging/ dev/  — per-env configurations
modules/        # networking/ compute/ data/ — reusable modules
examples/       # minimal/ complete/ — docs + integration fixtures

将 环境 与 模块 分开。使用 examples/ 同时作为文档和测试夹具。保持模块精简，并专注于单一职责。

请参阅 模块模式，了解架构原则、命名约定以及变量/输出契约。

命名约定（摘要）

• 使用描述性资源名称（例如 aws_instance.web_server，而不是 aws_instance.main）
• 仅将 this 用于真正的单例资源
• 在变量名前加上上下文前缀（例如 vpc_cidr_block，而不是 cidr）
• 标准文件：main.tf、variables.tf、outputs.tf、versions.tf

示例请参阅 模块模式：变量命名 和 代码模式：块排序。

块排序（摘要）

资源块：先写 count/for_each → 参数 → tags → depends_on → lifecycle。 变量块：description → type → default → validation → nullable → sensitive。

完整规则和示例请参阅 代码模式：块排序与结构。

测试策略

决策矩阵：选择哪种测试方法？

情况	方法	工具	成本
快速语法检查	静态分析	validate、fmt	免费
提交前验证	静态分析 + lint	validate、tflint、trivy、checkov	免费
Terraform 1.6+，逻辑简单	原生测试框架	terraform test	免费到低
低于 1.6，或具备 Go 专业知识	集成测试	Terratest	低到中
侧重安全/合规	策略即代码	OPA、Sentinel	免费
成本敏感型工作流	模拟 Provider（1.7+）	原生测试 + 模拟	免费
多云、复杂场景	完整集成	Terratest + 真实基础设施	中到高

原生测试规则（1.6+）

编写测试代码前：通过 Terraform MCP 验证资源架构，确保断言针对真实属性。

• command = plan — 速度快，仅适用于由输入推导出的值
• command = apply — 计算值（ARN、生成的名称）和 set 类型嵌套块必需
• Set 类型的块无法通过 [0] 索引访问 — 请使用 for 表达式，或通过 command = apply 将其具体化
• 常见的 set 类型：S3 加密规则、生命周期转换、IAM 策略语句

静态分析流水线、原生测试模式、Terratest 集成、模拟 Provider 以及完整的 LLM 错误清单，请参阅 测试框架。

Count 与 For_Each — 快速规则

场景	使用	原因
布尔条件（创建/不创建）	count = condition ? 1 : 0	可选的单例开关
项目可能被重新排序或删除	for_each = toset(list)	资源地址稳定
按键引用	for_each = map	可按名称访问
多个具名资源	for_each	标识稳定性更佳

切勿使用列表索引作为长期标识 — 删除中间元素会导致其后所有地址重新排列。有关决策矩阵、安全迁移手册、moved 块模式以及已知的计划阶段失败情况，请参阅 代码模式：count 与 for_each。

用于依赖管理的 Locals

在 local 中使用 try()，优先选择条件资源的属性而非其父级属性，是一种专门但价值很高的模式——它无需显式使用 depends_on，即可确保正确的删除顺序。常见用法：VPC + 次级 CIDR 关联 + 子网。

完整模式和示例请参阅 代码模式：用于依赖管理的 Locals。

模块开发

标准布局：

my-module/
├── README.md       # Usage documentation
├── main.tf         # Primary resources
├── variables.tf    # Typed inputs with descriptions
├── outputs.tf      # Output values
├── versions.tf     # required_version + required_providers
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── module_test.tftest.hcl   # or Go for Terratest

变量契约：始终提供 description，始终显式指定 type，复杂约束使用 validation，机密信息使用 sensitive = true，优先使用带类型默认值的 optional()（1.3+），而非无类型的 map(any)。

输出契约：始终提供 description，将敏感输出标记为敏感，只公开稳定的子集（而非整个 provider 对象）。

完整的契约模式、模块发布检查清单和 LLM 错误检查清单，请参阅 模块模式。

CI/CD

流水线阶段：验证 → 测试 → 计划 → 应用（并启用环境保护）。

成本控制：PR 验证时使用模拟 provider，仅在 main 分支或定时任务中进行真实云集成；为测试资源添加标签并自动清理。

防止配置漂移：固定运行时和 provider 版本，提交 .terraform.lock.hcl，在应用阶段使用计划阶段生成的已审核计划制品（不要在应用作业中重新运行 plan），并确保每条应用路径都会经过策略/安全阶段。

GitHub Actions、GitLab CI 和 Atlantis 模板以及 LLM 错误检查清单，请参阅 CI/CD 工作流。

安全与合规

必要检查：

trivy config .
checkov -d .

**不要：**将机密信息存储在变量或 .tfvars 中；使用默认 VPC；跳过加密；将安全组开放给 0.0.0.0/0；在 aws_security_group 中使用内联 ingress/egress 块。

**应该：**从云机密管理器（AWS Secrets Manager / Azure Key Vault / GCP Secret Manager）获取机密信息，或在 1.11+ 中使用 write_only 参数；创建专用 VPC；强制启用静态加密和 TLS；遵循最小权限原则配置 SG；使用独立的 aws_vpc_security_group_{ingress,egress}_rule 资源（例如 AWS provider v5+）。

将变量标记为 sensitive = true 只会隐藏显示内容——其值仍然存储在状态中。请在 1.11+ 中使用 write_only / *_wo，或者通过运行时查找，完全避免将机密材料放入 Terraform。

trivy/checkov 流水线、状态文件加固、合规性映射和 LLM 错误检查清单，请参阅 安全与合规。

状态管理

**团队或生产环境中绝不要使用本地状态。**远程后端提供自动锁定、加密、版本控制、审计日志和安全协作功能。

选择远程后端

AWS 示例（Azure azurerm / GCP gcs / TF Cloud 语法请参阅 状态管理：选择远程后端）：

terraform {
  backend "s3" {
    bucket        = "my-terraform-state"
    key           = "prod/vpc/terraform.tfstate"
    region        = "us-east-1"
    encrypt       = true
    use_lockfile  = true   # Native S3 locking, 1.10+
  }
}

在 Terraform < 1.10 中，请使用 dynamodb_table = "terraform-state-lock"，而不是 use_lockfile。Azure Storage、GCS 和 Terraform Cloud 均提供内置锁定功能——语法请参阅状态管理参考文档。有关如何选择后端及其锁定模型，请参阅选择远程后端。

状态组织

模式	适用情况	示例路径
按环境划分	不同环境由不同团队管理	prod/terraform.tfstate、staging/...
按组件划分	生命周期相互独立	prod/vpc/、prod/eks/、prod/rds/
混合模式（推荐）	兼具两者优势	prod/networking/、prod/compute/、staging/networking/

在以下情况下拆分状态：由不同团队管理、更新周期不同，或资源超过 500 个。在以下情况下合并：资源紧密耦合、资源少于 100 个，且生命周期相同。

有关锁定、迁移、多团队隔离、灾难恢复和 LLM 错误检查清单，请参阅状态管理。

版本管理

组件	策略	示例
Terraform 运行时	固定次版本	required_version = "~> 1.9"
Providers	固定主版本	version = "~> 5.0"
Modules（生产环境）	固定精确版本	version = "5.1.2"
Modules（开发环境）	允许修订版本更新	version = "~> 5.1"

有意提交 .terraform.lock.hcl。将 Provider／运行时升级与功能变更放在不同的 PR 中。有关约束语法和升级工作流，请参阅代码模式：版本管理。

现代 Terraform 功能（1.0+）

功能	最低版本	常见用途
try()	0.13+	安全回退，替代 element(concat())
nullable = false	1.1+	防止 null 静默覆盖默认值
moved 块	1.1+	重构时无需销毁／重新创建资源
带默认值的 optional()	1.3+	类型化对象属性
import 块	1.5+	声明式导入，可在 VCS 中审查
check 块	1.5+	运行时断言
原生 terraform test	1.6+	内置测试框架
Mock Provider	1.7+	零成本单元测试
removed 块	1.7+	声明式移除资源
Provider 定义的函数	1.8+	Provider 专属转换（要求 Provider 声明函数）
跨变量验证	1.9+	在 validation 块中引用其他 var.*
write_only 参数	1.11+	密钥不会存储在状态中
S3 原生锁文件	1.10+	无需 DynamoDB 即可锁定状态

使用某项功能前，请先确认运行时版本下限。完整表格以及各项功能常见的大模型错误模式，请参阅代码模式：功能版本守卫表。

运行时专项指南

• Terraform 1.0-1.5（OpenTofu 从 1.6 开始）：使用 Terratest 进行集成测试；仅使用静态分析和 plan 验证（无原生测试）。
• 1.6+：可使用原生 terraform test／tofu test——迁移简单的单元测试，复杂集成测试继续使用 Terratest。
• 1.7+：Mock Provider 可降低测试成本——单元测试使用 Mock，最终集成测试使用真实运行。
• 1.10+：S3 原生锁文件（use_lockfile）是新配置的正确默认选项——不再需要 DynamoDB 锁定。
• 1.11+：使用 write_only 参数处理密钥，确保凭据不会进入状态。
• Terraform 与 OpenTofu：两者均受支持。有关许可、治理和功能差异，请参阅快速参考：Terraform 与 OpenTofu。

代码智能（terraform-ls）

HCL 的语义导航。terraform-ls 是可选的；没有它时，下表中的每一项都会降级为明确说明的 rg + Read 回退方案。

这是一个独立的 terraform-ls 层，属于通用代码智能规范的一部分——直接应用下表中的各项。建议搭配使用：code-intelligence 插件（位于同一个 antonbabenko/agent-plugins marketplace）包含通用规范（位置锚定、降级门槛、说明格式、防虚假垫片），并提供 /code-intelligence:doctor 来检查就绪状态。如果已安装，请遵循其通用协议；即使未安装，此技能也完全自成一体。

目标	用法	权衡
查找定义 / 所有引用	terraform-ls goToDefinition / findReferences	需要先运行 init 并提供位置锚点
重命名值符号（var/local/output/provider 别名）	手动操作：findReferences -> 逐个文件重新 Read -> 编辑 -> validate	没有重命名提供程序
重命名资源 / 模块地址	使用 moved 块 + plan 显示 0 次销毁	文本重命名会强制销毁并重新创建
精确文本 / 已知名称 / .tfvars / 非 HCL	rg + Read	没有语义作用域

✅ 支持：goToDefinition、findReferences、documentSymbol、hover、workspaceSymbol。 ❌ 不支持：goToImplementation、调用层次结构、重命名提供程序。不要调用这些功能后再将其缺失报告为发现项。

• ✅ 前提条件：本地 terraform/tofu 位于 PATH 中，且已运行 terraform init；冷启动时可能需要重试一次。
• ✅ LSP 调用必须锚定位置（file:line:character）——先用 rg 找到锚点，绝不能只使用符号名称。
• ❌ 在通过降级门槛之前，不要声称“LSP 已损坏，改用 rg”；如替换了工具，须在第一行说明。

详细说明：代码智能。

参考文件

渐进式披露——此处介绍要点，按需深入了解：

• 测试框架 — 静态分析、原生测试、Terratest、模拟提供程序
• 模块模式 — 结构、变量/输出契约、terraform_remote_state 规则、发布检查清单
• CI/CD 工作流 — GitHub Actions、GitLab CI、Atlantis、成本控制
• 安全与合规 — trivy/checkov、密钥处理、合规映射
• 状态管理 — 后端、锁定、迁移、多团队、恢复
• 代码模式 — 块排序、count/for_each 深入解析、现代功能、版本管理、locals
• 代码智能 - terraform-ls 功能、位置锚定调用、手动重命名、降级门槛
• 快速参考 — 命令速查表、流程图、故障排除

许可证

Apache License 2.0。完整条款请参阅 LICENSE。

版权所有 © 2026 Anton Babenko