terraform-skill

Terraform Skill for Claude

先診斷再引導的 Terraform 與 OpenTofu 指南。核心檔案為工作流程；深度內容則依需求載入的參考檔案中。

回應合約

每個 Terraform/OpenTofu 回應必須包含：

1. 假設與版本下限 — 執行環境（terraform 或 tofu）、確切版本、Provider、狀態後端、執行路徑（本機/CI/Cloud/Atlantis）、環境重要性。若使用者未提供，需明確陳述假設。
2. 處理的風險類別 — 一或多項：身分變動、機密暴露、爆炸半徑、CI 漂移、合規缺口、狀態損毀、Provider 升級風險、測試盲點。
3. 選擇的補救措施與取捨 — 選擇了什麼、取捨了什麼、原因為何。
4. 驗證計畫 — 根據執行環境與風險等級量身訂做的確切指令（fmt -check、validate、plan -out、政策檢查）。
5. 回滾注意事項 — 針對任何破壞性或狀態變更：如何復原、應保留哪些證據。

絕不建議在未經審查的計畫產物與核准下直接對生產環境執行 apply。

絕不執行 terraform destroy（無論是目標式或完整式），除非先執行 terraform plan -destroy 並向使用者顯示所有將被刪除的資源 — 包括透過 locals 或 for_each 引入的隱含相依資源。在繼續前需取得明確確認。絕不在 destroy 中使用 -auto-approve。

工作流程

1. 擷取執行上下文 — 執行環境+版本、Provider、後端、執行路徑、環境重要性。
2. 診斷失敗模式 — 使用下方路由表。若意圖跨越多個類別，則載入對應的多個參考檔案。
3. 僅載入相符的參考檔案 — 不要預先載入任務不需要的深度內容。
4. 提出修復方案與風險控制 — 為何此方案能解決該模式、仍可能出錯的地方、防護措施（測試/核准/回滾）。
5. 產生產物 — HCL、遷移區塊（moved、import）、CI 變更、政策規則。
6. 在定案前進行驗證 — 根據風險等級執行量身訂做的驗證指令。
7. 在結尾輸出回應合約。

先診斷再產生

失敗類別	症狀	主要參考檔案
身分變動	重構後資源位址變動、count 索引變動、缺少 moved 區塊	程式碼模式：count vs for_each、程式碼模式：moved 區塊、程式碼模式：LLM 常見錯誤
機密暴露	機密出現在預設值、狀態、日誌、CI 產物中	安全性與合規、程式碼模式：write-only、狀態管理
爆炸半徑	堆疊過大、共用生產/非生產狀態、不安全的 apply	狀態管理、模組模式
Destroy 連鎖效應	目標式 destroy 刪除超出預期的資源；locals 引用目標資源導致所有 for_each 消費者成為隱含相依	回應合約：先執行 plan-destroy；狀態管理：安全 Destroy
CI 漂移	本機 plan ≠ CI plan、未經審查產物即 apply、未鎖定版本	CI/CD 工作流程、程式碼模式：版本管理
合規缺口	缺少政策階段、無核准模型、無證據保留	安全性與合規、CI/CD 工作流程
測試盲點	僅以 plan 驗證計算值、set 類型索引、mock/真實混淆	測試框架
狀態損毀/復原	鎖定卡住、後端遷移、漂移調和	狀態管理
Provider 升級風險	Provider 重大版本變更、未鎖定模組版本	程式碼模式：版本管理、模組模式
Provider 生命週期	移除 Provider 但狀態中仍有資源、孤立資源、使用 removed 區塊	狀態管理：Provider 移除
啟動/編排誤用	使用 null_resource + local-exec 進行啟動、remote-exec 執行設定腳本、provisioner stdout 在 CI 日誌中洩漏機密	程式碼模式：Provisioner 作為最後手段
導航/安全重新命名盲點	無法語義定位符號定義/引用、值符號重新命名以盲目文字取代、僅用 grep 重構遺漏引用、幻覺 rg 替代	程式碼智能
跨雲/Provider 對應	"Azure/GCP 中 X 的對應是什麼"、為每個雲端選擇後端/認證模型	狀態管理：跨雲對應

何時使用此技能

啟用時機： 建立或審查 Terraform/OpenTofu 設定或模組、設定或除錯測試、建構多環境部署、實作 IaC CI/CD、選擇模組模式或狀態組織、設定或遷移遠端狀態後端。

不適用於： Claude 已知的基本 HCL 語法問題、Provider API 參考（請連結至文件）、與 Terraform/OpenTofu 無關的雲端平台問題。

核心原則

模組層級

類型	使用時機	範圍
資源模組	單一邏輯群組的關聯資源	VPC + 子網路、SG + 規則
基礎設施模組	為特定目的組合多個資源模組	單一區域/帳戶內的多個資源模組
組合	完整基礎設施	跨越多個區域/帳戶

流程：資源 → 資源模組 → 基礎設施模組 → 組合。

目錄結構

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	免費
提交前驗證	靜態 + lint	validate、tflint、trivy、checkov	免費
Terraform 1.6+、簡單邏輯	原生測試框架	terraform test	免費-低
1.6 之前，或具備 Go 專業知識	整合測試	Terratest	低-中
安全性/合規重點	政策即程式碼	OPA、Sentinel	免費
成本敏感工作流程	Mock Provider（1.7+）	原生測試 + mock	免費
多雲、複雜	完整整合	Terratest + 真實基礎設施	中-高

原生測試規則（1.6+）

在撰寫測試程式碼前：透過 Terraform MCP 驗證資源 schema，使斷言針對真實屬性。

• command = plan — 快速，僅適用於輸入推導值
• command = apply — 計算值（ARN、產成名稱）與 set 類型巢狀區塊 必須使用
• Set 類型區塊無法以 [0] 索引 — 使用 for 表達式或透過 command = apply 具體化
• 常見 set 類型：S3 加密規則、生命週期轉換、IAM 政策陳述句

請參閱測試框架了解靜態分析管線、原生測試模式、Terratest 整合、Mock Provider 以及完整的 LLM 常見錯誤檢查清單。

Count vs For_Each — 快速規則

情境	使用	原因
布林條件（建立/不建立）	count = condition ? 1 : 0	可選單例切換
項目可能重新排序或移除	for_each = toset(list)	穩定的資源位址
依鍵值參考	for_each = map	具名存取
多個具名資源	for_each	更好的身分穩定性

絕不使用列表索引作為長期身分 — 移除中間元素會重新排列其後所有位址。如需決策矩陣、安全遷移手冊、moved 區塊模式以及已知的 plan 階段失敗案例，請參閱程式碼模式：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   # 或使用 Go 進行 Terratest

變數合約：一律包含 description、一律明確 type、對複雜約束使用 validation、對機密使用 sensitive = true、優先使用 optional() 搭配型別預設值（1.3+）而非無型別的 map(any)。

輸出合約：一律包含 description、標記敏感輸出、暴露穩定的子集（而非整個 Provider 物件）。

請參閱模組模式了解完整合約模式、模組發布檢查清單以及 LLM 常見錯誤檢查清單。

CI/CD

管線階段：validate → test → plan → apply（附環境保護）。

成本控制：在 PR 驗證中使用 Mock Provider、僅在 main 或排程時使用真實雲端整合、標記測試資源、自動清理。

漂移預防：鎖定執行環境與 Provider 版本、提交 .terraform.lock.hcl、在 apply 階段使用來自 plan 階段經審查的計畫產物（不要在 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 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   # 原生 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"
Provider	鎖定主要版本	version = "~> 5.0"
模組（生產）	鎖定確切版本	version = "5.1.2"
模組（開發）	允許修補版本	version = "~> 5.1"

有意識地提交 .terraform.lock.hcl。將 Provider/執行環境升級與功能變更分開在不同的 PR 中。請參閱程式碼模式：版本管理了解約束語法與升級工作流程。

現代 Terraform 功能（1.0+）

功能	最低版本	常見用途
try()	0.13+	安全後備，取代 element(concat())
nullable = false	1.1+	防止 null 靜默覆寫預設值
moved 區塊	1.1+	重構而不需 destroy/recreate
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 的狀態鎖定

在輸出功能前，請先驗證執行環境版本下限。請參閱程式碼模式：功能防護表取得完整表格及各功能的常見 LLM 錯誤模式。

執行環境特定指引

• 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 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 alias）	手動：findReferences -> 每個檔案重新 Read -> 編輯 -> validate	無重新命名提供者
重新命名資源/模組位址	moved 區塊 + plan 顯示 0 個 destroy	文字重新命名會強制 destroy/recreate
確切文字/已知名稱/.tfvars/非 HCL	rg + Read	無語義範圍

✅ 支援：goToDefinition、findReferences、documentSymbol、hover、workspaceSymbol。
❌ 不支援：goToImplementation、呼叫階層、重新命名提供者。請勿呼叫這些功能然後回報其缺失。

• ✅ 前置條件：本機 PATH 上有 terraform/tofu、已執行 terraform init；冷啟動可能需要重試一次。
• ✅ LSP 呼叫需位置錨點（file:line:character）— 先使用 rg 錨定，絕不單獨使用符號名稱。
• ❌ 在降級閘門通過前，不要聲稱「LSP 故障，改用 rg」；在第一行揭露任何工具替代。

深度內容：程式碼智能。

參考檔案

漸進式揭露 — 此處為重點，深度內容依需求載入：

• 測試框架 — 靜態分析、原生測試、Terratest、Mock Provider
• 模組模式 — 結構、變數/輸出合約、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