terraform-style-guide

terraform-style-guide 技能概览

terraform-style-guide 技能可以帮助你生成符合 HashiCorp 风格规范、文件布局和安全默认值的 Terraform HCL。它很适合你想要的是 Terraform 原生的代码生成，而不是泛泛而谈的“基础设施即代码”答案。

这个技能适合做什么

当任务是生成干净的 Terraform modules、审查生成出来的 HCL 是否偏离风格，或者把粗糙的基础设施需求整理成可维护的 Terraform 布局时，就该用 terraform-style-guide 技能。它尤其适合你希望输出能直接组织进真实仓库，而不是只得到一段可复制粘贴示例的场景。

它能带来什么价值

当你关注依赖顺序、文件拆分、变量声明、outputs，以及避免脆弱的硬编码值时，这个技能最有用。terraform-style-guide 指南在安全选择上也很有帮助，因为它会强化加密、最小权限、敏感 outputs，以及更安全地处理 secrets。

适合哪些读者

如果你是开发者、平台工程师，或者正在尝试产出更易读、易扩展、易审查 Terraform 的 AI agent，那么 terraform-style-guide 技能是一个很实用的起点。如果你只需要一段一次性的代码片段，而且不在乎结构或规范，那么普通 prompt 可能就够了。

如何使用 terraform-style-guide 技能

安装并触发它

在执行 terraform-style-guide install 这一步时，先从 HashiCorp skills repo 添加这个 skill，然后在 Terraform 相关的生成任务中调用它。实际使用中，最好的效果来自于明确说明输出应遵循 terraform-style-guide 技能，并且你希望生成或审查的 Terraform HCL 要符合 HashiCorp 风格。

提供正确的输入

terraform-style-guide usage 的最佳做法，是提前给出云厂商、资源目标、命名约定、环境假设，以及任何安全或 state 约束。强输入会像这样：“为 AWS S3 bucket 生成 Terraform，启用 versioning 和 encryption，variables.tf 放变量，outputs.tf 放 outputs，不要硬编码 secrets。” 弱输入会像这样：“写一份存储的 Terraform。”

先读这些文件

先看 SKILL.md，因为它包含核心生成规则和文件组织指导。然后检查 SECURITY.md，了解加固要求，尤其是在代码要管理真实云资源时。如果你要在自己的 repo 里把 terraform-style-guide 用于 Code Generation，还要查看周边仓库的规范，例如 module 布局、命名规则或 provider pinning 的要求。

能产出更好结果的工作流

建议用两步走：先让模型给出 Terraform 设计和文件计划，再让它生成实际 HCL。这样可以减少变量遗漏、资源顺序错误和文件放置不一致的问题。如果你已经知道目标结构，就直接告诉模型把 provider constraints 放在 terraform.tf，配置放在 providers.tf，resources 放在 main.tf，声明放在 variables.tf 和 outputs.tf。

terraform-style-guide 技能常见问题

terraform-style-guide 只适合新写 Terraform 吗？

不只是。terraform-style-guide 技能同样适合把已有 HCL 重构成更一致的结构，尤其是在文件混在一起或变量重复声明的情况下。它最有价值的地方，不是让代码“能跑”，而是让结果更易维护。

它和普通 prompt 有什么区别？

普通 prompt 也可能生成可用的 Terraform，但 terraform-style-guide 技能会更强地引导输出遵循 HashiCorp 风格的文件组织、依赖顺序和更安全的默认值。当你需要的不是“技术上正确一次”，而是可审查、可复用的结果时，这一点很重要。

它会替代 Terraform 知识吗？

不会。terraform-style-guide 技能能提升格式、结构和生成纪律，但并不能免除你对 provider 特定参数、资源语义或 backend 方案的核对。应把它看作风格和工作流指南，而不是平台验证的替代品。

什么时候不该用它？

如果你的任务本来就是非标准的、高度主观的，或者已经绑定到某个与 HashiCorp 规范冲突的现有 module 架构上，就不要依赖它。在这些情况下，terraform-style-guide 技能可能会成为约束，而不是收益。

如何改进 terraform-style-guide 技能

提供更清晰的基础设施意图

最能提升质量的做法，是明确目标云、资源类型、环境模型，以及哪些内容必须可配置。比如“一个支持多环境的 AWS module，包含 environment、region 和 tags 变量”，远比“帮我写 AWS Terraform”更有用。

尽早说明你的约束

如果输出必须支持 remote state、私有网络、静态加密，或敏感 outputs，请在生成前就说清楚。terraform-style-guide 技能在能把这些约束直接编码进结构时表现最好，而不是事后再打补丁。

按文件逐个输出

如果结果看起来很乱，就要求按 Terraform 文件拆开输出，而不是放在一个合并块里。这更符合 terraform-style-guide 指南，也更方便在审查时发现缺失的变量、outputs 或 provider 要求。

根据审查反馈继续迭代

第一轮之后，可以用更具体的修改要求来提升结果：比如“把所有可配置值移到 variables 里”“补上 validation blocks”“把 locals 和 resources 分开”“把和 secrets 相关的 outputs 标记为 sensitive”。这类反馈通常比让它给出一个笼统的“更好版本”更有效。