terraform-stacks

terraform-stacks 技能概览

terraform-stacks 是一项实用技能，适用于使用 HashiCorp Terraform Stacks 时，需要在不同环境、区域或账号之间定义、连接并验证 stack 配置的场景。它最适合后端开发人员和平台工程师：你不是只在写独立的 .tf 文件，而是在把可复用的 Terraform modules 组织成一套协同部署模型。

它主要解决的是 Stack language、文件布局以及跨 stack 连接方式带来的混乱。terraform-stacks 技能尤其适合用来判断如何拆分组件和部署、如何组织 .tfcomponent.hcl 和 .tfdeploy.hcl 文件，或者在一次运行被阻断之前，先排查语法和依赖问题。

terraform-stacks 最适合做什么

当你在做这些事时，适合用这个技能：

• 基于现有 modules 搭建新的 Stack
• 将基于 module 的基础设施迁移为协同部署
• 建模多环境或多区域基础设施
• 连接不同 Stacks 之间的输出
• 排查 Stack 专属的校验错误或依赖错误

terraform-stacks 为什么不同

不同于通用的 Terraform prompt，terraform-stacks 关注的是 Stack language 及其运行约束：独立的文件类型、component/deployment 边界、provider 配置模式，以及 linked-stack 的行为。也正因为如此，当问题不是“Terraform 怎么写”，而是“这个 Stack 应该怎么组织才真的能跑起来”时，它更有决策价值。

什么时候可能不适合

如果你只需要一个单模块的 Terraform 示例，或者你根本没有使用 Stack 文件，terraform-stacks 可能就过于专门了。如果你的问题主要是云厂商设计，而不是 Stack 结构、编排或部署连接，它的帮助也会有限。

如何使用 terraform-stacks 技能

安装并打开正确的源文件

进行 terraform-stacks install 时，先从 hashicorp/agent-skills 添加这个技能，然后优先阅读 Stack 相关源文件：

npx skills add hashicorp/agent-skills --skill terraform-stacks

先从 SKILL.md 开始，再查看：

• references/component-blocks.md
• references/deployment-blocks.md
• references/linked-stacks.md
• references/examples.md
• references/troubleshooting.md
• references/api-monitoring.md

这些文件比泛泛扫一遍仓库更重要，因为它们展示了真实的 block 语法、链接模型，以及会直接影响输出质量的运行边界。

把模糊目标变成可用 prompt

terraform-stacks 的使用方式，最适合你先提供这些信息：

• 云厂商和账号模型
• 目标环境与区域
• 源来自本地、私有 registry 还是公共 registry
• 你希望创建或修复哪个文件
• Stacks 之间预期的部署关系

弱 prompt 会说：“给我的应用创建一个 Terraform Stack。”
更强的 prompt 会说：“为一个 AWS 应用设计 terraform-stacks 布局，包含共享网络和独立的 dev/prod 部署。使用本地 modules，发布 VPC outputs，并展示 .tfcomponent.hcl 和 .tfdeploy.hcl 文件。”

更容易产出高质量结果的工作流

1. 先定义 Stack 边界：一个 stack 还是多个互相连接的 stacks。
2. 决定哪些值属于 components，哪些值属于 deployments。
3. 先说明 module 来源和 provider 约束。
4. 要求按文件逐个输出，不要把所有内容混在一个配置块里。
5. 在应用前，对照参考文件验证结果。

提升质量的实用技巧

质量提升最大的地方，来自你提供真实约束：现有 module 名称、provider 版本、命名规范，以及依赖方向。如果省略这些，terraform-stacks 可能会返回一个看起来正确的结构，但它仍可能不符合你的仓库规范或部署流程。

terraform-stacks 技能 FAQ

terraform-stacks 只适合高级 Terraform 用户吗？

不是。terraform-stacks 技能对已经理解基础 Terraform modules、但现在需要 Stack 感知结构的初学者同样有用。学习曲线主要在文件职责、引用关系和部署编排上，而不是在更复杂的 HCL 语法上。

这和普通的 Terraform prompt 有什么不同？

普通 prompt 可能只会给你一个 module 或 resource 示例。terraform-stacks 关注的是 Stack 专属决策：component 边界、deployment 文件、linked outputs，以及如何按环境组织基础设施。这也是为什么在需要 Terraform Stacks 时，应该用 terraform-stacks guide，而不是照着通用 Terraform 建议临时发挥。

terraform-stacks 对后端开发有帮助吗？

有，尤其适用于 terraform-stacks for Backend Development 这类场景：基础设施是应用交付流水线的一部分。它非常适合后端服务需要独立的 dev/stage/prod 部署、共享基础设施层，或者受控的跨 stack 依赖时使用。

什么时候不该用 terraform-stacks？

如果你没有采用 Terraform Stacks，或者你只需要一个小型一次性 module，或者问题与 Stack 结构无关，就不该用它。在这些情况下，这个技能只会增加额外复杂度，却不会提升结果。

如何提升 terraform-stacks 技能

先给出 stack 形状，再要求代码

最强的 terraform-stacks 输出，往往一开始就有清晰的形状：stack 数量、component 数量、部署环境，以及 outputs 是否需要向下游传递。如果没有这些信息，模型可能会选出一个语法上成立、但与你的运行模型并不一致的结构。

提供真实的 module 和 provider 约束

如果你想要真正可用的输出，请包含：

• module source 路径或 registry 地址
• provider 版本
• 需要的区域或账号
• 认证方式是否使用 OIDC、静态凭证或 HCP Terraform 设置
• 仓库里已经存在的命名或目录规范

这些细节可以避免返工，让 terraform-stacks usage 的输出更接近你可以直接提交的内容。

注意最常见的失败模式

最常见的问题通常是：

• 把 component inputs 和 deployment values 混为一谈
• 在 components 之间制造循环依赖
• 文件扩展名或 block 类型不匹配
• 漏掉必要的 provider 或身份信息
• 过度连接 stacks，而其实更简单的布局就足够了

如果第一次答案显得太抽象，就要求它按文件逐个重写，并移除那个具体失败点。

用明确的验收标准继续迭代

比起说“改进一下”，更好的后续提示是：“保持相同的 Stack 形状，但让它兼容一个 private registry module，拆分 dev 和 prod 部署，并展示哪些 outputs 应该发布给下游 stack。” 这种请求能让 terraform-stacks 给出更适合决策的修订版本，也能让 terraform-stacks guide 的结果更紧凑、更可落地。