Refactor Module

hashicorp/agent-skills/plugins/terraform/skills/refactor-module

作者 hashicorpf706481af9b8無授權條款890 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫4 天前更新

Transform monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

僅含說明Software DevelopmentDevOps & Cloud
AI 產生的概覽

引導將單體式 Terraform 組態重構為可重複使用、易於維護的模組，並涵蓋移轉與測試。

功能
此技能引導代理分析現有的 Terraform 組態，並將其重構為可重複使用的模組，包含明確的變數與輸出契約、封裝、文件與版本管理。它會產出模組設計、重構前後的程式碼轉換、使用 moved 區塊或 terraform state mv 的狀態移轉方案、模組文件，以及 Terraform 測試檔案。內容也涵蓋重構模式、常見陷阱，以及重構後計畫無差異等成功標準。
適用情境
當 Terraform 程式碼庫已變得龐大而需要拆分為模組時使用；也適合將重複的資源模式抽出為可重複使用的元件。它同樣適合規劃狀態移轉，以避免現有資源被重新建立。
執行需求
僅為說明性內容，不附帶指令碼。需要既有的 Terraform 組態、可用的 Terraform CLI（用於 terraform state list、terraform show -json、terraform plan、terraform state mv 等命令）、透過 terraform init 安裝提供者，以及了解模組登錄模式。

Skill: Refactor Module

Overview

This skill guides AI agents in transforming monolithic Terraform configurations into reusable, maintainable modules following HashiCorp's module design principles and community best practices.

Capability Statement

The agent will analyze existing Terraform code and systematically refactor it into well-structured modules with:

  • Clear interface contracts (variables and outputs)
  • Proper encapsulation and abstraction
  • Versioning and documentation
  • Testing frameworks
  • Migration path for existing state

Prerequisites

  • Existing Terraform configuration to refactor
  • Understanding of resource dependencies
  • Access to inspect current state via terraform state list / terraform show -json (for migration planning)
  • Knowledge of module registry patterns

Input Parameters

ParameterTypeRequiredDescription
source_directorystringYesPath to existing Terraform configuration
module_namestringYesName for the new module
abstraction_levelstringNo"simple", "intermediate", "advanced" (default: intermediate)
preserve_statebooleanYesWhether to maintain state compatibility
target_registrystringNoTarget module registry (local, private, public)

Execution Steps

1. Analysis Phase

markdown
**Identify Refactoring Candidates**- Group resources by logical function- Identify repeated patterns- Map resource dependencies- Detect configuration coupling- Analyze variable usage patterns
**Complexity Assessment**- Count resource relationships- Measure variable propagation depth- Identify cross-resource references- Evaluate state migration complexity

2. Module Design

Interface Design
hcl
# Define clear input contractvariable "network_config" {  description = "Network configuration parameters"  type = object({    cidr_block         = string    availability_zones = list(string)    enable_nat         = bool  })
  validation {    condition     = can(cidrhost(var.network_config.cidr_block, 0))    error_message = "CIDR block must be valid IPv4 CIDR."  }}
# Define output contractoutput "vpc_id" {  description = "ID of the created VPC"  value       = aws_vpc.main.id}
output "private_subnet_ids" {  description = "List of private subnet IDs"  value       = { for k, v in aws_subnet.private : k => v.id }}
Encapsulation Strategy
markdown
**What to Include in Module:**- Tightly coupled resources (VPC + subnets)- Resources with shared lifecycle- Configuration with clear boundaries
**What to Keep Separate:**- Cross-cutting concerns (monitoring, tagging)- Resources with different lifecycles- Provider-specific configurations

3. Code Transformation

Before: Monolithic Configuration
hcl
# main.tf (monolithic)resource "aws_vpc" "main" {  cidr_block = "10.0.0.0/16"  enable_dns_hostnames = true
  tags = {    Name = "production-vpc"    Environment = "prod"  }}
resource "aws_subnet" "public_1" {  vpc_id            = aws_vpc.main.id  cidr_block        = "10.0.1.0/24"  availability_zone = "us-east-1a"
  tags = {    Name = "public-subnet-1"    Type = "public"  }}
resource "aws_subnet" "public_2" {  vpc_id            = aws_vpc.main.id  cidr_block        = "10.0.2.0/24"  availability_zone = "us-east-1b"
  tags = {    Name = "public-subnet-2"    Type = "public"  }}
resource "aws_internet_gateway" "main" {  vpc_id = aws_vpc.main.id
  tags = {    Name = "production-igw"  }}
# ... more repetitive subnet and routing resources
After: Modular Structure
hcl
# modules/vpc/main.tflocals {  subnet_count = length(var.availability_zones)}
resource "aws_vpc" "main" {  cidr_block           = var.cidr_block  enable_dns_hostnames = var.enable_dns_hostnames  enable_dns_support   = var.enable_dns_support
  tags = merge(    var.tags,    {      Name = var.name    }  )}
resource "aws_subnet" "public" {  for_each = var.create_public_subnets ? toset(var.availability_zones) : []
  vpc_id                  = aws_vpc.main.id  cidr_block              = cidrsubnet(var.cidr_block, 8, index(var.availability_zones, each.value))  availability_zone       = each.value  map_public_ip_on_launch = true
  tags = merge(    var.tags,    {      Name = "${var.name}-public-${each.value}"      Type = "public"    }  )}
resource "aws_internet_gateway" "main" {  count  = var.create_public_subnets ? 1 : 0  vpc_id = aws_vpc.main.id
  tags = merge(    var.tags,    {      Name = "${var.name}-igw"    }  )}
# modules/vpc/variables.tfvariable "name" {  description = "Name prefix for all resources"  type        = string}
variable "cidr_block" {  description = "CIDR block for the VPC"  type        = string
  validation {    condition     = can(cidrhost(var.cidr_block, 0))    error_message = "Must be a valid IPv4 CIDR block."  }}
variable "availability_zones" {  description = "List of availability zones"  type        = list(string)}
variable "create_public_subnets" {  description = "Whether to create public subnets"  type        = bool  default     = true}
variable "enable_dns_hostnames" {  description = "Enable DNS hostnames in the VPC"  type        = bool  default     = true}
variable "enable_dns_support" {  description = "Enable DNS support in the VPC"  type        = bool  default     = true}
variable "tags" {  description = "Tags to apply to all resources"  type        = map(string)  default     = {}}
# modules/vpc/outputs.tfoutput "vpc_id" {  description = "ID of the VPC"  value       = aws_vpc.main.id}
output "vpc_cidr_block" {  description = "CIDR block of the VPC"  value       = aws_vpc.main.cidr_block}
output "public_subnet_ids" {  description = "Map of availability zones to public subnet IDs"  value       = { for k, v in aws_subnet.public : k => v.id }}
output "internet_gateway_id" {  description = "ID of the internet gateway"  value       = try(aws_internet_gateway.main[0].id, null)}
# Root configuration using modulemodule "vpc" {  source = "./modules/vpc"
  name               = "production"  cidr_block         = "10.0.0.0/16"  availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
  tags = {    Environment = "production"    ManagedBy   = "Terraform"  }}

4. State Migration

Inspecting Current State

Before writing moved blocks or state mv commands, inspect the current state to map existing resource addresses. Prefer the documented, stable, and more token-efficient commands over reading the raw state file:

bash
# Enumerate current resource addresses (the inputs for `moved` / `state mv`)terraform state list
# Inspect resolved attribute values when you need themterraform show -json | jq '.values.root_module'

terraform show -json requires providers to be installed (terraform init), since it renders values against provider schemas. Fall back to the raw state (terraform state pull / terraform.tfstate) only when providers aren't available and init can't run, you need only coarse info (addresses, outputs, serial/lineage), or you must avoid executing Terraform. Avoid parsing the raw version-4 state format as a stable interface. Note: state contains sensitive values in plaintext in every format — never echo state contents into logs or output.

Generate Migration Plan
hcl
# migration.tf# Use moved blocks for state refactoring (Terraform 1.1+)
moved {  from = aws_vpc.main  to   = module.vpc.aws_vpc.main}
moved {  from = aws_subnet.public_1  to   = module.vpc.aws_subnet.public["us-east-1a"]}
moved {  from = aws_subnet.public_2  to   = module.vpc.aws_subnet.public["us-east-1b"]}
moved {  from = aws_internet_gateway.main  to   = module.vpc.aws_internet_gateway.main[0]}
Manual State Migration (Pre-1.1)
bash
# Generate state migration commandsterraform state mv aws_vpc.main module.vpc.aws_vpc.mainterraform state mv aws_subnet.public_1 'module.vpc.aws_subnet.public["us-east-1a"]'terraform state mv aws_subnet.public_2 'module.vpc.aws_subnet.public["us-east-1b"]'terraform state mv aws_internet_gateway.main 'module.vpc.aws_internet_gateway.main[0]'

5. Module Documentation

markdown
# VPC Module
## OverviewCreates a VPC with configurable public and private subnets across multiple availability zones.
## Features- Multi-AZ subnet deployment- Optional NAT gateway configuration- VPC Flow Logs integration- Customizable CIDR allocation
## Usage
\`\`\`hclmodule "vpc" {  source = "./modules/vpc"
  name               = "my-vpc"  cidr_block         = "10.0.0.0/16"  availability_zones = ["us-east-1a", "us-east-1b"]
  create_public_subnets  = true  create_private_subnets = true  enable_nat_gateway     = true
  tags = {    Environment = "production"  }}\`\`\`
## Requirements
| Name | Version ||------|---------|| terraform | >= 1.5.0 || aws | ~> 5.0 |
## Inputs
| Name | Description | Type | Default | Required ||------|-------------|------|---------|----------|| name | Name prefix for resources | `string` | n/a | yes || cidr_block | VPC CIDR block | `string` | n/a | yes || availability_zones | List of AZs | `list(string)` | n/a | yes |
## Outputs
| Name | Description ||------|-------------|| vpc_id | VPC identifier || public_subnet_ids | Map of public subnet IDs || private_subnet_ids | Map of private subnet IDs |
## Examples
See [examples/](./examples/) directory for complete usage examples.

6. Testing

Use skill terraform-test

Test File: A .tftest.hcl or .tftest.json file containing test configuration and run blocks that validate your Terraform configuration.

Test Block: Optional configuration block that defines test-wide settings (available since Terraform 1.6.0).

Run Block: Defines a single test scenario with optional variables, provider configurations, and assertions. Each test file requires at least one run block.

Assert Block: Contains conditions that must evaluate to true for the test to pass. Failed assertions cause the test to fail.

Mock Provider: Simulates provider behavior without creating real infrastructure (available since Terraform 1.7.0).

Test Modes: Tests run in apply mode (default, creates real infrastructure) or plan mode (validates logic without creating resources).

File Structure

Terraform test files use the .tftest.hcl or .tftest.json extension and are typically organized in a tests/ directory. Use clear naming conventions to distinguish between unit tests (plan mode) and integration tests (apply mode):

my-module/├── main.tf├── variables.tf├── outputs.tf└── tests/    ├── unit_test.tftest.hcl      # Unit test (plan mode)    └── integration_test.tftest.hcl  # Integration test (apply mode - creates real resources)

Refactoring Patterns

Pattern 1: Resource Grouping

Extract related resources into cohesive modules:

  • Networking (VPC, Subnets, Route Tables)
  • Compute (ASG, Launch Templates, Load Balancers)
  • Data (RDS, ElastiCache, S3)

Pattern 2: Configuration Layering

hcl
# Base module with defaultsmodule "vpc_base" {  source = "./modules/vpc-base"  # Minimal required inputs}
# Environment-specific wrappermodule "vpc_prod" {  source = "./modules/vpc-production"  # Inherits from base, adds prod-specific config}

Pattern 3: Composition

hcl
# Small, focused modulesmodule "vpc" {  source = "./modules/vpc"}
module "security_groups" {  source = "./modules/security-groups"  vpc_id = module.vpc.vpc_id}
module "application" {  source     = "./modules/application"  vpc_id     = module.vpc.vpc_id  subnet_ids = module.vpc.private_subnet_ids  sg_ids     = module.security_groups.app_sg_ids}

Common Pitfalls

1. Over-Abstraction

hcl
# ❌ Don't create overly generic modulesvariable "resources" {  type = map(map(any))  # Too flexible, hard to validate}
# ✅ Do use specific, typed interfacesvariable "database_config" {  type = object({    engine         = string    instance_class = string  })}

2. Tight Coupling

hcl
# ❌ Don't couple modules through direct references# module Aoutput "instance_id" { value = aws_instance.app.id }
# module B (in same config)resource "aws_eip" "app" {  instance = module.a.instance_id  # Tight coupling}
# ✅ Do pass dependencies through root modulemodule "compute" {  source = "./modules/compute"}
resource "aws_eip" "app" {  instance = module.compute.instance_id}

3. State Migration Errors

Always test migration in non-production first:

bash
# Create plan to verify no changes after migrationterraform plan -out=migration.tfplan
# Review carefullyterraform show migration.tfplan
# Apply only if plan shows no changesterraform apply migration.tfplan

Version Control Strategy

hcl
# Use semantic versioning for modulesmodule "vpc" {  source  = "git::https://github.com/org/terraform-modules.git//vpc?ref=v1.2.0"  version = "~> 1.2"}
# Pin to specific versions in production# Use version ranges in development

Success Criteria

  • Module has single, well-defined responsibility
  • All variables have descriptions and types
  • Validation rules prevent invalid configurations
  • Outputs provide sufficient information for consumers
  • Documentation includes usage examples
  • Tests verify module behavior
  • State migration completed without resource recreation
  • No plan differences after refactoring

Related Skills

Resources

Revision History

VersionDateChanges
1.0.02025-11-07Initial skill definition

來源與署名

來源：hashicorp/agent-skills位於plugins/terraform/skills/refactor-module提交f706481

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 hashicorp/agent-skills 的技能

Terraform Test

hashicorp

指導撰寫與執行 Terraform 測試，涵蓋 .tftest.hcl 檔案、run 區塊、斷言、mock 與 CI 整合。

Software Development8904 天前更新

Terraform Style Guide

hashicorp

依照 HashiCorp 官方風格慣例與最佳實務產生並審查 Terraform HCL 程式碼。

DevOps & Cloud8904 天前更新

Terraform Stacks

hashicorp

指導撰寫與驗證 HashiCorp Terraform Stacks 設定檔，用於多環境基礎架構。

DevOps & Cloud8904 天前更新

Terraform Policy

hashicorp

撰寫、測試與轉換 Terraform Policy 檔案（.policy.hcl、.policytest.hcl）以及 Sentinel 政策。

Software Development8904 天前更新

Provider Resources

hashicorp

Implement Terraform Provider resources and data sources using the Plugin Framework: CRUD operations, schema design, plan modifiers and validators, not-found handling, waiters for eventually consistent APIs, import support, resource design principles, and required acceptance test coverage. Use when adding or changing a resource or data source, deciding whether an API concept should be a resource, wiring a resource to the provider's configured client, handling drift or resource-not-found, or reviewing a resource implementation before submission.

待分類8904 天前更新

Provider Framework Migration

hashicorp

指導將 Terraform provider 資源從 Plugin SDKv2 遷移到 Plugin Framework，並使用混合式 provider。

Software Development8904 天前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新