Terraform Style Guide

ANÁLISE EDITORIAL

Um arquivo Terraform pode estar sintaticamente correto e, ainda assim, ser difícil de revisar, manter ou migrar. A Terraform Style Guide transforma as recomendações oficiais da HashiCorp em instruções reutilizáveis para um agente organizar HCL, nomes, variáveis, saídas, versões e controles de segurança. O valor está na consistência do rascunho e da revisão. A Skill não prova que a infraestrutura é segura, não consulta o estado por conta própria e não autoriza um terraform apply.

Esta curadoria fixa o commit 4451ceca5456e79cc776efee96a744f7ac96e5bf, consultado em 17 de agosto de 2026. O repositório oficial hashicorp/agent-skills tinha 819 estrelas no momento da consulta. O número fica abaixo da preferência editorial de mil estrelas, mas a exceção é objetiva: o projeto é mantido pela própria HashiCorp, possui documentação, histórico público e licença MPL-2.0 verificável. Isso confirma a origem oficial, não é uma alegação de popularidade nem de qualidade automática.

O que a Skill faz

O SKILL.md fixado orienta o agente a começar pelas restrições de versão e configuração de providers, declarar data sources antes dos recursos que dependem deles, construir recursos em ordem de dependência e expor resultados importantes por outputs. Também estabelece a organização convencional em terraform.tf, providers.tf, main.tf, variables.tf, outputs.tf e locals.tf.

Na escrita do HCL, a Skill pede indentação de dois espaços, alinhamento de argumentos consecutivos, argumentos antes de blocos e nomes em minúsculas com sublinhado. Variáveis precisam de tipo e descrição. Outputs precisam de descrição, e valores sensíveis devem ser marcados como tal. Para recursos dinâmicos, ela prefere for_each quando as instâncias têm identidades estáveis e reserva count para casos simples, como criação condicional.

Essas instruções acompanham o guia oficial de estilo do Terraform, que recomenda formatação, validação, nomes previsíveis, organização de arquivos, versionamento e tratamento de credenciais. A Skill condensa a referência para o contexto do agente, mas o documento oficial continua sendo a fonte de verdade quando houver conflito ou mudança posterior.

Para quem serve

Ela é útil para equipes que já usam Terraform e querem reduzir variações mecânicas entre módulos, pull requests e ambientes. Um engenheiro pode pedir ao agente para criar o esqueleto de um módulo com os arquivos corretos. Um revisor pode usar a mesma Skill para apontar variáveis sem descrição, nomes pouco claros, versões não fixadas ou outputs sensíveis. Uma equipe de plataforma pode incorporá-la como linha de base antes de aplicar regras próprias de arquitetura, custo, segurança e compliance.

Ela não substitui conhecimento do provider, desenho de rede, gestão de estado, revisão de IAM, testes ou políticas organizacionais. Para uma auditoria de segurança de código, uma Skill como a Trail of Bits CodeQL resolve outro problema. Para navegar pelo catálogo e comparar finalidades antes de instalar, consulte a página de Skills do Bastidores da IA.

Compatibilidade e pré-requisitos

O repositório atual organiza a Skill em plugins/terraform/skills/terraform-style-guide e fornece manifests para Codex e Claude Code no mesmo pacote Terraform. O README oficial do plugin documenta a instalação individual por caminho canônico. Em outros agentes compatíveis com pastas de Agent Skills, o método de descoberta pode variar, portanto confirme a documentação da ferramenta antes de escolher a pasta global ou por projeto.

Para aproveitar as orientações, tenha um repositório Terraform versionado, uma versão conhecida do Terraform CLI e os providers relevantes documentados. A Skill mostra required_version >= 1.14 e AWS provider ~> 6.0 em um exemplo, não como requisito universal. Respeite o arquivo .terraform.lock.hcl, os módulos existentes e as restrições reais do projeto. A documentação de bloqueio de dependências explica por que a seleção instalada deve permanecer reproduzível.

Instalação controlada

O comando documentado pelo mantenedor para instalar somente esta Skill é:

npx skills add hashicorp/agent-skills/plugins/terraform/skills/terraform-style-guide

Antes de executá-lo, abra o repositório, confira o caminho atual e revise os arquivos que serão copiados. Para um teste isolado, prefira instalação no projeto em vez de global. Se a ferramenta aceitar uma referência fixada, use o commit auditado. O ZIP local do Bastidores contém somente SKILL.md, SECURITY.md, LICENSE e ORIGEM.md. Ele serve para leitura e instalação manual controlada, sem scripts ou dependências.

Não rode Terraform durante a instalação da Skill. O arquivo de instruções é texto, mas o agente que o utiliza pode receber permissão para ler e escrever no repositório ou executar comandos. Comece em uma branch, mantenha uma cópia do estado e negue mudanças fora do diretório em análise. A instalação não deve receber credenciais de cloud, tokens de CI ou arquivos .tfvars com segredos.

Configuração segura

Defina no pedido inicial o escopo permitido: diretório, arquivos que podem ser alterados, providers envolvidos e comandos autorizados. Um bom limite é solicitar primeiro apenas um diagnóstico e um diff proposto. Depois, aprove separadamente a escrita dos arquivos. Mantenha apply, importação de recursos, remoção do estado e mudanças no backend fora do alcance automático.

A referência SECURITY.md orienta criptografia em repouso, rede privada, menor privilégio, logging e proteção de segredos. Ela também estabelece uma ordem para dados sensíveis: integração nativa com um gerenciador de segredos, atributos write-only combinados com recursos efêmeros e, somente como último recurso, valores sensíveis persistidos no estado. A própria referência manda confirmar Terraform 1.11 ou superior antes de gerar recursos efêmeros. Veja a documentação oficial sobre recursos efêmeros e sobre dados sensíveis.

Primeiro uso seguro

Escolha um módulo pequeno e reversível. Peça ao agente para revisar somente a organização e o estilo, sem alterar nomes de recursos, endereços, backend ou providers. Um pedido inicial útil é: “Leia estes arquivos Terraform, compare com a Terraform Style Guide e devolva uma lista priorizada. Não edite e não execute comandos”. Isso permite separar problemas de formatação de decisões que mudariam o grafo ou o estado.

Na segunda etapa, autorize uma correção limitada e examine o diff. Rode terraform fmt -check -recursive para confirmar a formatação. Em seguida, faça terraform validate em um diretório inicializado com os providers corretos. O comando validate verifica sintaxe e consistência interna, mas não consulta APIs remotas nem confirma se uma escolha de arquitetura é adequada.

Se o diff alterar recursos ou valores calculados, gere um plano no processo habitual da equipe e revise cada mudança. Não trate uma saída limpa do formatter como aprovação de segurança. Também não aceite uma recomendação de versão sem confrontá-la com o lock file, a documentação do provider e os módulos consumidores.

Resultado esperado

O resultado saudável é um conjunto de arquivos HCL mais previsível, acompanhado de uma explicação curta sobre o que mudou e do que permaneceu fora do escopo. Variáveis e outputs ficam documentados, nomes seguem um padrão, versões aparecem em locais reconhecíveis e recursos são organizados para facilitar a leitura. A revisão humana deve conseguir distinguir uma mudança apenas editorial de outra que altera endereço, dependência, lifecycle ou estado.

Se o agente devolver um bloco grande sem indicar arquivos, riscos e comandos de validação, a tarefa ainda não terminou. Peça um diff menor. Se ele sugerir segredos em variáveis comuns ou outputs não marcados como sensíveis, interrompa a aplicação e volte à referência de segurança. Se houver divergência entre a Skill e a documentação atual do Terraform, prevalece a documentação oficial.

Permissões e riscos

O manifesto do plugin Terraform declara capacidades de leitura e escrita. Isso descreve o alcance esperado do agente, não uma permissão automática concedida pelo ZIP. Na prática, a ferramenta hospedeira decide se pode ler arquivos, criar diretórios, executar npx ou chamar o Terraform CLI. O risco principal não está no pacote documental, mas na combinação entre instrução, credenciais disponíveis e autonomia do agente.

Renomear recursos pode provocar substituições ou exigir moved blocks. Alterar versões pode atualizar providers. Mudar count para for_each sem plano de migração muda endereços no estado. Marcar um output como sensitive reduz exposição na interface, mas não remove o valor do estado. Por isso, a Skill deve orientar um rascunho e uma revisão, nunca ser usada como aprovação silenciosa para produção.

Erros comuns e como diagnosticar

• A Skill não é descoberta: confirme que a pasta contém SKILL.md no nível esperado pelo agente. Se usou o comando oficial, verifique o caminho instalado e reinicie apenas a ferramenta que documenta essa necessidade.
• O agente ignora SECURITY.md: mantenha o arquivo ao lado do SKILL.md. O pacote desta curadoria inclui a referência justamente porque o arquivo principal aponta para ela.
• O exemplo de versão conflita com o projeto: trate números do exemplo como ilustração. Use as restrições do repositório, o lock file e a compatibilidade dos módulos.
• terraform validate falha por provider ausente: execute a validação em ambiente controlado após a inicialização definida pelo projeto. Não permita que o agente troque o backend ou atualize providers apenas para apagar o erro.
• O formatter muda muitos arquivos: pare, reduza o escopo e revise por diretório. Formatação em massa pode esconder alterações semânticas no mesmo diff.
• O plano propõe substituições inesperadas: não aplique. Compare endereços, chaves de for_each, nomes e lifecycle com o estado e com o código anterior.

Versão, licença e download local

A versão auditada é o commit 4451ceca5456e79cc776efee96a744f7ac96e5bf, de 10 de agosto de 2026. O repositório declara MPL-2.0, que permite redistribuir o código-fonte sob as condições da licença e preservando seus avisos. O ZIP local mantém os arquivos oficiais sem modificação e acrescenta ORIGEM.md com hashes individuais, procedência e limites.

SHA-256 do pacote auditado: 4ecdc46eaff2c421adb32b41a37218248ca277b7e9b1b97c03b5a4f8167d1a67. Compare esse valor com o card de download antes de abrir o arquivo. O pacote não contém executáveis, scripts, dependências, credenciais, estado, planos ou dados de projeto. A imagem desta página é uma ilustração editorial exclusiva, não uma captura do Terraform nem prova de execução.

Fontes primárias

• Pasta oficial da Terraform Style Guide no commit auditado.
• Manifesto oficial do plugin Terraform para Codex.
• Guia oficial de estilo do Terraform.
• Sintaxe oficial da linguagem de configuração.
• Referência oficial do comando terraform plan.