refactor-module

refactor-module 技能概览

refactor-module 能做什么

refactor-module 技能可以把单体的 Terraform 配置重构成可复用的 module，让输入、输出、封装边界和迁移计划都更清晰。它面向的是重构工作，而不是从零设计新 module；当你手里已经有一套正在运行、但规模大到难以安全维护的 Terraform 代码时，它最有价值。

适合哪些人使用

如果你的 Terraform 难以复用、难以测试，或者因为逻辑、资源和 state 处理混在一起而改动风险很高，就适合用 refactor-module 技能。对于平台工程师、基础设施维护者，以及需要一份实用的 refactor-module guide、把现有工作负载拆成 module 边界又不丢失 state 上下文的评审者来说，它都很合适。

它为什么不一样

这个 refactor-module 技能是以决策为导向的：它会要求你提供源配置、module 名称、目标抽象层级和 state 兼容方案。比起泛泛的“把它模块化”提示词，它更可执行，因为它会推动 agent 去考虑接口、迁移和 registry 打包，而不只是重新摆放文件。

如何使用 refactor-module 技能

安装并指向正确的代码

在 refactor-module install 中，先按站点的技能安装流程安装 hashicorp/agent-skills，然后指向真正需要重构的 Terraform 配置。这个技能围绕 source_directory、module_name、abstraction_level、preserve_state 和可选的 target_registry 设计，所以最好一开始就把这些值提供清楚，而不是只说“帮我整理一下”。

先读对文件

先看 SKILL.md，了解工作流，再检查仓库上下文里定义规范、责任归属或发布预期的内容。如果你的环境里还有相邻文档或 module 标准，先读完再运行技能，这样输出会更贴合你仓库在命名、版本管理和 state 迁移方面的模式。

把模糊需求改成可用提示词

弱提示词会说：“把这个 Terraform 重构成 modules。” 更强的 refactor-module usage 提示词会写成：“重构 source_directory=./infra/prod，创建 module_name=vpc，使用 abstraction_level=intermediate，并为现有在线环境保留 state 兼容性。” 也要补上当前痛点，比如资源重复、接口不清晰，或者未来需要发布到 registry，因为这些都会影响重构应该有多激进。

采用能减少返工的工作流

先让它分析当前配置，再让它给出 module 边界、variables、outputs 和迁移步骤。若第一轮结果范围太大，就把范围收窄到一次只处理一个子系统，比如网络或 IAM，这样 module 设计更容易验证，state 迁移方案也更可信。

refactor-module 技能常见问题

refactor-module 只适合已有 Terraform 代码吗？

是的，refactor-module 技能主要用于已经存在、需要拆分成可维护 module 的配置。如果你是从零开始，普通的设计提示词可能就够了；但当你已经有资源、依赖关系和需要保留的 state 时，这个技能会更合适。

使用 refactor-module 前应该提供什么？

至少要提供源目录、module 名称，以及是否必须保留 state 兼容性。如果你还有 registry 目标、命名规范，或对抽象层级的限制，也一并提供；这些细节能帮助 refactor-module skill 避免产出在你环境里难以落地的设计。

什么时候不该用 refactor-module？

如果你只需要一次小清理、一次命名整理，或者只是想要一个 Terraform 示例，就不该用它。如果你无法提供足够的当前资源或 state 上下文，它也不适合，因为 module 重构依赖对依赖关系和迁移约束的理解。

如何改进 refactor-module 技能

给技能更强的约束

最好的 refactor-module 结果来自明确边界：哪些内容属于 module，哪些必须留在 root configuration，哪些因为生产环境 state 不能变。若这些都没说清，模型可能会把资源抽象得过头，或者给出技术上很漂亮、但运维成本很高的迁移路径。

提供当前痛点，而不只是期望结果

告诉技能这次重构为什么重要：是重复的 stacks、频繁 drift、变更很慢，还是准备对内发布。这样 refactor-module skill 才能在复用和简洁之间做出正确取舍，而这通常正是 Terraform module 工作里最难的决定。

检查输出的接口质量和迁移现实性

先审阅 variables、outputs、命名和依赖流，再确认 state 迁移计划是否符合你基础设施的真实部署方式。如果第一次回答太泛，就通过要求更窄的抽象层级，或更保守的保留 state 方案来迭代；这些调整通常比单纯要求“更详细”更能提升最终的 refactor-module guide。