Série sobre Agentic IaC

Este é o primeiro de três posts onde vou documentar, passo a passo, a construção de um agente de IA para projetos de Infrastructure as Code. Sem hype, sem falar de IA como se fosse a mágica salvadora do universo. Sem prometer que um prompt vai resolver todos os seus problemas de infraestrutura. Já adianto, não vai. No fim desse post você vai perceber isso.

O que você vai encontrar aqui é orientação prática, com base em referências técnicas de engenharia e em artigos da OpenAI, Anthropic e Martin Fowler que descrevem como times reais estão construindo e operando agentes em produção. A ideia é trazer esse conhecimento para o contexto de quem trabalha com Terraform e IaC no dia a dia.

A série está organizada assim:

• Post 1 (este): A anatomia do agente: O que é, quais são os mecanismos, como a estrutura funciona
• Post 2: Na prática: Um passo a passo completo para entregar um projeto real do início ao fim usando o agente
• Post 3: Distribuição: Como transformar o agente em padrão do time e escalar para toda a organização

Cada post deve ser lido sozinho, mas juntos tento criar um roteiro básico para quem quer ir além de “usar IA para gerar código” e construir um sistema de entrega que aprende e melhora com o tempo.

Certo!?!? Vamos lá então!!!

Introdução Agentic IaC

Em muitas empresas, o time repete os mesmos acertos e erros em projetos de IaC a cada sprint. Alguém esquece de fixar a versão X do provider. Outro faz um apply sem revisar o plan direito. O contexto de uma entrega fica perdido num thread do Slack/Teams que ninguém vai encontrar daqui a duas semanas. O problema não é falta de competência. É falta de sistema para gerir tudo isso.

Quando o conhecimento vive na cabeça das pessoas e não no repositório, cada sessão de trabalho começa do zero. E é exatamente aqui que entra uma verdade que pouca gente fala: o sucesso de um agente de IA não depende do modelo que você escolhe. Depende do trabalho que você faz antes de dar qualquer prompt. É o processo que importa.

Antes de montar um agente, você precisa olhar para como seu time trabalha e fazer um exercício difícil. Revisar e remover processos que existem por inércia, aqueles passos que ninguém sabe por que estão ali. Se o processo é confuso para um humano, vai ser confuso para um agente. Depois, detalhar o que sobra com clareza suficiente para que alguém que nunca viu aquilo consiga seguir. E por fim, a parte mais importante. Transformar conhecimento tácito em regras explícitas. Aquela convenção de naming que “todo mundo sabe”. Aquele workaround que o sênior faz de cabeça. Aquela decisão arquitetural que ficou registrada só numa reunião. Se não está escrito num arquivo que o agente consegue ler, simplesmente não existe para ele.

Esse trabalho tenta explicitar, documentar, e estruturar é o investimento real na construção de um Agentic IaC. Agentic IaC é a prática de combinar um agente de IA com uma estrutura de regras, contexto e validação que vive no repositório junto com o código de infraestrutura. Uma forma de empacotar tudo que seu time sabe num formato que tanto humanos quanto agentes de IA conseguem consumir. Não estou falando de um chatbot genérico. Estou falando de uma estrutura operacional que dá ao agente memória, processo, e mecanismos de aprendizado contínuo. É isso que torna a abordagem “agentic”, o agente não apenas responde perguntas ou gera código sob demanda. Ele opera dentro de um sistema que acumula contexto, segue um processo definido, e melhora a cada ciclo. Neste primeiro post, vamos dissecar a anatomia do bicho.

O que é um AI Agent (e o que não é)

Vamos alinhar o vocabulário. Quando falo “agent” aqui, não estou falando de um modelo de linguagem jogado num terminal com acesso a comandos. Isso é uma ferramenta. Um agente é diferente.

A definição mais útil que encontrei vem da comunidade de engenharia de IA:

Agent = Model + Harness

O modelo é a inteligência bruta, o LLM que gera texto, “raciocina”, escreve código. O Harness são as regras, o contexto, os mecanismos de validação, as instruções de comportamento. O modelo sem harness é como um cachorro solto que late e morde sem parar. O harness sem modelo é o cercadinho vazio e a coleira pendurada na parede, ou seja, um processo bonito que ninguém executa.

O ponto central aqui é que o trabalho da pessoa de DevOps deixa de ser “escrever código de infraestrutura” e passa a ser “projetar o ambiente onde o agente consegue trabalhar bem”. Você vira o arquiteto do sistema. O agente vira quem executa.

Humanos direcionam. Agentes executam.

O problema que ele resolve

Se você trabalha com infraestrutura como código, provavelmente reconhece pelo menos uma dessas três dores:

Contexto que se perde entre reuniões. Você estava trabalhando num módulo de VPC na sexta, volta na segunda e precisa gastar 30 minutos reconstruindo o raciocínio. Se é um colega assumindo a tarefa, pior ainda.

Erros que se repetem. Aquele recurso da AWS que recria quando você muda o nome. Aquele provider que tem um bug conhecido. Aquele módulo que precisa de um depends_on explícito senão quebra. Alguém descobre, resolve, e seis meses depois outro colega cai na mesma armadilha.

Conhecimento que fica invisível. As decisões tomadas numa reunião. A convenção de naming que “todo mundo sabe”. O motivo pelo qual o state está separado daquele jeito. Se não está escrito no repo, não existe para o agente e eventualmente não vai existir para o time também.

O agente não resolve esses problemas magicamente. Ele resolve porque a estrutura ao redor dele obriga o conhecimento a ser registrado, versionado, e consultado.

Guides e Sensors: o modelo mental de trabalho

Aqui está o framework conceitual que organiza tudo. Ele vem da engenharia de controle e foi formalizado recentemente para o contexto de coding agents.

Existem dois mecanismos de controle:

Guides (feedforward): Antecipam problemas e direcionam o agente ANTES dele agir. São como guardrails numa estrada de montanha. No contexto de IaC, um guide é qualquer informação que reduz a chance do agente tomar uma decisão errada antes mesmo de escrever a primeira linha de código.

Exemplos concretos de guides para IaC:

• Um documento listando os CIDRs já alocados na organização evita que o agente proponha um range que conflita com outra VPC
• Uma regra explicita: “todo recurso AWS deve ter as tags project, environment, owner e managed_by”, o agente aplica desde a primeira iteração, sem precisar de correção humana
• Um checklist pré-apply: “verifique se o provider está fixado, se o backend está configurado, se não há secrets hardcoded” o agente valida antes de apresentar o plan
• A lista de módulos internos aprovados pelo time, com versão e exemplos de uso em vez de inventar do zero, o agente reutiliza o que já existe
• Convenções de naming como {projeto}-{env}-{recurso}-{az} documentadas num arquivo, não na cabeça de alguém
• Anti-patterns conhecidos: “nunca use count para resources que têm lifecycle dependencies; use for_each” o agente evita armadilhas antes de cair nelas

Sensors (feedback): Observam o resultado DEPOIS do agente agir e alimentam a auto-correção. São como sensores de temperatura num datacenter. No contexto de IaC, um sensor é qualquer verificação que detecta problemas no que o agente já produziu.

Exemplos concretos de sensors para IaC:

• terraform validate: sensor computational básico. Se o código tem erro de sintaxe ou referência inválida, detecta imediatamente
• terraform plan diff é o sensor mais importante. Mostra exatamente o que vai mudar. Se aparece um destroy inesperado ou um must-replace num recurso de produção, o agente precisa parar e escalar
• terraform fmt -check verifica se a formatação segue o padrão. Trivial, mas evita ruído no code review
• Checkov, tfsec ou Trivy scanners de segurança que detectam configurações inseguras (S3 bucket público, security group aberto para 0.0.0.0/0, encryption desabilitada)
• Infracost estima o custo mensal dos recursos no plan. O agente pode verificar se a mudança está dentro do budget esperado antes de pedir aprovação
• Re-plan imediato após o apply. Se terraform plan mostra diff depois de aplicar, há drift. O sensor detecta e o agente registra
• O próprio FEEDBACK.md é o registro estruturado dos outcomes. Cada falha registrada é um dado que alimenta o aprendizado do processo

Se você só tem guides sem sensors, o agente segue regras mas nunca descobre se elas funcionaram. Se você só tem sensors sem guides, o agente repete os mesmos erros até alguém perceber o padrão.

Cada mecanismo ainda se divide em dois tipos de execução:

• Computational é determinístico, rápido, executado por ferramentas. O terraform validate é um sensor computational. O tfsec rodando num pre-commit hook é um sensor computational. Um script que verifica se todas as variáveis têm description é um guide computational.
• Inferential é baseado em julgamento, executado pelo próprio LLM. Uma revisão do plan pelo agente buscando impactos não-óbvios é um sensor inferential. Um documento de design principles que o agente consulta antes de projetar a arquitetura é um guide inferential.

A combinação dos dois eixos forma a matriz completa:

O poder está na combinação. Sensors computacionais são rápidos e baratos. Rode em cada iteração. Sensors inferenciais são mais caros mas capturam problemas semânticos que nenhum linter detecta (“esse security group está tecnicamente válido, mas a regra de ingress é mais permissiva do que o necessário para essa aplicação”).

O steering loop

O nome vem da ideia de steering, que significa pilotar, direcionar. Pense num carro. Você não controla cada explosão no motor ou cada giro da roda. Você segura o volante e faz correções de rumo. Se o carro puxa para a esquerda, você corrige. Se uma curva é mais fechada do que parecia, você ajusta. Você não executa, você direciona.

Com um agente de IA é a mesma coisa. O humano não fica escrevendo cada linha de Terraform. Ele constrói o sistema de controle (guides e sensors) e depois direciona ajustando as regras, adicionando falhas ocorridas, refinando checklists. O agente executa dentro desse sistema.

O “loop” é o que fecha o ciclo. Não é uma execução linear que começa e termina. É um ciclo contínuo onde o resultado de cada execução alimenta a próxima:

O humano define as regras e prioridades. Os guides direcionam o agente antes dele agir. O agente executa. Os sensors observam o resultado. Se algo falhou, o agente tenta auto-corrigir. Se o mesmo problema apareceu duas vezes, o humano melhora o harness, adiciona um novo pitfall no FEEDFORWARD.md, refina um checklist, documenta uma convenção. Na próxima execução, esse conhecimento já está nos guides. Feedback vira feedforward.

O poder do steering loop é que ele melhora com o tempo sem exigir mais trabalho do humano, pelo contrário, exige menos. Cada correção que você faz no harness e commita no git é uma correção que nunca mais precisa ser feita manualmente.

Na prática: um apply falha porque um security group referencia uma VPC que ainda não existe. O agente registra no FEEDBACK.md. Da próxima vez que o mesmo tipo de dependência aparecer, o FEEDFORWARD.md já contém a prevenção: “sempre declare dependências explícitas entre recursos quando estão em módulos separados.”

Escrevendo instruções que funcionam

Ter a estrutura de arquivos é necessário, mas não suficiente. O conteúdo dentro dos guides precisa ser escrito de uma forma que o agente realmente consiga usar. Instruções vagas como “siga boas práticas” ou “trate erros adequadamente” não servem para nada. Essa não é a linguagem do agente. Ele precisa de orientação concreta, específica do seu contexto.

Alguns princípios que fazem diferença na hora de escrever o conteúdo dos seus guides:

Inclua o que o agente não sabe, omita o que ele já sabe. Você não precisa explicar o que é uma VPC ou como funciona o protocolo TCP. O modelo já sabe disso. O que ele não sabe é que na sua empresa o CIDR 10.0.0.0/8 já está alocado, que o time usa naming com o padrão {projeto}-{env}-{recurso}, ou que aquele módulo interno exige uma dependência explícita no Internet Gateway. Foque no conhecimento específico do seu contexto, porque é ali que o agente erra sem orientação.

Seções de armadilhas conhecidas valem ouro. O conteúdo de maior valor num guide geralmente é uma lista de “pegadinhas” específicas do ambiente, aqueles detalhes traiçoeiros que parecem funcionar mas quebram de formas inesperadas. Em inglês, o termo usado é gotchas (de “got you” ou na tradução das ruas “pegadinha do Malandro”). São situações onde o comportamento padrão engana até gente experiente. Não são conselhos genéricos, são correções concretas para erros que o agente vai cometer se ninguém avisar:

## Armadilhas Conhecidas

- O módulo `vpc-core` v2.3 tem um bug: se você passar `enable_dns = false`,
  ele ignora e habilita mesmo assim. Use v2.4+.
- Security groups referenciando outros SGs por ID precisam de dependência
  explícita quando estão em módulos separados.
- O backend S3 na conta de staging usa uma KMS key diferente da produção.
  Não copie o backend config de um para o outro sem ajustar.

Dê defaults, não menus. Quando existem múltiplas formas de fazer algo, escolha uma como padrão e mencione alternativas brevemente. Apresentar cinco opções como iguais paralisa o agente, porque ele não tem contexto para escolher.

Prefira procedimentos a declarações. O guide deve ensinar o agente como abordar uma classe de problemas, não qual é a resposta para uma instância específica. “Para criar um módulo novo, siga: 1) crie o diretório em modules/, 2) defina variables.tf com description e validation, 3) rode fmt e validate antes de commitar” é mais reutilizável do que listar exatamente quais variáveis um módulo específico deve ter.

Calibre o nível de controle. Nem toda instrução precisa do mesmo rigor. Seja prescritivo quando a operação é frágil ou irreversível, como por exemplo: “rode exatamente terraform plan -out=plan.tfplan antes do apply, sem modificar flags.” Dê liberdade quando múltiplas abordagens são válidas, como: “organize os outputs de forma que faça sentido para quem consumir downstream.”

Validation loops: o agente que se auto-corrige

Um dos patterns mais poderosos no harness é instruir o agente a validar seu próprio trabalho antes de avançar. O padrão é simples: executa, valida, corrige, repete até passar.

Isso não é uma sugestão, é uma instrução explícita no PROCESS.md. O agente não precisa ser perfeito na primeira tentativa. Ele precisa de um loop de auto-correção claro, com validadores computacionais que dão feedback imediato e específico.

O mesmo princípio se aplica ao plan. Antes de apresentar o plan ao humano, o agente verifica contra o FEEDFORWARD.md: tem destroys inesperados? Tem resources sem tags? O checklist pré-apply passa? Se não passa, corrige antes de escalar.

Esse pattern, o plan-validate-execute, é especialmente importante para operações destrutivas. Criar um plano intermediário, validar contra uma source of truth, e só então executar. O agente que pula a validação é o agente que destrói um banco de dados em produção.

Progressive disclosure: o mapa, não o manual

Voltando à estrutura de arquivos, existe uma razão pela qual o AGENTS.md é curto e aponta para outros documentos em vez de conter tudo.

O contexto de um LLM é finito. Cada token no prompt compete por atenção com todos os outros. Se você jogar 5.000 linhas de instruções no contexto do agente, ele vai se perder e vai seguir regras que não se aplicam à tarefa atual, ou vai ignorar regras críticas porque estão enterradas no meio de informação irrelevante.

A solução mais recomendada é o progressive disclosure: o AGENTS.md carrega o essencial, ou seja, quem o agente é, como opera, e onde buscar mais detalhe. Os outros arquivos são carregados sob demanda, quando o agente precisa daquela informação específica.

Na prática:

• AGENTS.md diz: “antes de aplicar, consulte a seção Pre-Apply Guards do FEEDFORWARD.md”
• O agente só carrega essa seção quando chega nesse momento do processo
• O MEMORY.md inteiro só é consultado no início da sessão para restaurar contexto

Isso mantém o agente focado no que importa agora, sem sobrecarregar com tudo que ele poderia precisar eventualmente.

A estrutura de arquivos de um Agent

Agora vamos ao concreto. O harness do agente vive como arquivos .md na raiz do repositório. Cada arquivo tem uma função precisa:

repo/
├── AGENTS.md        — O índice. Curto, estável, aponta para os outros.
├── MEMORY.md        — Memória de longo prazo. Append-only.
├── HANDOFF.md       — Estado da sessão atual. Lido no início, escrito no fim.
├── FEEDFORWARD.md   — Guides: pitfalls, checklists, anti-patterns, principles.
├── FEEDBACK.md      — Sensors: registro de outcomes pós-execução.
├── PROCESS.md       — Fluxo de entrega (stages sequenciais).
├── TASKS.md         — Decomposição do trabalho atual.
└── CHECKLIST.md     — Quality gates por transição de stage.

AGENTS.md é o mapa. Não é um manual de 500 linhas, e sim um índice de ~100 linhas que diz ao agente quem ele é, como ele opera, e onde buscar informação mais profunda. Se você colocar tudo num arquivo só, o agente perde foco. Se você distribui em arquivos com responsabilidade clara, ele navega com precisão.

MEMORY.md é append-only. Decisões, lessons learned, error patterns, quirks de providers. Nunca se deleta uma entrada; se ficou obsoleta, marca como superseded. Isso garante audit trail.

HANDOFF.md é o artefato de transição. Estado atual, o que foi feito, o que falta, blockers, riscos. Quando uma sessão termina (ou quando o agente troca de contexto), esse arquivo captura tudo que o próximo operador precisa saber.

FEEDFORWARD.md contém a inteligência pré-execução. Pitfalls conhecidos, checklists pré-plan e pré-apply, design principles, anti-patterns. É consultado antes de cada ação significativa.

FEEDBACK.md registra outcomes. Cada apply, cada falha, cada rollback vira uma entry com: o que tentou, o que esperava, o que aconteceu, root cause, resolução, e a lesson extraída.

PROCESS.md define os stages de entrega: Intake, Design, Build, Validate, Deploy, Close. Sequencial, sem pulos.

TASKS.md decompõe o trabalho. Uma task ativa por vez. Cada task com critério de aceitação claro.

CHECKLIST.md define quality gates. Antes de transicionar de Build para Validate, por exemplo, o agente verifica: fmt passa? validate passa? variáveis têm description? Sem passar no gate, não avança.

Construindo a partir de expertise real

Um erro comum é pedir para o LLM gerar os guides do zero, sem contexto específico do seu projeto. O resultado são instruções genéricas e inúteis: “trate erros adequadamente”, “siga boas práticas de segurança”. Isso não agrega nada.

Os melhores guides nascem de experiência real. É nesse ponto que o nosso conhecimento técnico acumulado faz a diferença. Vejam duas formas de construí-los:

Extraia de uma tarefa concluída. Termine uma entrega de IaC trabalhando junto com o agente. Preste atenção nos momentos em que você corrigiu o rumo, como: “não, use esse módulo em vez daquele”, “aqui precisa de um validation block”. Esses momentos de correção são o conteúdo do seu FEEDFORWARD.md. Extraia o padrão reutilizável.

Sintetize dos artefatos que já existem. Seu time provavelmente já tem runbooks, comentários de code review, incident reports, histórico de fixes no git. Esse material é ouro. Um FEEDFORWARD.md construído a partir dos seus incident reports reais vai capturar os failure modes específicos do seu ambiente, e não os genéricos de um blogpost.

E depois de criar a primeira versão, refine com execução real. Rode o agente contra tarefas concretas. Leia os traces de execução, não só o output final. Se o agente está perdendo tempo tentando múltiplas abordagens, o guide provavelmente está vago demais. Se ele segue instruções que não se aplicam à tarefa, o guide está largo demais. Itere.

O loop de aprendizado contínuo

Num fluxo de trabalho tradicional, o conhecimento nasce e morre dentro da cabeça de quem executou. O engenheiro descobre que um recurso da AWS tem um comportamento estranho, resolve o problema, e segue em frente. Três meses depois, outro colega, ou ele mesmo, cai no mesmo buraco. O conhecimento existia, mas não estava acessível.

O loop de aprendizado contínuo resolve isso transformando cada execução do agente numa oportunidade de capturar conhecimento e torná-lo reutilizável. Não é algo que acontece “quando sobrar tempo” ou “no final do projeto”. É parte do processo, e acontece automaticamente a cada ciclo de trabalho.

A mecânica é simples e baseada em frequência:

Primeira ocorrência de um problema: registra no FEEDBACK.md. Apenas observa. Pode ser um caso isolado, não vale criar uma regra para algo que talvez nunca se repita.

Segunda ocorrência do mesmo problema: agora é padrão. Promove para MEMORY.md (vira lesson permanente que o agente consulta no início de cada sessão) e para FEEDFORWARD.md (vira prevenção ativa que o agente verifica antes de agir).

Falha crítica em qualquer ocorrência: não espera repetir. Promove imediatamente para ambos. Se derrubou um recurso em produção ou causou downtime, isso vira prevenção na hora.

Sucesso notável: o aprendizado não é só sobre erros. Um pattern que funcionou particularmente bem, como uma forma de organizar módulos ou uma estratégia de state splitting, vai para FEEDFORWARD.md como “proven pattern”.

Isso cria um ciclo virtuoso:

Por que isso é tão importante nesse novo fluxo de trabalho? Porque um agente de IA não tem a experiência acumulada que um engenheiro sênior carrega. Ele não “lembra” que aquele provider tem um bug, que aquele módulo precisa de um workaround, que aquela conta tem uma restrição. Toda vez que o agente inicia uma sessão, ele começa sem contexto, a não ser que esse contexto esteja escrito num arquivo que ele consegue ler.

O loop de aprendizado transforma o harness num sistema que fica mais inteligente a cada entrega. Na primeira semana, o FEEDFORWARD.md está quase vazio e o agente precisa de bastante supervisão. No segundo mês, ele já tem dezenas de pitfalls documentados, patterns provados, e quirks de providers registrados. O agente comete menos erros, precisa de menos correção, e o humano gasta menos tempo revisando, porque o conhecimento que antes vivia só na cabeça das pessoas agora está no repositório, acessível para qualquer operador, humano ou agente.

Conclusão

Um AI Agent para projetos de IaC não é um chatbot que roda terraform apply. É um sistema de controle com:

• Guides que previnem erros antes da execução, escritos com conhecimento específico do seu contexto, não conselhos genéricos
• Sensors que detectam problemas depois da execução e alimentam auto-correção
• Memória que acumula conhecimento ao longo do tempo
• Processo que garante consistência com validation loops em cada etapa
• Handoff que preserva contexto entre sessões
• Progressive disclosure que mantém o agente focado sem sobrecarregar

Mas antes de sair montando a estrutura, um aviso importante: nada disso funciona se você simplesmente colocar um agente de IA por cima do seu processo atual e esperar que as coisas acelerem. IA não acelera bagunça, ela escala bagunça. Se o seu fluxo de entrega tem etapas que ninguém sabe por que existem, o agente vai seguir essas etapas cegamente. Se suas convenções são contraditórias, o agente vai produzir resultados contraditórios. Se o conhecimento do time está espalhado em Slack, Confluence e cabeças, o agente não vai ter acesso a nada disso.

O trabalho real começa antes do primeiro prompt. Rever o que vocês fazem hoje. Remover o que não faz mais sentido. Adaptar o que funciona mas precisa ser explicitado. Documentar o que sempre foi implícito. Esse exercício de olhar para dentro, simplificar, e estruturar é o que separa um time que usa IA de verdade de um time que apenas instalou mais uma ferramenta.

E não é um exercício que você faz uma vez e pronto. O harness precisa evoluir junto com o time, com os projetos, com os providers, com os modelos de IA. Rever, ajustar, mudar, acompanhar continuamente. O steering loop não é só para o agente. É para o time inteiro. A estrutura toda cabe em oito arquivos markdown versionados no mesmo repo do seu código de infraestrutura. Sem dependências externas. Sem ferramentas adicionais. Sem banco de dados.

No próximo post, vou pegar essa estrutura e usar para entregar um projeto real do início ao fim, com um roteiro completo por cada estágio do processo. Você vai ver o agente consultando FEEDFORWARD.md, registrando no FEEDBACK.md, e atualizando HANDOFF.md em tempo real.

Abraços!

Vida longa e próspera a todos!!

Referências

• Harness engineering: leveraging Codex in an agent-first world — OpenAI, Fev 2026
• Harness design for long-running application development — Anthropic, Mar 2026
• Harness engineering for coding agent users — Martin Fowler / Birgitta Böckeler, Abr 2026
• Best practices for skill creators — Agent Skills
• Spec Driven chegou no limite — Harness Engineering é o próximo passo — Aprendi muito com esse vídeo ⭐⭐⭐⭐⭐
• https://infraascode.com.br/ia-como-copiloto-em-infraestrutura/
• https://infraascode.com.br/ia-como-copiloto-em-infraestrutura-v2/
• https://infraascode.com.br/meu-amigo-robo/
• https://infraascode.com.br/nao-tenha-medo-da-ia-estude-os-fundamentos/

Entre em contato: