← BLOG
André SpineliAndré Spineli
12 de julho de 2026

Harness engineering e arquitetura homogênea

harness engineeringplatform engineeringlldai

O DevStation é TypeScript rodando em Deno. O harness é Go. Os dois seguem o mesmo low-level design: arquitetura hexagonal, bounded contexts isolados, comandos e queries separados, ports definidos pelo consumidor. E nos dois, a maior parte do código foi escrita por agentes. O que me chamou a atenção não foi o agente escrever código, foi o segundo projeto ter custado uma fração do primeiro para chegar à mesma qualidade de estrutura. Este artigo é sobre o que fez essa diferença, e sobre onde eu acho que esse tipo de solução deveria viver dentro de uma empresa.

Em teoria, bastaria documentar o padrão e seguir. Na prática, todo mundo que já manteve um guia de arquitetura sabe onde isso termina: o documento envelhece, cada time interpreta de um jeito, e seis meses depois existem quatro dialetos do mesmo padrão. O problema nunca foi decidir a arquitetura, foi mantê-la igual a si mesma, mudança após mudança, pessoa após pessoa.

Artefatos: rules, skills e agents

No harness engineering que venho praticando, os padrões deixam de ser documento e viram artefatos versionados que os agentes carregam: rules para o que vale sempre, skills para conhecimento sob demanda, agents para papéis específicos. A diferença para um guia tradicional é prática: o artefato entra no contexto do agente no momento em que ele trabalha, e podemos cobrar o resultado no build com testes de arquitetura. O guia clássico depende de alguém lembrar de ler. O artefato é carregado, queira o leitor ou não.

É também o que venho aplicando com times de desenvolvimento: ADRs e diretrizes técnicas que já existiam viram matéria-prima de rules, skills e guardrails. A decisão arquitetural continua sendo o registro importante, o que muda é que ela ganha uma forma que o agente consegue obedecer.

Skills abstratas, capabilities concretas

A peça que fez o segundo projeto custar pouco foi a separação entre conceito e implementação. A skill de low-level design que uso define contratos agnósticos de stack: o que é um bounded context, onde vivem os invariantes, como comandos e queries se separam, o que é um port e quem o define. Uma capability por stack implementa esses contratos, e na biblioteca hoje existem lld-typescript, lld-go e lld-php. A lld-go, por exemplo, traduz os mesmos conceitos para Go idiomático, com packages por feature no lugar de diretórios por camada e interfaces definidas pelo consumidor, enquanto a lld-typescript mantém as formas que o DevStation usa.

Tradução, não transliteração: o conceito sobrevive como papel, a forma muda com o idioma da stack. Quando comecei o harness em Go, nada da teoria precisou ser redecidido. Carreguei a skill abstrata, carreguei a capability de Go, e o agente produziu as mesmas formas em outro dialeto. A teoria ficou relativamente empacotada: um artefato que se reproduz em projetos diferentes com stacks diferentes, sem depender de eu reexplicar o desenho a cada início de projeto.

A ferramenta

Para isso funcionar em mais de um projeto, os artefatos precisam viver fora deles. O harness é um CLI open source que gerencia esses artefatos entre projetos: ele funde uma biblioteca pessoal com os artefatos locais de cada projeto, permite escolher o que cada projeto precisa numa TUI (uma interface que roda no próprio terminal), compõe skills agnósticas com implementações por stack e gera o AGENTS.md que diz ao agente o que carregar sempre e o que carregar sob demanda. Bibliotecas de artefatos podem viver em repositórios git adicionados como source, então um padrão corrigido na biblioteca se propaga, em vez de divergir silenciosamente em cada cópia.

Vale a honestidade de escopo: hoje é um piloto, focado em compartilhamento entre os meus próprios projetos. A tese deste artigo é maior que a ferramenta, e a ferramenta é a parte da tese que eu consigo testar sozinho.

Agentes seguem regra melhor que eu

Aqui entra a parte que mudou minha expectativa sobre tudo isso: LLMs são provavelmente melhores que humanos em seguir regras explícitas. Não em julgamento, em obediência. Um engenheiro experiente questiona a regra, esquece a regra, decide que hoje não precisa da regra. Um agente com a regra carregada aplica a regra na milésima vez com a mesma disposição da primeira, até porque disposição não é um problema que ele tenha. O gargalo muda de lugar: deixa de ser garantir que a regra seja seguida e passa a ser escrever regras que valham a pena seguir.

Arquitetura homogênea em ambientes distribuídos

Até aqui, projetos pessoais. Minha aposta é que o mesmo desenho vale mais em ambientes corporativos distribuídos, onde o custo da variação é multiplicado. Quando N times compartilham os mesmos artefatos, pessoas migram entre times sem reaprender o dialeto local, revisão de código atravessa fronteiras de time, e a empresa para de pagar várias vezes pela mesma solução de engenharia. Não é uniformidade pela uniformidade: é reduzir variação onde a variação não gera valor, e sobra energia justamente para os problemas em que o time precisa divergir.

Tenho também uma observação, ainda sem medição rigorosa: os ganhos de produtividade com IA aparecem mais em times com responsabilidades bem definidas e contextos separados por produto. Faz sentido pela mesma razão dos bounded contexts, fronteira clara reduz o que o agente precisa carregar para agir. Mas registro como observação de quem está aplicando, não como resultado medido.

Onde isso deve viver: times de plataforma

Na minha visão, esse tipo de solução deve emergir de times de plataforma, no sentido do Team Topologies: times que resolvem problemas comuns e constroem produtos internos para os times de engenharia alinhados a produto. É o mesmo movimento que developer experience já faz há anos com CLIs internos, golden paths para deploy e bootstrap de aplicação nova, e portais de desenvolvedor com catálogo de serviços, o que ferramentas como o Backstage fazem. Com harness não é diferente: a biblioteca de rules e skills é mais um produto interno, com uso metrificado, feedback coletado e evolução priorizada pela demanda dos próprios times.

E como todo produto de plataforma, não precisa ser monopólio. Um time de produto pode evoluir a plataforma quando a necessidade é prioridade exclusiva dele, desde que o time de plataforma esteja de acordo e revise a mudança. É o modelo de contribuição interna que já funciona para o resto do ferramental, aplicado aos artefatos de harness.

A mesma lógica, outros problemas

Artefatos de agente são só o primeiro produto dessa prateleira. A mesma lógica de plataforma se estende ao conhecimento com curadoria, RAG sobre documentação interna, ADRs e catálogo de regras de negócio, onde o problema difícil não é a busca, é manter a base viva, e isso é trabalho de produto com dono. Se estende aos MCPs internos expondo deploy, feature flags, observabilidade e o catálogo de serviços como tools: o golden path de sempre, com a diferença de que o consumidor agora é um agente. E se estende a agentes como produto interno para além da engenharia, consulta de métricas em linguagem natural, apoio em incidentes com runbooks, resumo de postmortems, com guardrails proporcionais a leitores que confiam no que leem.

Há também a camada de fluxo de trabalho, quebra de entregáveis, priorização, estimativas. Aqui vou com mais cautela: como rascunho de apoio funciona, mas estimativa gerada por IA apresentada como número vira compromisso rápido demais, e estimativa já era um problema difícil antes da IA. Cada um desses temas renderia um artigo próprio, e alguns ainda vão render.

O que consigo afirmar até agora

Volto aos dois projetos do começo. O que consigo afirmar hoje é que, entre os meus projetos, empacotar a teoria em skills abstratas e capabilities por stack fez a segunda implementação custar uma fração da primeira, com a mesma estrutura verificada por testes de arquitetura nas duas. Que isso escala para uma organização inteira é a aposta, não o fato: depende de biblioteca com dono, de metrificação honesta de uso e de times de plataforma tratando artefatos de agente como produto, não como wiki. É exatamente o tipo de aposta que um time de plataforma existe para testar.

Referências