refactor-module_skill

Overview

This skill automates refactoring monolithic Terraform configurations into reusable, maintainable modules that follow HashiCorp module design principles and community best practices. It focuses on clear input/output contracts, encapsulation, versioning, documentation, testing, and a safe state migration path. The goal is predictable modules that are easy to consume, test, and evolve.

How this skill works

The agent analyzes your existing Terraform files to identify logical resource groupings, repetition, and cross-resource coupling. It generates module scaffolding with typed variables, outputs, and validation rules, and proposes moved blocks or terraform state mv commands for safe state migration. The skill also creates module documentation, example usage, and test harnesses (.tftest files) to validate behavior before and after migration.

When to use it

• You have a large monolithic Terraform root module that is hard to maintain.
• You need to expose a clean, typed interface for reuse across environments.
• You want to introduce automated tests and documentation for infrastructure components.
• You must migrate existing state into new module structure without resource recreation.
• You plan to publish modules to a registry (local, private, or public).

Best practices

• Group tightly coupled resources (e.g., VPC + subnets) into one module and keep cross-cutting concerns separate.
• Design explicit, typed variables and outputs with validation to prevent invalid inputs.
• Prefer small focused modules and use composition or layering for environment-specific customizations.
• Use moved blocks (Terraform 1.1+) or terraform state mv for predictable state migration; always test in non-production first.
• Add tests (.tftest) for unit/plan checks and integration/apply runs; include mock providers when appropriate.

Example use cases

• Refactor a monolithic networking configuration into a reusable vpc module with AZ-mapped subnet outputs.
• Extract compute resources (ASG, launch templates, ALB) into a module consumed by multiple environments.
• Create a database module with strict input object types and validation for engine and sizing.
• Migrate existing resources into modules using moved blocks or scripted terraform state mv commands to avoid recreation.
• Add plan-mode unit tests and integration tests to verify no changes after refactoring.