一、基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 正式名称 | refactor-module-hashicorp-agent-skills | 合集仓库子目录名（见下方说明） |
| 所属合集仓库 | hashicorp/agent-skills（HashiCorp 官方 Agent Skills 合集，含 Terraform、Packer 两条产品线共 17 个技能） | GitHub |
| 作者/维护者 | HashiCorp（现为 IBM 旗下），官方账号 hashicorp 发布，仓库可见 16 位具名贡献者 |
GitHub API |
| 来源链接 | https://github.com/hashicorp/agent-skills/tree/main/terraform/module-generation/skills/refactor-module | — |
| 许可证 | MPL-2.0（Mozilla Public License 2.0），仓库根目录 LICENSE 文件确认 | GitHub API |
| 所属仓库整体 Stars/Forks | 754 / 110（注：该数字属整个合集仓库，不代表本技能自身热度，仅作背景参考） | GitHub API |
| 最新版本 | 内部 metadata 版本号 0.0.1；本技能所在目录最近一次提交为 2026-07-09 | GitHub API |
| 安装方式 | npx skills add hashicorp/agent-skills/terraform/module-generation/skills/refactor-module；或经 Claude Code 插件市场安装 terraform-module-generation@hashicorp |
官方 README |
二、功能介绍与亮点
本技能教 Agent 把手写的单体 Terraform 配置重构成可复用、边界清晰的模块：识别耦合模式 → 设计变量/输出接口 → 给出重构前后完整代码对照（以 VPC 为例） → 用 moved 区块或 terraform state mv 平滑迁移 state、不重建已有资源 → 生成模块 README 模板。
核心亮点：① 给出可直接套用的重构前/后完整 HCL 代码对照与 state 迁移命令，不止讲原则；② 专列“常见陷阱”（过度抽象的万能类型、模块间紧耦合），各配正反例；③ 附“成功标准”检查清单及“相关技能”交叉引用（terraform-style-guide、terraform-test、Azure Verified Modules）；④ 第三方自动化审计 NLPM 于 2026-04-06 逐文件评分，本技能获 92/100，未发现安全或功能缺陷。
三、适用场景
固定分类：工程效率与代码质量
需要把团队积累的单体 Terraform 配置拆分为可复用模块、且必须保证已有 state 不被意外重建的 IaC 工程师；也适用于新人接手历史 Terraform 项目、需 Agent 辅助规划模块边界与迁移步骤的场景。
四、跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 官方 README 列出 Claude Code 为支持目标，并提供插件市场安装命令 |
| Codex | 未验证 | README 列出 GitHub Copilot / Opencode / Cursor 等通用安装目标，未点名 Codex |
| OpenClaw | 未验证 | 同上，未提及 |
| Hermes Agent | 未验证 | 同上，未提及 |
五、推荐理由
HashiCorp 官方把“如何把资源安全地拆成模块”从零散经验，变成带完整代码对照与 state 迁移命令的可执行工作流，且经第三方自动化审计单独核实质量。
六、评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 所属仓库整体 754 星、110 fork、16 位具名贡献者（背景参考，不计入本技能自身）；本技能所在目录有独立提交历史，最近一次提交为 2026-07-09；第三方自动化审计工具 NLPM 单独抓取并评分本文件 |
| 可用性 | 9 | 一条命令或经插件市场即可安装；内容详实、含完整重构前后代码示例与迁移命令；目录近日（2026-07-09）仍有维护；核心重构指导本身无需额外付费依赖 |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合评分 | 8.3 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 涉及 terraform state mv、terraform plan/apply 等命令，均作用于用户自己声明的基础设施状态，用途在正文中逐条说明，范围明确 |
| ② 运行时联网外发 | 技能正文本身不发起任何网络请求 |
| ③ API Key/凭据 | 核心重构指导不要求任何凭据；仓库内该插件另附一个可选 MCP 组件（对接 Terraform Cloud/Enterprise，需用户自备 TFE_TOKEN），与本技能非强绑定 |
| ④ 可疑指令排查 | 已直接抓取 SKILL.md 全文核实，未发现 prompt injection 或隐藏指令；第三方自动化审计 NLPM 对本文件单独评分 92/100，未标注安全问题 |
| ⑤ 作者/组织信誉 | HashiCorp（现 IBM 旗下），Terraform 官方开发商，仓库由多位具名员工共同维护 |
| ⑥ License | MPL-2.0，条款清晰 |
| ⑦ 最近维护 | 目录最近一次提交 2026-07-09（lint 修复） |
纯指导性内容、无外联，且为官方出品、完全开源可审计，符合 9-10 档标准，定为 9 分。
七、跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本 skill 的差异 |
|---|---|---|
| terraform-skill（antonbabenko，个人开发者出品） | 通用 Terraform/OpenTofu 最佳实践诊断技能，内置 13 种故障模式路由表 | 覆盖面是全场景 IaC 质量诊断（漂移、密钥泄露、变更半径等），不专门针对“把单体配置拆成模块”这一具体重构工作流给出代码级步骤 |
| terraform-style-guide（同仓库 hashicorp/agent-skills 内的另一子技能） | Terraform 代码风格与格式规范 | 只管命名、格式等风格层面的一致性，不涉及资源分组、接口设计、state 迁移等模块化架构决策 |
核心差异化：本技能把“模块化重构”拆解到代码级步骤（含 state 迁移命令与前后代码对照），而非泛化最佳实践清单或纯格式规范。
八、用户评价
该技能目前在第三方社区平台尚无具名用户评价；GitHub 仓库层面有第三方自动化审计工具 NLPM 于 2026-04-06 生成的逐文件质量评分（本文件 92/100），已在第六章引用。
九、其他补充
hashicorp/agent-skills 仓库覆盖 Terraform 与 Packer 两条产品线，refactor-module 与仓库内 terraform-style-guide、terraform-test 等为同产品线不同子技能，功能互补而非替代；官方公告后续将扩展至 Vault、Consul 等产品。
十、安装使用方式
方式一：npx skills 通用安装
npx skills add hashicorp/agent-skills/terraform/module-generation/skills/refactor-module方式二：Claude Code 插件市场
claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform-module-generation@hashicorp安装后无需重启，Agent 在处理 Terraform 模块重构、拆分单体配置等相关任务时会自动加载本技能；若需使用同插件内可选的 Terraform Cloud/Enterprise 集成（MCP 组件），需另行准备 TFE_TOKEN，但不影响核心重构指导功能的使用。
十一、注意事项
- state 迁移操作（
moved区块或terraform state mv）直接作用于生产 state，正文提醒先用terraform plan核实无差异再执行，用户仍需自行做好 state 备份 - 内容以 AWS 场景（VPC/子网）为主要示例，其他云厂商需自行按同样模式套用
- 目前仅验证了与 Claude Code 的兼容性，其余 Agent 生态尚未获得直接证据