terraform-module-library

terraform-module-library skill 概览

terraform-module-library 的作用

terraform-module-library skill 的定位，不是帮你临时拼一份一次性的 .tf 文件，而是帮助你为云基础设施设计可复用的 Terraform module。它更适合正在为 AWS、Azure、GCP 或 OCI 搭建内部 module 目录的团队，希望统一 module 结构、示例目录和测试模式时使用。

谁适合使用 terraform-module-library

最适合 terraform-module-library 的用户，包括平台工程师、云架构师、DevOps 团队和咨询顾问。这类用户通常需要可重复使用的 Terraform 构件，例如 VPC/VNet、Kubernetes、数据库、存储或负载均衡模块。尤其当你的目标是产出一个可维护的 module 仓库，而不只是单个环境的 stack，这个 skill 会更有价值。

它真正解决的工作需求是什么

大多数用户并不是抽象地想要一份“Terraform 代码”。他们真正需要的，是一个之后能被其他团队安全复用的 module：输入输出清晰、版本边界明确、带示例、带测试。terraform-module-library 的价值就在于，它会把重点拉回到 module 接口、默认值、组合方式，以及不同 provider 的最佳实践上。

这个 skill 的差异化在哪里

terraform-module-library 最明显的差异点是“结构化”。源材料明确围绕一套标准 module 模式展开：main.tf、variables.tf、outputs.tf、versions.tf、README.md、examples/complete 和 tests。此外，它还附带 AWS 和 OCI 的专门参考资料，因此相比泛泛的“写 Terraform”提示词，它能给出更具体的落地方向。

什么情况下 terraform-module-library 特别适合

当你想用 terraform-module-library 来做这些事情时，它会很合适：

• 从零创建一个可复用 module
• 在团队之间统一 module 目录结构
• 把云厂商约定沉淀到一个稳定的 module 接口里
• 在 module 代码旁边补齐示例和测试
• 为跨多个环境的 Cloud Architecture 工作建设 module library

什么情况下它不是合适的工具

如果你只需要以下内容，terraform-module-library 就没那么合适：

• 一个快速的一文件 Terraform PoC
• 一个包含大量在线依赖的完整环境编排
• 超出参考资料范围的 provider 深度实现细节
• module 的部署自动化、CI/CD 或发布工程方案

如何使用 terraform-module-library skill

terraform-module-library 的安装方式与使用上下文

从 wshobson/agents 仓库安装这个 skill：

npx skills add https://github.com/wshobson/agents --skill terraform-module-library

安装后，在你的 agent 环境里调用它时，要明确说明你需要的是“可复用 Terraform module”，而不只是基础设施代码。这个 skill 不是 Terraform provider，也不是 CLI plugin；它本质上是一套可通过提示词调用的指导和模式，用来生成面向 module 的输出。

提示前先看这些文件

建议先读：

1. plugins/cloud-infrastructure/skills/terraform-module-library/SKILL.md
2. plugins/cloud-infrastructure/skills/terraform-module-library/references/aws-modules.md
3. plugins/cloud-infrastructure/skills/terraform-module-library/references/oci-modules.md

SKILL.md 说明了目标 module 的结构。参考文件则补充了更实用的 module 候选项和最佳实践，尤其是 AWS 默认约定和 OCI 接口设计相关内容。

terraform-module-library 需要哪些输入才更好用

如果你提供以下信息，terraform-module-library 的效果通常会明显更好：

• 云厂商：AWS、Azure、GCP 或 OCI
• module 类型：VPC、EKS、RDS、object storage、load balancer 等
• 预期使用方：平台团队、应用团队、共享服务团队
• 必需的 inputs 和 outputs
• 安全要求：encryption、IAM、logging、backups
• 命名和 tagging 标准
• Terraform 与 provider 的版本约束
• 是否需要示例和 Terratest 脚手架

如果没有这些信息，模型通常还是会生成一个“看起来像样”的 module 结构，但接口设计往往会比较弱。

如何把模糊需求改写成高质量的 terraform-module-library 提示词

较弱的提示词：

Create a Terraform module for AWS networking.

更强的提示词：

Use terraform-module-library to design a reusable AWS VPC module for internal platform teams. Include main.tf, variables.tf, outputs.tf, versions.tf, README.md, examples/complete, and tests/module_test.go. Support public and private subnets, NAT gateways, route tables, VPC flow logs, standard tags, and encryption where applicable. Target Terraform 1.x and aws provider ~> 5.0. Expose outputs needed by EKS and RDS modules. Keep the interface stable and avoid environment-specific values.

后者之所以效果更好，是因为它明确了使用者、兼容性、范围边界和组合目标。

真实项目里建议采用的 terraform-module-library 工作流

一个实用的 terraform-module-library usage 流程通常是：

1. 先确定一个清晰的 module 边界
2. 优先定义对外公开的接口
3. 明确 provider / version 约束
4. 再要求生成 module 文件夹结构
5. 先产出 variables.tf 和 outputs.tf，再补实现细节
6. 添加 examples/complete，方便使用方理解
7. 添加 tests/module_test.go，做基础验证
8. 继续迭代默认值、可选功能和 outputs

这个顺序能有效避免 module 越长越散、输入接口越来越不稳定。

先设计接口，不要先堆资源数量

使用 terraform-module-library 时，一个很常见的错误是直接要求“把所有东西都加进去”。但对可复用 module 来说，更重要的是 API 是否干净：

• 哪些输入是必填的
• 哪些选项应该有安全默认值
• 哪些输出是给下游组合使用的
• 哪些功能本来就应该排除在 scope 之外

比如，AWS VPC module 应该清晰暴露 subnet IDs 和 VPC ID。OCI networking module 则应明确建模 compartment 输入，并返回其他 module 会依赖的 OCIDs。

充分利用内置的 provider 参考资料

AWS 参考资料尤其适合这些 module：

• vpc
• eks
• rds
• s3
• alb
• lambda
• security-group

它还强调了生产环境里用户真正关心的默认项：provider ~> 5.0、默认开启 encryption、最小权限 IAM、tagging、logging、backups，以及与 AWS Well-Architected 指导的一致性。

如果你的 terraform-module-library for Cloud Architecture 工作涉及 OCI，OCI 参考资料会特别有帮助，重点包括：

• 显式的 compartment 建模
• 优先使用 NSGs，而不是宽泛的 security lists
• dynamic groups 与最小权限 IAM
• 为组合场景暴露必要的 OCIDs
• 默认 logging、metrics 和 backup 设置

明确要求生成完整的 module scaffold

当你明确要求 terraform-module-library 按标准模式输出时，这个 skill 的价值会更高：

• main.tf
• variables.tf
• outputs.tf
• versions.tf
• README.md
• examples/complete/main.tf
• examples/complete/variables.tf
• tests/module_test.go

如果你不主动要求这些 scaffold，很多 agent 会省略文档、示例或测试，从而直接削弱 module 的可复用性。

能显著提升输出质量的实用提示词模式

可以直接使用这类提示词：

• Generate only the module interface first: variables, outputs, versions, and README table.
• Keep environment values out of the module and move them to examples.
• Mark optional features clearly and prefer secure defaults.
• Show how this module composes with EKS, RDS, or OKE consumers.
• Explain which features should be separate modules instead of inlining everything.

这些模式能强制模型收紧边界，减少“过度设计”的大而全 module。

拿到第一版后，应该重点检查什么

在正式采纳输出前，建议先检查：

• 变量命名是否稳定、清晰、易读？
• outputs 是否足以支持下游 module？
• 是否在可行范围内开启了安全默认值？
• 示例是否真的能被消费，而不只是摆设？
• 测试是否和 module 接口保持一致？
• agent 是否把环境 stack 逻辑混进了可复用 module？

这一步通常能拦住最常见的早期落地问题。

terraform-module-library skill 常见问题

terraform-module-library 适合新手吗？

适合，前提是你的目标是理解 Terraform module 应该如何组织。它能提供清晰的目录结构和具体的 module 示例。不过，新手依然需要掌握基础 Terraform 知识，才能验证 provider 参数、理解资源行为并运行测试。

它和直接让 AI 写 Terraform 有什么区别？

泛化提示词通常会返回资源代码，但 module 边界往往比较弱。terraform-module-library skill 更适合需要可复用接口、示例、测试以及适合沉淀到 library 的目录结构时使用。它提升的重点不在“代码量”，而在“可维护性”。

terraform-module-library 会往 Terraform 里安装什么东西吗？

不会。terraform-module-library install 这一步是把 skill 加进你的 agent 工作流，而不是安装到 Terraform 本身。你仍然需要在自己的环境中照常运行 terraform fmt、terraform validate、测试，以及 provider 初始化等标准流程。

哪些云厂商支持得最好？

这个 skill 在高层设计上明确面向 AWS、Azure、GCP 和 OCI。就仓库里的证据来看，AWS 和 OCI 提供了具体的参考文件，因此目前这两个 provider 的指导信号最强。

terraform-module-library 适合生产环境工作吗？

适合作为面向生产的 module 设计与生成辅助工具，尤其因为它强调测试、示例、版本约束和安全默认值。但你仍然应该结合 provider 官方文档进行复核，执行验证流程，并套用你们组织内部的策略和 CI 检查。

什么时候应该避开 terraform-module-library？

如果你需要的是以下内容，建议不要用它：

• 完整的在线环境 root module
• 深度的 policy-as-code 或 CI pipeline 设计
• 参考资料未覆盖的高级 provider 边界场景
• 面向 module registry 的强约束发布 / 版本工作流

如何提升 terraform-module-library skill 的使用效果

缩小 module 范围

想让 terraform-module-library 产出更好，最快的方法就是只定义一个 module 边界。问它“an AWS ALB module”或“an OCI Object Storage module”，不要直接要求“完整的网络和应用平台 library”。范围越窄，接口通常越干净，错误假设也越少。

明确下游使用方

告诉这个 skill：谁会依赖这个 module。例如：

• This VPC module must support EKS and RDS consumers.
• This OCI VCN module must expose subnet and security outputs for OKE.

这样会直接改变输出质量，因为 outputs 会变得有明确目的，而不是泛泛而谈。

一开始就写明不可妥协的标准

可以提前写清这些标准：

• provider versions
• tag schema
• encryption defaults
• backup / logging requirements
• IAM least-privilege expectations
• compartment 或 account boundary 规则

这个 skill 本身已经倾向于关注这些问题，但如果你事先写明标准，后面清理和返工会少很多。

把可复用逻辑和示例环境分开

一个很常见的失败模式，是把环境专用的值泄漏进可复用 module。改进第一版时，可以直接要求：

• 把固定的 CIDRs、名称和环境标签移到 examples/complete
• 保持 module variables 通用且带类型定义
• outputs 只保留组合所需内容，不要塞调试噪音

这样生成的 module 会更容易发布，也更容易被复用。

不只要求“加功能”，也要要求“哪些不要加”

更好的 terraform-module-library guide 使用方式，是主动问清哪些内容应该留在 scope 之外。例如：

• 让 security groups 独立于 VPC module
• 不要把数据库配置打包进 network module
• 如果 IAM 逻辑责任过多，就拆出去单独处理

这能有效避免出现“大杂烩”式的 kitchen sink module。

第二轮重点补强测试和文档

在第一版输出之后，可以继续要求：

• 一份简洁的 README.md，包含用法与 inputs / outputs
• 一个真实可运行的 examples/complete
• 一个最小可用的 tests/module_test.go
• 关于边界场景和可安全升级默认值的说明

很多时候，真正决定一个团队会不会采用该 module 的，恰恰就是这些配套产物。

校验云厂商特有的前提假设

对于 AWS，确认输出是否遵循 encryption、logging、tagging 以及 provider ~> 5.0 等模式。对于 OCI，确认是否显式处理 compartment、暴露 OCID outputs、优先使用 NSG，并配置了 observability 默认项。这是提升 terraform-module-library usage 质量最划算的办法之一。

用“基于差异”的方式迭代，而不是整份重写

与其每次都全部重生，不如发起更有针对性的后续请求：

• Tighten variable types and validations.
• Reduce required inputs to the true minimum.
• Add outputs needed by downstream EKS consumers.
• Refactor optional features behind booleans or maps.
• Split this into two modules if responsibilities are mixed.

这种方式通常比反复整份重写更稳定，也更容易持续改进结果。