terraform-skill

Terraform Skill for Claude

面向 Terraform 和 OpenTofu 的优先诊断指导。核心文件是一个工作流；深度内容按需加载在参考资料中。

响应契约

每个 Terraform/OpenTofu 响应必须包含：

1. 假设与版本下限 — 运行时（terraform 或 tofu）、确切版本、提供商、状态后端、执行路径（本地/CI/Cloud/Atlantis）、环境关键性。如果用户未提供，则明确陈述假设。
2. 涉及的风险类别 — 一个或多个：身份变更、密钥泄露、爆炸半径、CI 漂移、合规缺口、状态损坏、提供商升级风险、测试盲区。
3. 选择的修复方案与权衡 — 选择了什么、放弃了什么、为什么。
4. 验证计划 — 针对运行时和风险等级定制的确切命令（fmt -check、validate、plan -out、策略检查）。
5. 回滚说明 — 对于任何破坏性或状态变更操作：如何撤销、保留哪些证据。

切勿在未审查计划产物和批准的情况下直接推荐生产环境 apply。

切勿在未先运行 terraform plan -destroy 并向用户展示所有将被删除的资源（包括通过 locals 或 for_each 拉入的隐式依赖项）之前运行 terraform destroy（定向或全量）。在继续之前获得明确确认。切勿在销毁操作中使用 -auto-approve。

工作流

1. 捕获执行上下文 — 运行时+版本、提供商、后端、执行路径、环境关键性。
2. 诊断故障模式 — 使用下面的路由表。如果意图跨越多个类别，则加载两个参考资料。
3. 仅加载匹配的参考文件 — 不要预加载任务不需要的深度内容。
4. 提出带有风险控制的修复方案 — 为什么这能解决该模式、仍可能出什么问题、防护措施（测试/审批/回滚）。
5. 生成产物 — HCL、迁移块（moved、import）、CI 变更、策略规则。
6. 最终确定前进行验证 — 运行针对风险等级定制的验证命令。
7. 在最后输出响应契约。

先诊断再生成

故障类别	症状	主要参考资料
身份变更	重构后资源地址变化、count 索引变更、缺少 moved 块	代码模式：count vs for_each、代码模式：moved 块、代码模式：LLM 错误
密钥泄露	默认值、状态、日志、CI 产物中的密钥	安全与合规、代码模式：write-only、状态管理
爆炸半径	过大的堆栈、共享的生产/非生产状态、不安全的 apply	状态管理、模块模式
销毁级联	定向销毁删除的资源超出预期；引用定向资源的 locals 使所有 for_each 消费者成为隐式依赖项	响应契约：先 plan-destroy；状态管理：安全销毁
CI 漂移	本地计划 ≠ CI 计划、未审查产物即 apply、未固定版本	CI/CD 工作流、代码模式：版本管理
合规缺口	缺少策略阶段、无审批模型、无证据保留	安全与合规、CI/CD 工作流
测试盲区	仅计划验证计算值、集合类型索引、模拟/真实混淆	测试框架
状态损坏/恢复	锁卡住、后端迁移、漂移协调	状态管理
提供商升级风险	破坏性提供商版本升级、未固定模块	代码模式：版本管理、模块模式
提供商生命周期	移除状态中仍有资源的提供商、孤立资源、removed 块使用	状态管理：提供商移除
引导/编排误用	使用 null_resource + local-exec 进行引导、remote-exec 运行设置脚本、provisioner stdout 在 CI 日志中泄露密钥	代码模式：provisioner 作为最后手段
导航/安全重命名盲区	无法语义定位符号定义/引用、值符号重命名作为盲文本替换、仅 grep 重构遗漏引用、幻觉 rg 垫片	代码智能
跨云/提供商映射	“X 的 Azure/GCP 等价物是什么”、为每个云选择后端/认证模型	状态管理：跨云等价物

何时使用此技能

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

不用于： Claude 已掌握的基本 HCL 语法问题、提供商 API 参考（链接到文档）、与 Terraform/OpenTofu 无关的云平台问题。

核心原则

模块层次结构

类型	使用时机	范围
资源模块	单一逻辑组的连接资源	VPC + 子网、安全组 + 规则
基础设施模块	为某一目的收集的资源模块	一个区域/账户中的多个资源模块
组合	完整基础设施	跨多个区域/账户

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

目录布局

environments/   # prod/ staging/ dev/  — 按环境配置
modules/        # networking/ compute/ data/ — 可重用模块
examples/       # minimal/ complete/ — 文档 + 集成测试夹具

将环境与模块分开。使用 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	免费
提交前验证	静态 + 代码检查	validate、tflint、trivy、checkov	免费
Terraform 1.6+，简单逻辑	原生测试框架	terraform test	免费-低
1.6 之前，或 Go 专长	集成测试	Terratest	低-中
安全/合规重点	策略即代码	OPA、Sentinel	免费
成本敏感的工作流	模拟提供商（1.7+）	原生测试 + 模拟	免费
多云、复杂	完整集成	Terratest + 真实基础设施	中-高

原生测试规则（1.6+）

在编写测试代码之前：通过 Terraform MCP 验证资源模式，以便断言针对真实属性。

• command = plan — 快速，仅用于输入派生值
• command = apply — 对于计算值（ARN、生成名称）和集合类型嵌套块是必需的
• 集合类型块不能使用 [0] 索引 — 使用 for 表达式或通过 command = apply 实现
• 常见集合类型：S3 加密规则、生命周期转换、IAM 策略语句

参见测试框架了解静态分析管道、原生测试模式、Terratest 集成、模拟提供商以及完整的 LLM 错误检查清单。

Count vs For_Each — 快速规则

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

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

用于依赖管理的 Locals

在 local 中使用 try() 来优先选择条件资源的属性而不是其父级，这是一种专门但高价值的模式——它强制正确的删除顺序，而无需显式的 depends_on。常见用途：VPC + 辅助 CIDR 关联 + 子网。

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

模块开发

标准布局：

my-module/
├── README.md       # 使用文档
├── main.tf         # 主要资源
├── variables.tf    # 带描述的类型化输入
├── outputs.tf      # 输出值
├── versions.tf     # required_version + required_providers
├── examples/
│   ├── minimal/
│   └── complete/
└── tests/
    └── module_test.tftest.hcl   # 或用于 Terratest 的 Go

变量契约：始终有 description、始终显式 type、对复杂约束使用 validation、对密钥使用 sensitive = true、优先使用带类型默认值的 optional()（1.3+）而不是无类型的 map(any)。

输出契约：始终有 description、标记敏感输出、暴露稳定子集（而不是整个提供商对象）。

参见模块模式获取完整契约模式、模块发布检查清单和 LLM 错误检查清单。

CI/CD

管道阶段：validate → test → plan → apply（带环境保护）。

成本控制：PR 验证使用模拟提供商，仅在 main 或定时任务上使用真实云集成，标记测试资源，自动清理。

漂移预防：固定运行时和提供商、提交 .terraform.lock.hcl、在 apply 阶段应用审查过的计划产物（不要在 apply 作业中重新运行 plan）、在通往 apply 的每条路径上运行策略/安全阶段。

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

安全与合规

基本检查：

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、最小权限安全组、使用单独的 aws_vpc_security_group_{ingress,egress}_rule 资源（例如 AWS 提供商 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   # 原生 S3 锁定，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"
提供商	固定主版本	version = "~> 5.0"
模块（生产）	固定确切版本	version = "5.1.2"
模块（开发）	允许补丁版本	version = "~> 5.1"

有意提交 .terraform.lock.hcl。将提供商/运行时升级放在与功能变更不同的 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+	内置测试框架
模拟提供商	1.7+	零成本单元测试
removed 块	1.7+	声明式资源移除
提供商定义函数	1.8+	提供商特定转换（需要提供商声明函数）
跨变量验证	1.9+	在 validation 块中引用其他 var.*
write_only 参数	1.11+	密钥从不存储在状态中
S3 原生锁文件	1.10+	无需 DynamoDB 的状态锁定

在输出特性之前，验证运行时下限。参见代码模式：特性防护表获取完整表格以及每个特性的常见 LLM 错误模式。

运行时特定指导

• Terraform 1.0-1.5（OpenTofu 从 1.6 开始）：使用 Terratest 进行集成测试，仅静态分析和计划验证（无原生测试）。
• 1.6+：原生 terraform test / tofu test 可用——迁移简单单元测试，保留 Terratest 用于复杂集成。
• 1.7+：模拟提供商降低测试成本——单元测试使用模拟，最终集成使用真实运行。
• 1.10+：S3 原生锁文件（use_lockfile）是新配置的正确默认值——不再需要 DynamoDB 锁定。
• 1.11+：用于密钥处理的 write_only 参数使凭据不进入状态。
• Terraform vs OpenTofu：两者都支持。有关许可、治理和特性差异，请参见快速参考：Terraform vs OpenTofu。

代码智能（terraform-ls）

HCL 的语义导航。terraform-ls 是可选的；没有它，下面的每一行都会降级为公开的 rg + Read 回退。

自包含的 terraform-ls 层属于通用代码智能学科——直接应用下面的行。推荐伴侣：code-intelligence 插件（同一 antonbabenko/agent-plugins 市场）承载通用学科（位置锚定、降级门、公开格式、反幻觉垫片）并提供 /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