Quando a velocidade sobe, mas a confiança cai

Se você está desconfiado com a IA, você não está sozinho. Eu também já desconfiei.

Lendo um artigo recente do Martin Fowler (se você não conhece esse cara, se informe sobre ele pra ontem), uma frase ficou martelando na minha cabeça: a IA acelera aquilo que você já é. Se seu sistema de engenharia é saudável, acelera saúde. Se está capenga, acelera dívida.

Foi nesse ponto que a ideia ganhou forma para mim: o jogo não é mais sobre “quem escreve sintaxe mais rápido”. O jogo virou sobre quem constrói melhor o sistema de controle ao redor da IA.

Esse sistema eu tem sido chamado de Harness Engineering.

O que eu entendo por Harness Engineering

Se eu tivesse que resumir em uma frase:

Harness Engineering é a disciplina de projetar testes, restrições arquiteturais, contexto e governança de risco para guiar o que a IA produz com segurança e consistência.

Repara que isso muda o centro de gravidade da nossa profissão.

Antes, o foco principal era: “como eu escrevo esse código?”

Agora, o foco estratégico passa a ser:

• “Como eu defino o comportamento esperado?”
• “Como eu protejo os limites arquiteturais do sistema?”
• “Como eu forneço contexto suficiente para reduzir ambiguidade?”
• “Como eu calibro o nível de autonomia da IA pelo risco da tarefa?”

Eu gosto de uma analogia simples: o harness é a torre de controle. O avião (agente) pode ser rápido e poderoso, mas sem plano de voo, comunicação e regras de aproximação, a chance de colisão aumenta rápido.

Por que esse tema importa agora

No mesmo artigo do Fowler, aparecem ideias que eu considero centrais para os próximos anos:

• middle loop (camada de supervisão) como trabalho de engenharia cada vez mais relevante
• risk tiering (estratificação de risco) como disciplina central
• TDD como forma robusta de prompt engineering (olha ele de novo aí)

Eu concordo com essa direção porque ela conversa com algo que eu já vejo na prática: equipes que tratam IA como brinquedo de produtividade tendem a gerar pico de velocidade e vale de confiança. Equipes que tratam IA como parte do sistema de engenharia criam um efeito mais sustentável.

E aqui tem um ponto de liderança muito importante: isso não é responsabilidade de um indivíduo isolado. É desenho de sistema de trabalho. É alinhamento entre liderança técnica, arquitetura, plataforma e produto.

“Poxa, Hugo, então agora todo dev vai virar auditor de IA e parar de programar?”, diz o Leitor

Não. A programação continua existindo. O que muda é o vetor de valor.

O diferencial competitivo deixa de ser só escrever código e passa a incluir a capacidade de desenhar barreiras de proteção e ciclos de validação que mantêm qualidade em alta velocidade.

Os 4 pilares do Harness Engineering

Para não ficar abstrato, vamos ver o tema em quatro pilares que se reforçam.

1. Testes e avaliações primeiro

Se a IA gera opções, quem define certo e errado é o seu sistema de avaliação.

Por isso, eu tenho visto TDD (Test-Driven Development, desenvolvimento guiado por testes) ganhar um novo papel: não apenas melhorar design de código humano, mas também ancorar o comportamento esperado para agentes.

Sem isso, você está validando no olho e no feeling. E feeling não escala.

Na prática, esse pilar significa:

• Definir critérios de aceitação antes da geração
• Usar testes automatizados como contrato mínimo de comportamento
• Incluir avaliações não-funcionais quando fizer sentido (performance, segurança, observabilidade) ou as famosas Architectural Fitness Functions
• Tratar falhas recorrentes como sinal de lacuna no harness, não apenas “erro do modelo”

2. Restrições arquiteturais explícitas

Arquitetura implícita morre rápido quando você injeta velocidade de geração.

Se os limites de domínio, os contratos e os padrões de integração não estão claros, a IA tende a preencher lacunas com soluções plausíveis, mas desalinhadas.

Aqui entra um trabalho que times maduros já deveriam fazer, com IA ou sem IA:

• Tornar decisões arquiteturais explícitas (ADRs)
• Definir limites que não podem ser atravessados
• Estabelecer padrões aceitos para comunicação entre componentes
• Reduzir ambiguidade estrutural

É literalmente engenharia de contenção. Você não está reduzindo criatividade. Está protegendo integridade do sistema.

3. Engenharia de contexto

Esse pilar conecta diretamente com o que venho escrevendo sobre maturidade de agentes: contexto bom gera saída boa.

Quando falo de contexto, não é “prompt enorme”. É contexto útil, curado e orientado a decisão:

• convenções do time
• decisões arquiteturais e seus porquês
• regras de negócio que não podem ser violadas
• exemplos reais que servem como referência

Se você já usa artefatos como OpenSpec, OpenCode e AgentSkills, ótimo: eles cabem perfeitamente dentro deste pilar como instrumentos concretos de contexto.

O erro comum é achar que contexto é documento estático. Não é. É um ativo vivo de engenharia.

Para maiores detalhes, leia meu artigo anterior: Liderança Situacional na Era da IA.

4. Risk tiering e autonomia proporcional

Nem toda tarefa merece o mesmo nível de autonomia.

Esse é, talvez, o pilar mais negligenciado no começo da adoção de IA.

Eu sugiro uma matriz simples:

A ideia é simples: quanto maior o impacto potencial, maior o rigor de validação.

O Harness Loop: operacionalizando no dia a dia

Uma forma prática de tornar isso rotina é operar em ciclo.

Eu uso um loop de cinco etapas:

1. Especificar comportamento, limites e critérios
2. Gerar com agentes de IA
3. Avaliar com testes, checks e revisão orientada a risco
4. Restringir onde houve deslizes (ajustar contexto e limites)
5. Aprender com incidentes, retrabalho e acertos para evoluir o harness

Perceba que esse modelo desloca a conversa de “qual prompt mágico eu uso” para “qual sistema de aprendizagem e proteção meu time está construindo”.

Quando esse loop amadurece, acontece algo poderoso: a velocidade deixa de ser inimiga da qualidade.

Anti-patterns: sinais de que você está sem harness

Se você quiser um check rápido de realidade, aqui vão sinais clássicos de adoção desequilibrada:

• Volume de PR aumentou, mas o tempo de review explodiu
• Mesma feature com padrões diferentes dependendo de quem pediu ao agente
• Crescimento de correções pós-merge
• Discussões arquiteturais reaparecendo em toda sprint
• Sensação constante de “não confio totalmente nisso”

Se três ou mais desses sintomas estão acontecendo juntos, provavelmente não falta IA. Falta harness.

Outro anti-pattern comum: tentar resolver tudo com uma política genérica de uso de IA em uma base e achar que isso basta. Política sem mecanismo operacional vira intenção sem efeito.

O papel dos líderes técnicos nesse cenário

Na minha visão, o líder técnico da era dos agentes não perde relevância. Ele muda de alavanca.

Em vez de ser apenas o “resolvedor final” de problemas complexos, ele passa a ser também:

• designer de sistema de controle
• curador de critérios de qualidade
• articulador entre arquitetura, plataforma e produto
• educador do time em práticas de validação

Isso conversa com algo que eu já defendi em outros artigos: liderança técnica não é cargo, é comportamento. E aqui esse comportamento aparece de forma cristalina.

Você pode até usar a melhor IA do mercado, mas sem engenharia de proteção o resultado tende a oscilar. Com harness bem desenhado, até agentes diferentes convergem para outputs mais consistentes.

Conclusão: velocidade sem controle não é evolução

Se eu tivesse que resumir tudo em poucos pontos, seria isso:

• A IA muda o jogo, mas não elimina engenharia; ela muda onde a engenharia precisa ser mais forte
• Harness Engineering é o nome que tem sido usado para esse novo centro: testes, arquitetura, contexto e risco trabalhando juntos
• O papel do desenvolvedor e do líder técnico evolui de executor de sintaxe para designer de sistema de controle
• Times que tratam IA como aceleração sem proteção tendem a escalar dívida
• Times que constroem harness consistente conseguem escalar velocidade com mais confiança
• Aos CEOs, vocês sempre encontrarão alguém num corredor querendo vender uma solução mágica, vocês já sabem a resposta, o filme se repete.

No fim do dia, não se trata de frear inovação. Se trata de colocar cinto de segurança, freios ABS e pneus novos em um carro que agora corre muito mais rápido.

E aí, no seu contexto, qual pilar do Harness Engineering está mais frágil hoje: testes, restrições arquiteturais, contexto ou risk tiering? Quero muito ler sua experiência nos comentários. 👍😃🚀

Artigos relacionados que podem aprofundar essa conversa:

• Liderança Situacional na Era da IA
• Arquétipos da Liderança Técnica
• Times de Plataforma

Harness Engineering: O que separa times que escalam IA dos que escalam dívida was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O déjà vu que mudou minha perspectiva

Há alguns meses, eu estava revisando o output (resultado) de um agente de IA que configurei para gerar código em um projeto real. O código estava razoável, mas fora do padrão. Não seguia as convenções do projeto, ignorava decisões de arquitetura que tomamos meses atrás e, sinceramente, parecia aquele código genérico de tutorial que qualquer ferramenta cospe por padrão.

Eu parei. Respirei. E pensei: “Já vivi isso antes.”

Não com uma IA. Com pessoas.

Lembrei de um desenvolvedor júnior que entrou no meu time anos atrás. Brilhante, motivado, cheio de energia, mas que produzia código fora do padrão, ignorava convenções do projeto e trazia soluções genéricas de Stack Overflow. Não porque era ruim, mas porque lhe faltava contexto, maturidade e direcionamento.

E o que eu fiz com ele? Direcionei. Expliquei padrões. Revisei pull requests. Aos poucos, fui dando mais autonomia. Até que um dia, ele estava tocando features complexas sozinho, com qualidade impecável.

Foi aí que caiu a ficha: eu estava liderando agentes de IA exatamente como lidero pessoas. E, mais importante, o modelo que uso para desenvolver liderados funcionava perfeitamente para desenvolver agentes.

Esse modelo tem nome: Liderança Situacional.

O modelo que você já conhece (mas talvez não aplique assim)

A Situational Leadership (Liderança Situacional), criada por Paul Hersey e Ken Blanchard, é um dos modelos de liderança mais conhecidos do mundo. A ideia central é simples e poderosa: não existe um único estilo de liderança que funcione para todos. O estilo certo depende da maturidade de quem você está liderando.

O modelo define quatro níveis de maturidade do liderado:

• D1 — Iniciante Entusiasmado: Baixa competência, alto comprometimento. Quer fazer, mas não sabe como.
• D2 — Aprendiz Desiludido: Alguma competência, baixo comprometimento. Começou a ver a complexidade real e perdeu parte da confiança.
• D3 — Capaz, mas Cauteloso: Alta competência, comprometimento variável. Sabe fazer, mas ainda hesita em decisões mais autônomas.
• D4 — Autossuficiente: Alta competência, alto comprometimento. Pronto para receber uma tarefa e entregar com qualidade, sem microgerenciamento.

E para cada nível de maturidade, existe um estilo de liderança correspondente:

1. S1 — Dirigir: Alta direção, baixo suporte. Você diz o quê e como fazer.
2. S2 — Orientar (Coach): Alta direção, alto suporte. Você explica, ensina e acompanha de perto.
3. S3 — Apoiar: Baixa direção, alto suporte. Você está disponível, mas deixa a pessoa conduzir.
4. S4 — Delegar: Baixa direção, baixo suporte. Você entrega a responsabilidade e confia no resultado.

A beleza do modelo é que ele não é estático. A maturidade evolui, e o líder precisa acompanhar essa evolução, ajustando seu estilo. Tratar um D4 como D1 gera frustração. Tratar um D1 como D4 gera desastre.

“Poxa, Hugo, mas isso eu já sei. O que isso tem a ver com IA?”, diz o Leitor

Tudo. Absolutamente tudo!

A grande sacada: agentes de IA também têm níveis de maturidade

Pense no seguinte: quando você abre o Claude Code, o GitHub Copilot ou qualquer agente de código pela primeira vez em um projeto, o que acontece?

Ele não conhece suas convenções. Não sabe quais padrões de arquitetura você adotou. Não entende por que vocês escolheram uma lib em vez de outra. Ele é, literalmente, um D1 — Iniciante Entusiasmado. Tem uma capacidade absurda (o “comprometimento” aqui é o poder computacional), mas zero contexto sobre o seu projeto.

E o que a maioria das pessoas faz? Trata esse agente D1 como se fosse D4. Joga um prompt vago, “crie o endpoint de usuários”, e reclama que o resultado veio genérico, fora do padrão, sem considerar as decisões do projeto.

Isso é como delegar uma tarefa complexa para um júnior no primeiro dia. Claro que não vai funcionar!

A grande sacada está aqui: você precisa evoluir a maturidade do seu agente de IA da mesma forma que evolui a maturidade de um liderado. Isso não acontece com um prompt mágico. Acontece com um processo estruturado de construção de contexto, especificações e padrões.

O agente D1: muito poder, nenhum contexto

Vamos ser honestos: a maioria dos líderes técnicos hoje está preso no estágio D1 com seus agentes de IA. E a culpa não é da ferramenta, é da falta de investimento em maturidade.

Um agente D1 é como aquele desenvolvedor júnior brilhante que acabou de chegar. Ele é capaz? Sim, extremamente. Mas quando você pede “implementa o serviço de notificações”, ele vai entregar algo que funciona, mas que não segue o padrão de services do projeto, usa uma estrutura de pastas diferente, escolhe uma abordagem de error handling (tratamento de erros) que ninguém do time usa e ignora completamente o padrão de logging que vocês definiram.

O que você faz com esse desenvolvedor júnior? Dirige. Senta do lado, explica os padrões, mostra exemplos, revisa linha por linha.

Com o agente D1, é a mesma coisa: você precisa ser extremamente diretivo nos prompts, especificar cada detalhe, e revisar tudo. É trabalhoso, é lento, e muitas vezes você pensa: “era mais rápido eu mesmo ter feito.”

E sabe o que mais? Esse pensamento é exatamente o mesmo que muitos líderes têm com liderados D1. Mas líderes maduros sabem que o investimento inicial se paga exponencialmente depois.

Os frameworks que aceleram a evolução: AgentSkills, OpenSpec e OpenCode

Assim como no desenvolvimento de pessoas em que nós usamos PDIs (Plano de Desenvolvimento Individual), one-on-ones, feedbacks estruturados e programas de mentoria, no desenvolvimento de agentes de IA existem frameworks que estruturam a evolução da maturidade.

Na minha experiência, três se destacam, e usados em conjunto, são transformadores:

AgentSkills: O que o agente sabe fazer

O AgentSkills é um framework que define as habilidades e capacidades do agente no contexto do seu projeto. Pense nele como a “matriz de competências” que muitas empresas usam para guiar a carreira dos desenvolvedores.

Quando você estrutura as skills (habilidades) do agente, está dizendo: “Você sabe fazer isso, siga essas regras ao fazer aquilo, e quando encontrar esse cenário, use essa abordagem.”

É o equivalente a mapear as competências de um liderado e definir expectativas claras para cada uma.

OpenSpec: O contexto e as decisões do projeto

O OpenSpec é onde vivem as especificações do projeto, as decisões de arquitetura, os trade-offs (prós e contras) que foram feitos, os requisitos não-funcionais, as regras de negócio fundamentais.

Se o AgentSkills é “o que o agente sabe fazer”, o OpenSpec é “o que o agente precisa saber sobre o projeto”.

É como aquele documento de onboarding que você prepara para um novo membro do time, mas estruturado para consumo de uma IA. Inclui:

• Decisões de arquitetura e suas justificativas
• Padrões adotados e por que foram escolhidos
• Contexto de negócio relevante para decisões técnicas
• Restrições técnicas e organizacionais

O papel do OpenSpec no meu fluxo de trabalho é planejar. Antes de qualquer Agente sair codificando, é preciso que existam artefatos (specs) que descrevem exatamente o que precisa ser feito. Aqui é essencial o uso de modelos de IA mais “poderosos” para criação de artefatos ricos e detalhados, para que na codificação possamos economizar.

OpenCode: O executor do trabalho

O OpenCode complementa o trio definindo como o código deve ser escrito. Não é apenas executor, mas também o orquestrador que escolhe as habilidades necessárias para a execução da demanda, consultando specs e skills:

• Padrões de nomenclatura
• Estrutura de arquivos e pastas
• Design patterns (padrões de projeto) preferidos
• Como tratar erros, logs, testes
• Tarefas a serem executadas, bem como seu andamento

Pense assim: se o AgentSkills é o currículo do agente, o OpenSpec é a especificação do projeto e o OpenCode é o que da vida a funcionalidade. Juntos, eles transformam um agente D1 em um agente D3 com potencial D4.

De D1 a D4: o caminho na prática

Vou compartilhar como funciona a evolução, baseado na minha experiência com Claude Code e GitHub Copilot.

De modo proposital não pretendo explicar no detalhe cada ferramenta, elas tem uma documentação abrangente e esse não é o objetivo do artigo.

Estágio 1: Dirigir (D1 → D2)

No início, o agente não tem nada. Você começa criando as bases:

• Documente as decisões de arquitetura no OpenSpec: não precisa ser perfeito, precisa existir em openspec/config.yaml. Depois você evolui.

schema: spec-driven

context: |
  Tech stack: .NET 10, ASP.NET Core Web API, C#
  Architecture: Feature Folder with Vertical Slice Architecture
  ORM: Entity Framework Core (PostgreSQL / SQL Server
  Auth: Keycloak with JWT Bearer tokens
  Events: Dapr pub/sub integration events
  Testing: xUnit with Arrange-Act-Assert pattern
  API docs: Scalar (OpenAPI)
  We maintain backwards compatibility for all public APIs
  ... 
  to be continued

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows
  task:
    - Break down implementation into checkboxed tasks.

• Configure o OpenCode: Faça com que ele conheça o que um executor precisa conhecer. Regras do projeto: CLAUDE.md no diretório do seu projeto (usado se não existir AGENTS.md)

# Sample Project

## Architecture Overview

This is a .NET 10 Web API using **Feature Folder with Vertical Slice Architecture** and **CQRS pattern**. 

### Feature Folders (Business Logic)
Each feature is self-contained under `Features/{FeatureName}/` with use-case slices:

```
Features/{FeatureName}/
├── {Entity}.cs                    # Domain entity
├── I{Entity}Repository.cs         # Repository interface
├── {Entity}Repository.cs          # Repository implementation
├── {Entity}Configuration.cs       # EF Core entity config
├── {FeatureName}Controller.cs     # API Controller
├── {Entity}ViewModel.cs           # ViewModels
...
```

### Code Standards

- Prefer file-scoped namespace declarations and single-line using directives.
- Ensure that the final return statement of a method is on its own line.
- Use pattern matching and switch expressions wherever possible.
- Use nameof instead of string literals when referring to member names.
- Always use is null or is not null instead of == null or != null.

### Database
- Supports **SQL Server** and **PostgreSQL** (switch via `DatabaseProvider` in appsettings)
- Migrations auto-apply on startup via `ApplyDatabaseMigrations()`
- Local default: SQL Server LocalDB; Docker: PostgreSQL
... 
to be continued

• Defina as primeiras skills no AgentSkills: as tarefas mais comuns que você quer delegar. O OpenCode pesquisa nesse local: .opencode/skills/<name>/SKILL.md

---
name: api-endpoint
description: Creates API controller endpoints with proper routing, authorization, documentation. Use when adding new HTTP endpoints, REST APIs, or when the user asks to create a controller or API route.
metadata:
  author: hugo
  version: "1.0"
---

# API Endpoint Skill

This skill guides the creation of API controllers following the project's patterns with MediatR and proper documentation.

## Controller Structure

Location: `Features/{FeatureName}/{FeatureName}Controller.cs`
... 
to be continued

Neste estágio, você ainda está dirigindo: cada prompt é detalhado, cada resultado é revisado linha por linha, e você frequentemente corrige e ajusta. É trabalhoso, mas é aqui que a fundação é construída.

Observe que os exemplos são simples, nesse estágio o objetivo é entender como o fluxo está sendo executado e se as coisas simples aplicadas estão sendo “absorvidas” pelo agente.

Estágio 2: Orientar (D2 → D3)

Com os frameworks básicos no lugar, o agente começa a produzir resultados mais consistentes, mas ainda precisa de orientação forte. Você:

1. Refine a forma como as especificações são geradas com base nos erros que observa. Não se preocupe em ter as definições de projeto em vários lugares, pois são usadas por ferramentas diferentes em momentos diferentes. Ainda há espaço pra melhorar.
2. Adicione exemplos reais do projeto ao System Prompt do OpenCode. Se as especificações estão corretas, mas a implementação saiu torta, verifique onde faltou contexto para a execução do OpenCode.
3. Expanda as skills com cenários mais complexos. Modelos tem limite de contexto, portanto separar bem as skills e rodar em SubAgents é um trunfo.
4. Dar feedback ao agente através de correções no uso do workflow do frameworks

É como fazer coaching com um liderado D2: “Olha, ficou bom aqui, mas nessa parte você precisa seguir esse padrão. Veja esse exemplo.”

Estágio 3: Apoiar (D3 → D4)

Aqui a mágica começa. O agente já produz código dentro do padrão na maioria dos casos. Seu papel muda: em vez de dirigir cada passo, você revisa e valida. Faz code review do que o agente produziu, assim como faria com um desenvolvedor sênior.

Você ainda está presente, mas a dinâmica inverteu: o agente conduz, você apoia.

Estágio 4: Delegar (D4)

Este é o estágio que mudou minha produtividade. Quando o agente atinge a maturidade D4, com AgentSkills, OpenSpec e OpenCode bem estruturados, você pode delegar tarefas com confiança.

Na minha experiência, quando chego nesse estágio, algo impressionante acontece: os resultados dos Modelos de IA ficam muito similares entre si. Respeitam o estilo de codificação, seguem as decisões técnicas do projeto e produzem código que parece ter sido escrito pelo time.

E tudo isso em um tempo drasticamente menor.

O resultado que comprova o modelo

Quero ser bem direto aqui, porque sei que muitos líderes técnicos são (justificadamente) céticos com promessas de produtividade da IA.

Quando você evolui a maturidade dos agentes com esses frameworks, o resultado não é apenas “código mais rápido”. É código consistente. É código que respeita as decisões do projeto. É código que parece ter sido escrito por alguém que entende o contexto.

Na prática, o que observei foi:

• Modelos de IA (GPT Codex e Claude Opus, obrigado Github Copilot por liberar ambos os modelos em uma única assinatura) produzem resultados muito similares quando recebem os mesmos artefatos de maturidade. Isso mostra que a qualidade do output não depende tanto da ferramenta, mas da qualidade do contexto que você fornece
• O estilo de codificação é respeitado, nomenclaturas, padrões de projeto, estrutura de arquivos
• As decisões técnicas são seguidas, a IA não tenta reinventar a roda quando já existe uma roda definida. Mesmo que não esteja tão redonda, situação da maioria dos projetos de software.
• O tempo de desenvolvimento cai drasticamente, tarefas que levariam dias são entregues em horas ou até minutos, com qualidade de review.

A grande sacada não é qual IA você usa. A grande sacada é o processo de evoluir a maturidade do agente a ponto de poder delegar. Assim como na liderança de pessoas, o investimento em maturidade é o que gera autonomia.

A armadilha que todo líder precisa evitar

Existe um erro clássico na Liderança Situacional com pessoas que se repete identicamente com agentes de IA: tratar todos os contextos com o mesmo estilo.

Assim como um líder que só sabe delegar vai frustrar um júnior, e um líder que só sabe dirigir vai sufocar um sênior, você precisa calibrar sua interação com o agente de acordo com o estágio de maturidade em que ele está para aquele projeto específico.

Repare: eu disse “para aquele projeto específico”. Assim como um desenvolvedor pode ser D4 em uma linguagem e D1 em outra, um agente pode ser D4 no seu projeto backend (onde você investiu nos frameworks) e D1 no seu projeto frontend (onde ele tem pouco ou nenhum contexto).

A maturidade não é global. É contextual.

Outra armadilha: achar que o D4 é permanente. Projetos evoluem. Novas decisões de arquitetura são tomadas. Se você não atualiza o OpenSpec, o OpenCode e o AgentSkills, o agente regride. É como um colaborador que parou de receber atualizações e feedback, ele vai ficar desatualizado.

Como começar amanhã

Se você é um líder técnico e quer aplicar esse modelo, aqui vai um caminho prático:

1. Identifique o projeto mais crítico, aquele onde a produtividade do agente teria mais impacto
2. Comece pelo OpenSpec, documente as 5 decisões de arquitetura mais importantes do projeto. Não precisa ser perfeito, precisa existir
3. Depois, crie o OpenCode, registre as 10 convenções de código mais críticas. Inclua exemplos reais do próprio projeto
4. Configure o AgentSkills, defina as 3 tarefas mais comuns que você quer delegar ao agente
5. Teste com Modelos de IA, dê a mesma tarefa para modelos diferentes, com os mesmos artefatos, e compare os resultados
6. Itere, a cada resultado fora do padrão, se pergunte: “O que faltou no OpenSpec, no OpenCode ou no AgentSkills para que ele acertasse?”

Esse ciclo de iteração é exatamente o ciclo de desenvolvimento de um liderado. Cada erro é uma oportunidade de refinar o contexto. E a cada refinamento, o agente sobe um degrau na escada de maturidade.

A liderança que ninguém te ensinou

Quando estudamos Liderança Situacional, ninguém imaginou que um dia aplicaríamos esse modelo a agentes de inteligência artificial. Mas se pararmos para pensar, faz todo sentido.

Liderar é, em essência, sobre desenvolver capacidade em quem você lidera para que, eventualmente, essa pessoa (ou agente) possa atuar com autonomia. O veículo muda, de pessoas para IAs, mas o princípio permanece:

• Contexto gera consistência
• Investimento em maturidade gera autonomia
• O estilo de liderança precisa se adaptar ao nível de maturidade

Os líderes técnicos que vão se destacar nos próximos anos não serão apenas aqueles que sabem usar Claude Code ou GitHub Copilot. Serão aqueles que entendem que a ferramenta é o meio, e a maturidade é o fim. Que sabem construir AgentSkills, OpenSpec e OpenCode (ou ferramentas futuras) de forma estruturada. Que aplicam, conscientemente, os mesmos princípios de liderança que já funcionam com pessoas.

Porque no final das contas, o problema nunca foi a IA. O problema sempre foi a falta de um processo de maturidade.

E isso, caro leitor, é algo que todo bom líder já sabe resolver. Você só precisa aplicar o que já sabe em um novo contexto.

Conclusão: os pontos que importam

Para não perder o fio da meada, aqui vai o resumo do que conversamos:

• A Liderança Situacional (Hersey & Blanchard) define 4 níveis de maturidade (D1 a D4) e 4 estilos de liderança correspondentes (S1 a S4)
• Agentes de IA também têm maturidade, e ela começa em D1 (sem contexto) em todo projeto novo
• Três frameworks aceleram a evolução: AgentSkills (habilidades), OpenSpec (especificações do projeto) e OpenCode (convenções de código)
• A maturidade é contextual, o mesmo agente pode ser D4 em um projeto e D1 em outro
• Quando o agente atinge D4, ferramentas como Claude Code e GitHub Copilot produzem resultados surpreendentemente similares e consistentes com o estilo do projeto
• A grande sacada não é qual IA usar, mas investir no processo de evolução da maturidade do agente

E aí, você já parou para pensar em que estágio de maturidade estão os agentes de IA nos seus projetos? Está dirigindo, orientando, apoiando ou delegando? Deixe sua opinião nos comentários, quero muito ouvir como tem sido a experiência de vocês liderando essas “novas mentes” do time! 👍🚀😃

Artigos relacionados que podem te interessar:

• Arquétipos da Liderança Técnica
• O papel da empresa e dos líderes na evolução de carreira dos liderados
• Contribuidor Individual ou Gestão de Pessoas

Liderança Situacional na Era da IA: Você Já Lidera Agentes e Nem Percebeu was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Esse artigo mostra o conceito, os desafios reais de uma implementação em produção e as decisões de arquitetura que tomamos no NDD Labs ao construir um sistema de webhooks multitenant em .NET 9.

O Que São Webhooks?

Webhooks são callbacks HTTP que permitem que uma aplicação notifique outra quando um evento específico acontece. Enquanto APIs tradicionais funcionam no modelo pull (você pergunta: “tem novidade?”), webhooks funcionam no modelo push (o sistema avisa: “acabou de acontecer algo importante!”).

Polling vs. Webhook

A diferença prática: em um e-commerce com 10.000 pedidos ativos, polling geraria milhares de requisições por minuto, a maioria retornando “nada de novo”. Com webhooks, o sistema só envia notificações quando um pedido realmente muda de status.

Do Conceito à Produção

Entendido o conceito, surge a pergunta prática: como construir um sistema de webhooks que funcione em produção, com múltiplos clientes, segurança real e tolerância a falhas?

Foi exatamente esse desafio que enfrentamos no Labs. Nossos módulos atendem dezenas de produtos, e cada uma precisa de webhooks configuráveis com seus dados completamente isolados. A seguir, as decisões de arquitetura que tomamos e por quê.

Multitenancy: Isolamento na Camada de Dados

O primeiro desafio foi garantir que nenhuma organização visse dados de outra. A solução foi colocar o filtro na camada mais baixa possível: query filters do Entity Framework Core:

// Configuramos o filtro uma vez no DbContext
modelBuilder.Entity<WebhookSubscription>()
    .HasQueryFilter(s => s.OrganizationId == _currentTenant.Id);

// Qualquer query já vem filtrada automaticamente
var subscriptions = await _context.Subscriptions.ToListAsync();
// Retorna apenas subscrições da organização atual

Cada requisição inclui o header X-Organization-Id. Um middleware valida o header, resolve a organização e injeta o contexto de tenant antes que qualquer endpoint execute. Se o header estiver ausente, malformado ou apontar para uma organização inativa, a requisição é rejeitada com 400 Bad Request antes de tocar no banco.

Segurança com HMAC

Implementamos autenticação HMAC-SHA256, o mesmo padrão usado por GitHub, Stripe e Slack. O conceito é simples: funciona como um lacre de segurança em uma encomenda. O remetente lacra o pacote com um código que só ele e o destinatário conhecem. Se o lacre chegar violado, o destinatário sabe que alguém mexeu no conteúdo no caminho.

Na prática, cada webhook enviado inclui uma assinatura criptográfica nos headers (X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-Id) que permite ao receptor validar a autenticidade do payload. A comparação usa FixedTimeEquals, uma comparação time-constant que impede ataques de timing, onde um atacante tenta deduzir a assinatura correta medindo tempos de resposta.

Além da assinatura, o timestamp é validado com tolerância de 5 minutos, prevenindo replay attacks.

Confiabilidade com Retentativas Inteligentes

Falhas acontecem: o endpoint do cliente pode estar temporariamente fora, a rede pode oscilar, um deploy pode reiniciar o serviço. A estratégia para lidar com isso é o backoff exponencial, a lógica é a mesma de tentar ligar para alguém que não atende: você espera um pouco, tenta de novo, espera mais, tenta de novo. Se insistir a cada 2 segundos, vira inconveniente. Se espaçar as tentativas, as chances de encontrar o serviço disponível aumentam sem sobrecarregá-lo.

Na prática: se a primeira tentativa falhar, esperamos 5 minutos. Se falhar de novo, 10. Depois 20, depois 40, até um máximo de 1 hora. Cada cliente pode configurar quantas tentativas quer e qual o intervalo base na própria subscrição, um cliente que precisa de entrega rápida usa intervalos curtos com muitas tentativas; outro que tolera mais latência pode ser menos agressivo.

Processamento Assíncrono com Filas Priorizadas

Todos os webhooks são processados em background. Quando um evento acontece, a requisição apenas enfileira a tarefa e retorna imediatamente. A entrega real acontece em workers paralelos.

Implementamos filas com prioridades: retentativas entram na fila de alta prioridade, webhooks novos na fila de prioridade média. Isso garante que entregas que falharam são reprocessadas antes de novos webhooks, sem bloquear o fluxo.

O sistema usa uma abstração (IWebhookJobPublisher) que permite trocar o backend de processamento via configuração, sem mudança de código, suportando Dapr com Redis Streams para cenários cloud-native e distribuídos.

O Que Aprendemos

Isolamento de dados não se negocia. No início, consideramos filtrar dados na camada de serviço. O risco ficou evidente rápido: bastaria um desenvolvedor esquecer um .Where() para expor dados de um cliente para outro. Mover o filtro para query filters do EF Core eliminou essa classe inteira de bugs, o isolamento acontece independentemente de quem escreve a query.

Assíncrono por padrão, sempre. Nas primeiras versões, tentamos enviar webhooks de forma síncrona durante a requisição. Bastou um endpoint de cliente demorar 10 segundos para responder e toda a cadeia travou. Background jobs com filas priorizadas resolveram o problema e tornaram o tempo de resposta da API previsível.

Retry inteligente resolve a maioria das falhas. Analisando os logs de produção, a grande maioria das falhas de entrega são transitórias, timeouts, 503s temporários, deploys do cliente. O backoff exponencial resolve esses casos automaticamente sem intervenção humana. O retry manual existe para os casos restantes.

Observabilidade não é opcional. Sem o histórico detalhado de entregas, cada investigação de “o webhook não chegou” seria uma caixa preta. Com status, tentativas, response codes e tempos registrados, o diagnóstico se torna objetivo.

Testando Localmente

Para experimentar webhooks durante o desenvolvimento, o webhook.site é uma ferramenta prática: gera URLs temporárias e mostra em tempo real todos os webhooks recebidos, incluindo headers e payload. É útil para validar assinaturas HMAC e estrutura de dados antes de integrar com o endpoint real.

Conclusão

Webhooks parecem simples na superfície, é um POST HTTP com um payload JSON. A complexidade real aparece quando você precisa garantir entrega, isolar dados entre clientes, autenticar payloads e dar visibilidade sobre o que está acontecendo.

Se você está construindo integrações entre sistemas, comece pelo caso mais simples e adicione camadas (retry, HMAC, observabilidade) conforme a necessidade real aparecer. Over-engineering no início custa caro; ausência dessas camadas em produção custa mais.

O sistema que construímos no Labs está pronto e segue em evolução.

Seu Sistema Ainda Depende de Polling? Como construímos webhooks multitenant no Labs was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O ponto é que essas dependências viram parte do seu sistema. Se uma biblioteca fica desatualizada, é abandonada ou passa a ter falhas de segurança, a aplicação pode ficar exposta. E como surgem vulnerabilidades novas todos os dias, acompanhar isso manualmente não escala: vira um trabalho constante de “caça a CVE”, conferência em site, planilha, relatório… e, no final, pouca previsibilidade.

Para resolver isso, uma abordagem bem sólida é usar ferramentas como o Dependency-Track. A ideia é simples:

1. Primeiro eu gero um SBOM do projeto
2. Depois eu uso o Dependency-Track para analisar esse SBOM de forma centralizada e contínua

O que é o Dependency-Track?

O Dependency-Track é a ferramenta que eu uso para ter visão centralizada das dependências do projeto e do risco que elas trazem.

Você entrega para ele um SBOM (por exemplo no padrão CycloneDX) e ele transforma isso em algo prático: mostra quais bibliotecas o sistema usa e quais delas têm vulnerabilidades conhecidas, sem precisar ficar caçando informação em relatório, site ou planilha.

Na prática, ele serve para:

• Enxergar rapidamente o que está vulnerável em cada projeto;
• Priorizar o que é mais crítico (o que precisa de ação primeiro);
• Acompanhar ao longo do tempo se o risco foi resolvido conforme você atualiza versões e releases.

O que é o SBOM?

SBOM é como um “rótulo de ingredientes” do software: ele lista tudo o que a aplicação usa (bibliotecas e versões), incluindo dependências transitivas quando a ferramenta consegue enxergar.

Para padronizar esse “rótulo”, existe o CycloneDX (CDX), que define um formato bem conhecido para SBOM. Uma forma simples de pensar é:

• SBOM é a ideia (a lista de componentes)
• CycloneDX é o modelo (o formato) dessa lista, para que qualquer ferramenta consiga ler e interpretar do mesmo jeito

Na prática, eles se complementam assim: eu gero o SBOM no formato CycloneDX e consigo integrar essa informação automaticamente em ferramentas como o Dependency-Track.

Ganhos na prática

• Visibilidade rápida do risco: em minutos eu sei quais projetos estão expostos e onde está o problema.
• Menos ruído e mais organização: sai a dependência de planilhas, relatórios soltos e conferência manual.
• Prioridade clara: fica fácil separar o que é crítico do que pode esperar.
• Correção com mais confiança: quando atualizo uma biblioteca, consigo confirmar se o risco foi resolvido e manter um histórico do que mudou.

Como o Dependency-Track é utilizado na prática?

A forma mais comum de usar o Dependency-Track no dia a dia é organizar por projeto e manter o SBOM sendo enviado automaticamente pelo CI/CD.

Considerações finais

Dependências são inevitáveis em software moderno e quando você passa a enxergar bibliotecas como parte do risco do produto, o SBOM deixa de ser burocracia e vira um ativo: ele registra exatamente o que está rodando em cada release.

O Dependency-Track entra como a peça que transforma esse registro em decisão: centraliza a visão, reduz o esforço de correlação manual e mantém histórico para responder perguntas que realmente importam. O maior ganho aparece quando isso vira rotina via CI/CD: toda entrega atualiza o SBOM, o risco é reavaliado automaticamente e o time consegue priorizar com base em severidade e impacto, não em sensação.

No fim, não é sobre ferramenta e sim sobre ter processo e rastreabilidade para tratar risco de dependências como parte do ciclo normal de entrega com previsibilidade, evidência e menos ruído.

Dependency-Track e SBOM: gestão de vulnerabilidades em dependências was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

E é aí que surge um tipo de dúvida que parece simples, mas costuma ser bem trabalhosa de responder:

Quando não existe um lugar único para consolidar tudo, o histórico se perde, o time perde tempo comparando saídas de scanners e a confiança no processo cai.

Onde o DefectDojo entra

Uma das opções mais sólidas para endereçar esse cenário é o DefectDojo. Pense nele como um painel único para centralizar achados: em vez de cada scanner gerar um relatório isolado (e ninguém saber por onde começar), você consolida tudo em um lugar só.

Na prática, o DefectDojo:

• importa resultados de várias fontes (SAST, DAST, SCA, container, IaC, secrets etc.)
• organiza e reduz o ruído (duplicidades)

O ganho principal é visibilidade: fica mais fácil enxergar o que é mais crítico, quem é o responsável, em qual produto/ambiente está o risco e o que já foi resolvido.

O que você ganha na prática

Com isso, podemos:

• Centralizar tudo em um único lugar, em vez de ficar analisando relatório por relatório;
• Reduzir duplicidade e ruído, evitando que o mesmo problema apareça várias vezes como se fossem achados diferentes;
• Priorizar com clareza, separando o que é crítico do que pode esperar;
• Manter histórico por projeto e por versão, para saber o que entrou, o que foi tratado e o que continua pendente.

E, no dia a dia, isso se traduz em:

• Visão única de vulnerabilidades por projeto/repositório;
• Menos retrabalho com planilhas, PDFs e relatórios espalhados;
• Correções mais certeiras, porque fica claro o que realmente importa e o que foi resolvido entre releases.

Relatórios de quais ferramentas eu consigo importar?

O DefectDojo suporta diversas integrações e formatos de importação. A lista oficial (mantida pela comunidade) está aqui:

DefectDojo — Ferramentas Suportadas

Como o DefectDojo é usado na prática

A forma mais comum de usar o DefectDojo no dia a dia é padronizar uma hierarquia e automatizar a entrada dos scans via CI/CD. Isso evita que o uso vire “manual demais” e garante consistência entre times.

1) Estrutura inicial (uma vez por organização/produto)

1. Criar o Product Type
   Uma categoria que agrupa produtos por domínio/vertical (ex.: Cargo​, Elog​, IP​). Aqui, um padrão bem prático é usar o nome da vertical como Product Type, já que cada vertical pode ter vários repositórios.
2. Criar o Product
   Aqui é o “alvo” real que você quer gerenciar (ex.: nddCargo​, nddElog​, nddIP​). Um padrão que costuma facilitar muito é definir o nome do Product igual ao nome do repositório no TFS/Azure DevOps (ou Git), porque a busca e o vínculo com o projeto ficam óbvios.

2) Ciclo de trabalho (por release, sprint ou período)

Como isso entra no CI/CD

O fluxo mais comum fica bem objetivo:

Considerações finais

O DefectDojo não “resolve segurança” sozinho, ele resolve um problema bem específico e muito comum: falta de centralização e rastreabilidade. Quando cada ferramenta gera um relatório isolado, o time perde tempo correlacionando achados, lidando com duplicidade e tentando provar evolução entre releases. Ao consolidar tudo em um único lugar, você transforma resultados soltos em dados concretos.

O maior ganho aparece quando o uso é consistente e automatizado. Padronizar a hierarquia (Product Type -> Product -> Engagement) e enviar os scans pelo CI/CD faz com que o histórico deixe de depender de memória, planilha ou artefatos de pipelines.

No fim, a ferramenta vira mais valiosa quando é tratada como parte do processo: menos ruído, mais previsibilidade e um backlog de segurança mais claro, alinhado com a realidade do desenvolvimento e com o ritmo de entregas do time.

DefectDojo: centralizando achados de segurança e mantendo histórico entre releases was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O problema aparece quando essa infraestrutura vira rotina.

Quando você precisa repetir o mesmo desenho em outro ambiente (dev/hml/prod), manter padrões, auditar “quem mudou o quê” e recriar tudo com segurança (especialmente em POCs que nascem e morrem o tempo todo), o portal começa a virar um gargalo. A cada ajuste feito “só aqui”, os ambientes inevitavelmente divergem. E, quando você percebe, a diferença entre dev e prod não é mais “configuração”: virou um conjunto de decisões implícitas que ninguém consegue explicar direito.

É aqui que Terraform muda o jogo. E, quando o projeto cresce, Terragrunt entra como uma camada que resolve um problema muito específico: reduzir repetição, organizar estados e padronizar ambientes sem você copiar e colar providers.tf​, backend.tf​, versions.tf​ em todo lugar.

Infraestrutura como código (de verdade)

A ideia continua simples: infraestrutura vira código.

Em vez de clicar no portal, você descreve o que precisa existir rede, AKS, Key Vault, ACR, VMs, discos e aplica isso de forma padronizada e rastreável.

O ganho real de IaC não é “criar mais rápido”. É:

• eliminar drift (a divergência silenciosa entre ambientes)
• dar previsibilidade (a mesma entrada gera o mesmo resultado)
• criar histórico confiável (git + revisão + rastreabilidade)
• reduzir risco em mudanças (plan antes do apply, revisão antes do merge)

O ponto é que, com o tempo, o desafio deixa de ser “escrever Terraform” e passa a ser “manter dezenas de stacks consistentes”. E é justamente aí que Terragrunt brilha.

Por que Terragrunt entra na conversa

Terragrunt não substitui Terraform. Ele organiza o uso do Terraform.

Na prática, ele resolve três dores comuns em ambientes Azure que crescem rápido:

• ​DRY de verdade​: você para de repetir provider/backend/versions em toda stack.
• ​Estados bem organizados​: um state por componente, com naming consistente.
• ​Orquestração por dependências​: você aplica infraestrutura em ordem (e com segurança) usando outputs como contratos.

O resultado é uma estrutura que escala melhor quando você começa a ter fundação, plataforma e workloads evoluindo ao mesmo tempo.

Exemplo prático: DefectDojo e Dependency-Track (infra + banco)

Ao implantar DefectDojo e ​Dependency-Track​, existe uma base mínima no Azure antes da aplicação em si:

• Resource Group
• Rede (VNET, subnets, NSGs)
• VM Linux dedicada para PostgreSQL
• Public IP / DNS (quando necessário)
• Storage
• AKS

Com Terraform + Terragrunt, isso vira um fluxo claro:

1. Provisiona a infraestrutura base (rede, compute, storage, AKS).
2. Entra o Ansible para instalar e configurar o PostgreSQL (extensões, parâmetros, acesso, bancos e usuários).
3. A camada de aplicação vem depois (Helm, manifests, pipelines), consumindo outputs e secrets de forma padronizada.

A divisão de responsabilidades continua objetiva:

• ​Terraform​: ciclo de vida da infraestrutura e estado.
• ​Terragrunt​: organização, padronização, backends, inputs por ambiente e dependências.
• ​Ansible​: configuração do sistema e do software de forma idempotente.

Organização do repositório: módulos e stacks (com Terragrunt)

Uma organização prática e escalável separa:

• o que é reutilizável (módulos Terraform)
• do que é específico de ambiente (stacks com Terragrunt)

A lógica lembra a separação entre “código reutilizável” e “orquestração”.

Estrutura base (exemplo)

infra/
├── catalog/
│   └── modules/
│       ├── azurerm_resource_group/
│       ├── azurerm_virtual_network/
│       ├── azurerm_subnet/
│       ├── azurerm_public_ip/
│       ├── azurerm_network_interface/
│       ├── azurerm_linux_virtual_machine/
│       ├── azurerm_managed_disk/
│       ├── azurerm_key_vault/
│       ├── azurerm_storage_account/
│       ├── azurerm_container_registry/
│       └── azurerm_kubernetes/
│
└── stacks/
    └── nde/
        ├── root.hcl
        ├── env.hcl
        ├── dev/
        │   ├── foundation/
        │   │   └── network/
        │   │       └── terragrunt.hcl
        │   ├── platform/
        │   │   └── keyvault/
        │   │       └── terragrunt.hcl
        │   └── workloads/
        │       └── defectdojo/
        │           ├── compute/
        │           │   └── terragrunt.hcl
        │           └── aks/
        │               └── terragrunt.hcl
        ├── hml/
        │   └── ...
        └── prd/
            └── ...

Como ler essa estrutura

catalog/modules/
Módulos Terraform reutilizáveis. Pequenos, com contrato claro (inputs/outputs), fáceis de versionar e reaproveitar.

stacks/
O “live” do Terragrunt: cada pasta representa uma unidade de execução com seu próprio terragrunt.hcl​ apontando para um módulo e definindo inputs, dependências e estado.

root.hcl / env.hcl
Arquivos de “configuração base” que evitam repetição: backend, provider, tags, naming, subscription/tenant, padrões de rede e qualquer coisa compartilhada.

O coração do Terragrunt: herança e padrão de state

Uma prática que funciona muito bem é ter um root.hcl​ com:

• ​remote_state​ centralizado (Azure Storage)
• ​generate​ para provider e versões
• padrões comuns (tags, naming, features)
• convenções para o key do state baseado no caminho

Exemplo de root.hcl​:

locals {
  project = "nde"
}

remote_state {
  backend = "azurerm"
  config = {
    resource_group_name  = "rg-tfstate"
    storage_account_name = "sttfstateprod001"
    container_name       = "tfstate"
    key                  = "${path_relative_to_include()}/terraform.tfstate"
  }
}

generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
provider "azurerm" {
  features {}
}
EOF
}

generate "versions" {
  path      = "versions.tf"
  if_exists = "overwrite_terragrunt"
  contents  = <<EOF
terraform {
  required_version = ">= 1.6.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.0.0"
    }
  }
}
EOF
}

E um env.hcl​ para variáveis do ambiente:

locals {
  location    = "eastus"
  environment = "dev"
  tags = {
    env     = "dev"
    project = "nde"
  }
}

Uma stack por componente (e estados pequenos)

No Terragrunt, cada pasta com terragrunt.hcl​ normalmente representa:

• um módulo Terraform
• um state isolado
• uma unidade que faz sentido evoluir e aplicar separadamente

Isso ajuda muito quando você precisa:

• reaplicar só um pedaço
• dar rollback com menor blast radius
• evoluir rede e compute em ritmos diferentes
• reduzir tempo de plan/apply

Dependências como contratos (sem acoplamento implícito)

Quando uma stack depende de outra, Terragrunt permite consumir outputs como contrato explícito.

Exemplo: o AKS depende da rede.

​stacks/nde/dev/foundation/network/terragrunt.hcl​:

include "root" {
  path = find_in_parent_folders("root.hcl")
}

locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl")).locals
}

terraform {
  source = "${get_repo_root()}//catalog/modules/azurerm_virtual_network"
}

inputs = {
  location = local.env.location
  tags     = local.env.tags
}

​stacks/nde/dev/workloads/defectdojo/aks/terragrunt.hcl​:

include "root" {
  path = find_in_parent_folders("root.hcl")
}

locals {
  env = read_terragrunt_config(find_in_parent_folders("env.hcl")).locals
}

dependency "network" {
  config_path = "../../../foundation/network"
}

terraform {
  source = "${get_repo_root()}//catalog/modules/azurerm_kubernetes"
}

inputs = {
  location      = local.env.location
  tags          = local.env.tags
  subnet_id     = dependency.network.outputs.snet_aks_id
}

Isso evita o “estado mental” de lembrar IDs na mão, evita terraform_remote_state​ espalhado e deixa a ordem de execução explícita.

Executando por camadas com segurança

Com Terragrunt, você consegue aplicar por nível:

• ​foundation​ primeiro
• depois platform​
• depois workloads​

E consegue fazer isso com:

• ​terragrunt run-all plan​
• ​terragrunt run-all apply​

Cada componente com seu state, e as dependências guiando a ordem quando necessário.

Ambientes (dev / hml / prd) sem workspaces

O padrão mais previsível continua sendo:

• pastas separadas por ambiente
• mesmo código, inputs diferentes
• state isolado por ambiente
• backend padronizado e automático

Isso reduz muito o risco de “aplicar no lugar errado” e facilita auditoria e rollback.

O que foi configurado para DefectDojo e Dependency-Track

Para essas duas aplicações, normalmente precisamos de:

• bancos dedicados (ex.: defectdojo​, dependencytrack​)
• usuários dedicados para cada aplicação
• permissões corretas
• ajustes e acesso (ex.: pg_hba.conf​, listen_addresses​, parâmetros)

Com Terraform + Terragrunt, a infraestrutura que suporta isso vira padrão. Com Ansible, a configuração do PostgreSQL vira código versionado. Se amanhã precisar recriar tudo, o processo deixa de depender de “memória” e vira execução.

Ganhos na prática

Os ganhos mais claros ao organizar Terraform com Terragrunt foram:

• menos repetição de arquivos e configurações entre stacks
• estados menores, mais rápidos de planejar e aplicar
• padronização forte entre ambientes
• dependências explícitas via outputs (contratos claros)
• execução por camadas, com menos risco
• reuso real: mesmos módulos, inputs por ambiente

Resumo final

Terraform resolve o “o que” da infraestrutura. Terragrunt resolve o “como manter isso organizado” quando o ambiente cresce.

No caso de DefectDojo e ​Dependency-Track​, essa combinação ajudou a criar uma base consistente no Azure rede, compute, storage e AKS e permitiu recriar ambientes em minutos, algo essencial em POCs e ciclos de teste frequentes. No fim, a infraestrutura fica mais previsível, o estado fica mais controlado e o repositório deixa de virar uma coleção de arquivos repetidos.

Terraform no Azure com Terragrunt: menos repetição, mais previsibilidade was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O Ansible costuma ser uma das soluções mais diretas e eficientes para esse cenário. A ideia é simples: você descreve o estado desejado do servidor pacotes, configurações, serviços e permissões e o Ansible aplica isso de forma automática e padronizada em todos os alvos. Assim, você deixa de acessar servidor por servidor para repetir o mesmo roteiro manualmente.

Como o Ansible é utilizado na prática?

Na prática, o Ansible entra quando você quer transformar uma configuração feita “na mão acessar a VM, instalar pacotes, editar arquivos, reiniciar serviços em um processo ​repetível, versionado e consistente​.

Em vez de cada ambiente ser configurado de forma diferente, você descreve o estado desejado em playbooks e ​roles​, versiona isso em um repositório e executa sempre que precisar, em qualquer servidor que siga o padrão do inventário.

Um exemplo real é a implantação de ferramentas como DefectDojo e ​Dependency-Track​. Para colocar essas aplicações em produção com estabilidade, foi necessário preparar um PostgreSQL completo: bancos, usuários, permissões, parâmetros de performance e acesso remoto. Esse é exatamente o tipo de tarefa que o Ansible resolve bem: instalar e manter o banco de forma padronizada, reproduzível e rápida.

Se, em outro momento, a equipe precisar aplicar a mesma automação em um novo ambiente por exemplo, criar uma nova VM de PostgreSQL para outro projeto basta apontar o inventário e executar. Em poucos minutos, o banco está pronto, seguindo o mesmo padrão.

Exemplo: configurando PostgreSQL com Ansible (visão prática)

Quando você prepara um PostgreSQL manualmente, o fluxo costuma ser mais ou menos assim:

1. Instalar o PostgreSQL no servidor
2. Criar o banco e o usuário da aplicação
3. Ajustar permissões e parâmetros do servidor
4. Liberar acesso de rede (pg_hba.conf​)
5. Reiniciar o serviço
6. Validar a conexão

Com Ansible, esses passos deixam de ser um “checklist humano e viram uma execução única, automatizada e previsível.

Estrutura básica

Uma organização simples e que escala bem separa claramente as responsabilidades dentro de um projeto Ansible:

• inventories/
  Lista os servidores por ambiente (dev​, hml​, prod​) e concentra variáveis associadas a hosts e grupos.
• playbooks/
  Orquestram a execução: definem o que será aplicado, em quais hosts e em qual ordem.
• roles/
  Contêm automações reutilizáveis, organizadas por domínio técnico, como a role de PostgreSQL.

Essa separação facilita a leitura, reduz acoplamento e torna a automação mais previsível conforme o projeto cresce.

Modelo mental aplicado à role de PostgreSQL

Dentro da role de PostgreSQL, ajuda muito pensar em responsabilidades bem definidas, executadas de forma ordenada. Um modelo mental simples é dividir a automação internamente em etapas como:

• Instalação e configuração do serviço
• Criação de bancos, usuários e permissões
• ​Ajustes de performance e tuning​, como max_connections​ e shared_buffers​
• ​Configuração de acesso​, incluindo pg_hba.conf​ e listen_addresses​

Essas etapas não são papéis separados, mas ​camadas internas da mesma role​, o que mantém o controle de estado do serviço centralizado e consistente.

Estrutura de pastas (exemplo)

roles/
└── postgresql/
    ├── defaults/
    │   └── main.yml
    ├── vars/
    │   └── main.yml
    ├── handlers/
    │   └── main.yml
    ├── templates/
    │   ├── postgresql.conf.j2
    │   └── pg_hba.conf.j2
    ├── files/
    ├── tasks/
    │   ├── main.yml
    │   ├── install.yml
    │   ├── service.yml
    │   ├── config.yml
    │   ├── access.yml
    │   ├── databases.yml
    │   └── tuning.yml
    └── meta/
        └── main.yml

Visão geral da estrutura

• inventories/
  Definem os ambientes e centralizam variáveis por grupo, permitindo diferenças controladas entre dev​, hml​ e prod​.
• playbooks/
  Funcionam como ponto de entrada da automação, chamando a role correta para os hosts adequados.
• roles/
  Encapsulam toda a lógica necessária para gerenciar um serviço específico, de forma organizada e reutilizável.

Dentro da role

• defaults/
  Contêm valores padrão das variáveis, pensados para serem sobrescritos por ambiente quando necessário.
• tasks/
  Implementam as etapas da automação, separadas por responsabilidade para facilitar manutenção e evolução.
• handlers/
  Definem ações reativas, como restart ou reload do serviço, executadas apenas quando algo realmente muda.

O que foi configurado para DefectDojo e Dependency-Track

Para essas duas aplicações, normalmente foi necessário configurar:

• ​Bancos dedicados​, como defectdojo​ e dependencytrack​
• Usuários dedicados para cada aplicação
• Permissões corretas nos schemas
• Ajustes de acesso e configuração (pg_hba.conf​, listen_addresses​, parâmetros do PostgreSQL)

Com Ansible, tudo isso vira código versionado. Se amanhã for preciso recriar o ambiente, basta executar o playbook e o banco sai exatamente igual, sem depender de memória, anotações soltas ou procedimentos manuais.

Ganhos na prática

Os principais benefícios de automatizar a camada de PostgreSQL com Ansible foram:

• Possibilidade de reaplicar a configuração sempre que necessário
• Redução drástica do tempo de setup e ajustes
• ​Menos incidentes​, graças à consistência entre servidores
• ​Escala com controle​, mesmo com muitos ambientes
• Menos erros manuais e menos variação entre máquinas
• Mais agilidade na implantação de aplicações
• ​Documentação viva​, onde o código mostra exatamente o que foi feito

Resumo final

No caso do DefectDojo e do ​Dependency-Track​, o Ansible foi essencial para preparar um PostgreSQL consistente com bancos, usuários, permissões e acesso configurados garantindo que o ambiente pudesse ser recriado em minutos sempre que necessário. Isso foi especialmente importante porque o projeto começou como uma ​POC​, exigindo recriações frequentes para testes e ajustes.

Com inventários, playbooks e roles bem organizados, o resultado é um processo mais rápido, confiável e versionado. No fim, o próprio código se torna a melhor documentação do ambiente.

Ansible: ganhos de escala ao automatizar a configuração de servidores was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

O problema aparece quando o empresa/projeto cresce e você passa a ter dezenas (ou centenas) de repositórios. De repente, você tem o cenário clássico:

• etapas parecidas em todo lugar (build, testes, scans, publish, deploy)
• implementadas com pequenas variações
• copiadas e coladas ao longo do tempo
• sem um padrão claro além do “funciona”

O resultado é previsível: manutenção difícil, copy/paste infinito e mudanças simples virando trabalho duplicado. Pior ainda quando o time precisa ajustar o processo de CI (trocar tecnologia, mudar etapa de build/test/scan, alterar padrão de deploy): você acaba entrando repositório por repositório para corrigir pipeline, gerando commits de “ajuste de infraestrutura” misturados com o código da aplicação.

Para evitar isso, eu gosto de trabalhar com um princípio simples: o repositório da aplicação não deveria “conter” o pipeline completo. Ele deveria apenas “consumir” um pipeline padrão.

A abordagem é separar a “infra de pipeline” em um repositório central e dividir a responsabilidade em templates por etapa. O projeto consumidor só chama esses templates e passa parâmetros.

Com isso, podemos:

• Reutilizar etapas, evitando duplicação de YAML.
• Padronizar o processo, para todo projeto seguir o mesmo fluxo.
• Evoluir rápido, porque uma melhoria no template vale para todos.
• Reduzir falhas, pois o pipeline fica previsível e revisado.

Benefícios

• Menos retrabalho e menos copy/paste entre repositórios.
• Pipelines consistentes, fáceis de manter e de auditar.
• Mudanças mais rápidas, com melhoria centralizada nos templates (uma mudança, impacto em todos).

Como os templates são utilizados na prática?

O time de engenharia vem trabalhando forte em ferramentas e padrões de segurança para facilitar a vida dos times de DevOps nas verticais. Para isso, foram desenhados templates que padronizam o processo e aceleram migrações, reduzindo retrabalho e evitando variações desnecessárias entre repositórios.

Aqui vou usar o NDE como exemplo para mostrar como montar um repositório de templates e pipelines e como reutilizá-los no dia a dia.

1) Criando o repositório central de DevOps

A ideia é ter um repositório único para concentrar tudo que é “infra de pipeline”: pipelines, templates, stages, steps, scripts auxiliares e documentação rápida. O objetivo é reduzir a manutenção para um lugar só e evitar espalhar YAML por vários repositórios.

Exemplos de nome: devsecops​, devops-pipelines​, templates-pipelines​.

2) Organizando pastas e templates

Essa parte tem gosto pessoal, mas um modelo que costuma funcionar bem é separar por:

• projeto/domínio (quando você tem variações relevantes)
• tipo de pipeline (CI e CD)
• nível de abstração (stages vs step templates)

Duas regras práticas que ajudam muito:

• Stage = macro fluxo (source, build, tests, security, publish, deploy)
• Step template = micro padrão (“install tool”, “run scan”, “publish artifact”), usado dentro de jobs/stages

Exemplo de estrutura objetiva:

devops-pipelines/
└── pipelines/
    ├── NOME_DO_PROJETO/
    │   ├── ci/
    │   │   ├── default.yml
    │   │   └── stages/
    │   │       ├── 01-source-stage.yml
    │   │       ├── 02-build-stage.yml
    │   │       ├── 03-tests-stage.yml
    │   │       ├── 04-security-stage.yml
    │   │       └── 05-publish-stage.yml
    │   └── cd/
    │       ├── default.yml
    │       └── stages/
    │           ├── 01-deploy-stage.yml
    │           └── 02-smoke-stage.yml
    ├── templates/
    │   ├── build/
    │   ├── deploy/
    │   └── scans/
    └── scripts/

3) Criando um pipeline default do projeto (CI)

O default.yml​ é o arquivo que descreve o CI completo chamando os stages.

Exemplo pipelines/default/ci/default.yml​:

stages:
- template: stages/01-source-stage.yml
  parameters:
    agentOS: Linux

A partir daqui, o pipeline “principal” fica pequeno e estável: ele só monta a orquestração. O detalhe de cada etapa vive nos templates de stage e step.

4) Exemplo de stage template (Source)

Exemplo pipelines/default/ci/stages/01-source-stage.yml​:

parameters:
- name: agentOS
  type: string

stages:
- stage: SourceStage
  displayName: '01 - Source Analysis'
  jobs:
  - job: SourceScans
    displayName: 'Run source security scans'
    steps:
    - template: /templates/scans/install-nde.yml@ndetemplates
      parameters:
        feedToken: '$(NDE_FEED_TOKEN)'
        agentOS: ${{ parameters.agentOS }}

    - template: /templates/scans/nde-gitleaks.yml@ndetemplates
      parameters:
        outputDir: '$(Build.ArtifactStagingDirectory)/reports'
        target: '$(Build.SourcesDirectory)'
        outputType: 'json'
        ddUrl: '$(DD_URL)'
        ddKey: '$(DD_TOKEN)'
        engagementId: '$(DD_ENGAGEMENT_ID)'
        agentOS: ${{ parameters.agentOS }}

    - template: /templates/scans/nde-trivy.yml@ndetemplates
      parameters:
        outputDir: '$(Build.ArtifactStagingDirectory)/reports'
        target: '$(Build.SourcesDirectory)'
        outputType: 'json'
        cacheDir: '$(Pipeline.Workspace)/.cache_nde'
        ddUrl: '$(DD_URL)'
        ddKey: '$(DD_TOKEN)'
        engagementId: '$(DD_ENGAGEMENT_ID)'
        agentOS: ${{ parameters.agentOS }}

    - template: /templates/scans/nde-semgrep.yml@ndetemplates
      parameters:
        outputDir: '$(Build.ArtifactStagingDirectory)/reports'
        target: '$(Build.SourcesDirectory)'
        outputType: 'json'
        ddUrl: '$(DD_URL)'
        ddKey: '$(DD_TOKEN)'
        engagementId: '$(DD_ENGAGEMENT_ID)'
        agentOS: ${{ parameters.agentOS }}

Note que, em cada template, aparece o sufixo @ndetemplates​. Isso indica que o template está vindo de um repositório de templates referenciado via resources.repositories​.

5) Consumindo os templates em outro repositório (na prática)

No repositório da vertical (ex.: nddCargo​), você não copia templates. Você referencia o repositório central e “puxa” o pipeline pronto.

Exemplo pipelines/ci.yml​ no repositório consumidor:

trigger:
- master

variables:
- group: NDE-Settings

resources:
  repositories:
  - repository: ndetemplates
    type: git
    name: NDE/devsecops
    ref: master
    endpoint: ndetemplates

  - repository: templates
    type: git
    name: devsecops
    ref: main

stages:
- template: pipelines/default/ci/default.yml@templates

Pontos de atenção que normalmente evitam dor:

• Se ndetemplates​ estiver em outra collection/projeto, é comum precisar configurar um Service Connection no projeto consumidor e referenciar em endpoint​.
• Centralizar configurações em um Variable Group (ex.: NDE-Settings​) reduz duplicação e mantém o pipeline do projeto mais limpo. Exemplos de variáveis: DD_URL​, DD_TOKEN​, DD_ENGAGEMENT_ID​.
• Os templates de scan ficam no repositório ndetemplates​, e o pipeline “montador” (default/stages) fica no repositório templates​. Essa separação permite evoluir componentes independentemente, quando fizer sentido.

Considerações finais

Esse modelo muda o jogo principalmente por um motivo: ele separa o que é código de produto do que é infra de entrega. O repositório da aplicação volta a ter um pipeline “leve”, enquanto a evolução do processo (build, testes, scans, publish e deploy) acontece em um lugar único, com revisão, padrão e controle.

Na prática, você troca o “cada repo faz do seu jeito” por um fluxo previsível, onde:

• melhorias viram mudança centralizada, não uma maratona de PRs em dezenas de repositórios;
• o time consegue padronizar sem engessar, porque os templates aceitam parâmetros e variações controladas;
• auditoria e manutenção ficam mais simples, já que o pipeline deixa de ser uma colcha de retalhos.

No fim, o ganho não é só reduzir YAML duplicado. É ganhar escala com governança: evoluir rápido, sem perder consistência, e com uma base que permite melhorar continuamente sem quebrar o ecossistema de repositórios.

Pipelines C.I e C.D padronizados com templates: menos YAML duplicado, mais velocidade para evoluir was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Kubernetes (K8s)

Kubernetes, também conhecido como K8s, é um sistema open source utilizado para automatizar a implantação, o dimensionamento e o gerenciamento de aplicativos em contêiner.

Por ser open source, existe a liberdade de utilizar o K8s em seu próprio cluster local, em uma arquitetura híbrida ou em qualquer provedor público de computação em nuvem, permitindo que você mova sem esforço suas aplicações para onde quiser.

Na nuvem, costumamos trabalhar com o AKS (Azure Kubernetes Service) aqui na NDD, mas existem outras alternativas como GKE (Google Kubernetes Engine) e EKS (Amazon Elastic Kubernetes Service). Embora o uso dessa ferramenta integrada na nuvem seja o mais comum, neste artigo vamos analisar o uso de K8s no ambiente local.

Por que rodar K8s localmente?

Rodar K8s localmente pode ser útil em casos de prototipação, desenvolvimento em fase inicial ou preparação para o ambiente de produção, mas é especialmente valioso para fins de estudo. Rodar K8s em um ambiente local torna a experiência de primeiro contato com essa ferramenta muito mais simples e interativa, eliminando risco de gerar custos adicionais na nuvem e afetar o software já em produção sem precisar sacrificar funcionalidade.

Ferramentas para rodar localmente

Existem diversas ferramentas que facilitam o processo de instalação e execução de K8s no seu computador. Seguem abaixo algumas delas:

• minikube;
• K3s;
• microk8s;
• k0s;
• kind e k3d que reaproveitam os conceitos de Docker;
• CodeReady Containers (CRC) e Minishift que utilizam OpenShift.

Dentre elas, escolhi duas específicas para me aprofundar por dois motivos: maior apoio da comunidade, importante quando precisar de documentação ou outro tipo de ajuda, e especializações diferentes para que consigamos cobrir diferentes casos de uso com ao menos uma dessas ferramentas.

minikube

O minikube foi feito para ser a melhor ferramenta para desenvolvimento de aplicações com K8s local e para suportar todas as funcionalidades aplicáveis do K8s. Por esse motivo, é bem completo em suas funcionalidades e deve atender a maioria dos casos de uso.

Destaques:

• Suporta a última versão do K8s.
• Suporta múltiplas plataformas (Linux, macOS e Windows).
• Suporta processadores gráficos para desenvolvimento de IA (NVidia, AMD, Apple).
• Pode ser implantado como uma VM, um contêiner ou sem virtualização alguma.
• Suporta múltiplos runtimes de contêiner (CRI-O, containerd, docker).
• Endpoint direto da API para rápido carregamento e construção das imagens.
• Funcionalidades avançadas como LoadBalancer, montagem de sistemas de arquivos, FeatureGates e políticas de rede.
• Suporta Addons com fácil instalação.
• Suporta ambientes comuns de CI.

Para instalar o minikube, siga o guia de instalação que cobre os requisitos necessários, o processo de instalação e passos iniciais para gerenciar seu cluster K8s.

K3s

O K3s foi feito originalmente por Rancher Labs com o objetivo principal de rodar em ambientes com poucos recursos, como é a necessidade de dispositivos de internet das coisas, funcionando até em um Raspberry Pi. Para isso, o K3s é bem leve, reduzindo dependências e aumentando a facilidade de atualizar, executar e atualizar automaticamente um cluster de K8s em produção.

Destaques:

• É disponibilizado através de um único arquivo binário de menos de 70MB.
• Suporte padrão ao SQLite3, suportando ainda Etcd3, MariaDB, MySQL, e Postgres.
• Encapsula K8s e outros componentes em um único, simples executável.
• É seguro com configurações padrões apropriadas para ambientes com poucos recursos.
• Tem dependências mínimas de sistemas operacionais, apenas a montagem de um kernel e cgroups é necessária.
• Simplifica operações do K8s com gerenciamentos de certificados TLS, conexões entre nós e um cluster etcd integrado, além de aplicar recursos de manifestos locais em tempo real conforme eles são modificados.

Para instalar o K3s basta seguir o guia de inicialização rápida. Existe uma alternativa para facilitar esse processo ainda mais: caso você já possua o Rancher Desktop instalado, basta ativar as funcionalidades de K8s. Isso pode ser feito no instalador do Rancher Desktop, que já deixa seu ambiente funcional com pouco esforço.

Comparação

Ambos foram feitos para criar clusters completos de K8s de um único nó em um único servidor ou máquina virtual, ideal para desenvolvimento local. Também são de fácil instalação e tem processos facilitados e amplamente documentados.

Quanto às vantagens, K3s se destaca por ser leve, considerando seu baixo consumo de recursos e requisitos menores, com funcionalidades prontas sem precisar de configurações extras. Já o minikube é mais personalizável através dos addons e possui algumas funcionalidades que se aproximam mais de um ambiente de produção.

Já quanto às desvantagens, o minikube acaba consumindo mais recursos e apresenta um tempo de inicialização mais alto enquanto o K3s, por ser tão leve, não possui todo o conjunto de funcionalidades de um ambiente tradicional de K8s.

Qual deles escolher?

Ambas as opções são bem suportadas pela comunidade, possuem ampla documentação e dão conta do recado. Por esse motivo, são as soluções mais adotadas na indústria e podem ser usadas para os cenários em que se especializam.

Caso você já tenha o Rancher Desktop instalado, começar a usar o K3s é muito simples, além de ser um ambiente mais leve. Porém, caso queira explorar mais funcionalidades, o minikube pode ser a melhor opção para você.

Como desenvolver nesse novo ambiente K8s local?

Além da execução das aplicações, também é possível realizar seu desenvolvimento diretamente em um ambiente K8s local. Algumas vantagens de desenvolver dessa forma são iterações mais rápidas, redução de custos e simulação do ambiente em produção.

Porém, essa abordagem vem com seus obstáculos. Em aplicações compostas de múltiplos serviços, precisamos garantir a persistência e acessibilidade dos dados utilizados pelos serviços, que a comunicação via rede seja feita corretamente e que os limites dos recursos de hardware sejam respeitados.

Para esse desafio contamos com a ajuda de ferramentas como Draft, Skaffold, Garden, Tilt e Plural, que nos auxiliam na redução do tempo de feedback das alterações feitas, considerando que a aplicação precisa ter seu código escrito, executado e modificado constantemente para não atrasar o processo de desenvolvimento.

Considerações finais

Embora ainda exista muito para aprender sobre o assunto, esse estudo visa ser um primeiro passo no aprendizado sobre o K8s em um ambiente local. Tópicos como o uso detalhado do minikube e K3s, o desenvolvimento em um ambiente K8s local e a escolha das ferramentas para esse desenvolvimento ficam como sugestões para dar sequência a esse estudo.

Enquanto isso, já podemos escolher uma ferramenta de K8s local, instalar e executar esse novo ambiente e começar a gerenciar nossas aplicações, seja para simular um ambiente de produção ou apenas para entender como o K8s funciona na prática.

Kubernetes no ambiente local was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Agora avance alguns capítulos.

Seu ambiente virou um cluster cheio de serviços distribuídos: APIs, jobs assíncronos, filas, caches, diferentes bancos, sidecars, gateways, integrações externas. Tudo ocorre dinamicamente, cada requisição segue um caminho diferente, e qualquer ponto pode falhar sem aviso.

E quando algo dá errado?

A equipe cai em uma verdadeira “caça ao tesouro”: logs desconexos, métricas isoladas, sintomas que não se explicam. Perde-se tempo, e controle, tentando descobrir onde o problema realmente começou.

É aí que a telemetria deixa de ser opcional. Sem ela, você está operando às cegas.

Neste artigo, vou mostrar como implementar telemetria com SigNoz + OpenTelemetry, e quais ganhos isso traz para o seu ambiente. E o melhor: tudo isso sem alterar uma linha de código da aplicação.

Preparando o ambiente

Para este exemplo utilizaremos:

• Linux Ubuntu,
• Docker,
• Git,
• SigNoz,
• Aplicação .NET e banco SQL Server.

Começaremos instalando o SigNoz. Basta clonar o repositório oficial e usar o instalador nativo:

git clone -b main https://github.com/SigNoz/signoz.git && cd signoz/deploy/

./install.sh

Em poucos minutos teremos os seguintes containers rodando:

• signoz-otel-collector
• signoz-signoz
• signoz-clickhouse
• signoz-zookeeper-1

Esses componentes são responsáveis por receber os dados, armazená-los, correlacioná-los e exibi-los.

Acessando localhost:8080, já podemos visualizar o SigNoz instalado e funcionando:

Instrumentando a aplicação

Agora vamos habilitar o OpenTelemetry no Docker da aplicação .NET.

No Dockerfile, adicionamos:

# Instalar OpenTelemetry Auto-Instrumentation
ENV OTEL_DOTNET_AUTO_HOME=/otel-dotnet-auto
RUN apt-get update && apt-get install -y curl unzip && \
    curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/download/v1.8.0/otel-dotnet-auto-install.sh -O && \
    sh ./otel-dotnet-auto-install.sh && \
    rm otel-dotnet-auto-install.sh && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# Configuração obrigatória do CLR Profiler
ENV CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318} \
    CORECLR_PROFILER_PATH=/otel-dotnet-auto/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so \
    DOTNET_STARTUP_HOOKS=/otel-dotnet-auto/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll \
    DOTNET_ADDITIONAL_DEPS=/otel-dotnet-auto/AdditionalDeps \
    DOTNET_SHARED_STORE=/otel-dotnet-auto/store \
    OTEL_DOTNET_AUTO_HOME=/otel-dotnet-auto \
    DOTNET_EnableDiagnostics=1

E no Docker Compose, adicionamos variáveis de identificação, exportação e habilitação dos recursos:

# Identificação do serviço e ambiente:
- OTEL_SERVICE_NAME=eshoponweb-web
- OTEL_RESOURCE_ATTRIBUTEyS=service.version=1.0.0,deployment.environment=development,service.namespace=eshoponweb

# Conexão com Signoz
- OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-otel-collector:4317
- OTEL_EXPORTER_OTLP_PROTOCOL=grpc
- OTEL_TRACES_EXPORTER=otlp
- OTEL_METRICS_EXPORTER=otlp
- OTEL_LOGS_EXPORTER=otlp

# O que será coletado:

# Traces
- OTEL_DOTNET_AUTO_TRACES_ASPNETCORE_INSTRUMENTATION_ENABLED=true
- OTEL_DOTNET_AUTO_TRACES_HTTPCLIENT_INSTRUMENTATION_ENABLED=true
- OTEL_DOTNET_AUTO_TRACES_ENTITYFRAMEWORKCORE_INSTRUMENTATION_ENABLED=true
- OTEL_DOTNET_AUTO_TRACES_SQLCLIENT_INSTRUMENTATION_ENABLED=true

# Métricas
- OTEL_DOTNET_AUTO_METRICS_ASPNETCORE_INSTRUMENTATION_ENABLED=true
- OTEL_DOTNET_AUTO_METRICS_HTTPCLIENT_INSTRUMENTATION_ENABLED=true
- OTEL_DOTNET_AUTO_METRICS_NETRUNTIME_INSTRUMENTATION_ENABLED=true

# Logs
- OTEL_DOTNET_AUTO_LOGS_ILOGGER_INSTRUMENTATION_ENABLED=true

Resultados

Após subirmos a aplicação já poderemos visualizar no SigNoz:

• Saúde dos serviços, latência e volume de chamadas

• Logs centralizados e correlacionados com traces:

• Traces completos de rede, banco e execução interna:

• Métricas de infraestrutura (CPU, RAM, disco, rede):

• Relação entre todos os serviços no cluster:

• Dashboards customizados reunindo tudo em um só lugar:

Conclusão

Com uma configuração mínima, conseguimos mapear automaticamente todos os serviços, processos, requisições, consultas ao banco e métricas de infraestrutura, tudo correlacionado, em tempo real.

Agora, se um erro/lentidão aparecer, conseguimos identificar rapidamente:

• Quais processos estavam rodando,
• Qual requisição gerou o problema,
• Tempo de resposta da rede e banco,
• O estado do servidor naquele exato instante,
• …

Como consequência, geramos valor na entrega de um serviço ao cliente e garantimos a confiabilidade do sistema.

E isso é apenas o básico da telemetria, podendo ser aplicada nos mais diversos ambientes (Kubernetes, Windows, Linux, …). Além disso, podemos criar alertas, automatizar ações e até monitorar métricas de negócio: vendas, emissões, transações, filas, heatmaps de acesso e muito mais.

Glossário

Tracing (ou Traces)
Rastreamento do caminho completo de uma requisição através de diversos serviços, mostrando tempos, falhas e gargalos.

Logs
Registros textuais de eventos emitidos por aplicações, serviços e sistemas, fundamentais para entender o que aconteceu.

Métricas
Dados numéricos coletados ao longo do tempo (CPU, RAM, latência, throughput, erros, etc).

OpenTelemetry (OTEL)
Padrão aberto para coletar métricas, logs e traces de qualquer aplicação, linguagem ou plataforma.

SigNoz
Plataforma open source de monitoramento e observabilidade que recebe os dados do OpenTelemetry e os apresenta em dashboards, gráficos e painéis correlacionados.

Documentação:

https://signoz.io/docs/install/self-host/
https://opentelemetry.io/docs/zero-code/dotnet/

Como implementar e quais os ganhos da telemetria em sua arquitetura was originally published in nddtech on Medium, where people are continuing the conversation by highlighting and responding to this story.