Os Testes Dizem que Funciona. Nada Diz que Ainda É a Sua Arquitetura.

“Cada vez mais código é escrito por um modelo. Os testes continuam dizendo que funciona. O RuboCop continua dizendo que está arrumado. Nada diz que ele ainda segue a sua arquitetura.”

Quem escreve é Carmine Paolino, autor do RubyLLM, na abertura do anúncio do ArchSpec 1.0 em agosto de 2026. Nomeamos o mesmo modo de falha em abril e o chamamos de deriva silenciosa: código que compila, passa em todos os testes e se afasta em silêncio da arquitetura que o time combinou. Aquele texto tinha diagnóstico e nenhum instrumento. O ArchSpec é um instrumento, e o formato dele interessa mais do que a ferramenta.

Um Verificador que Nunca Sobe a Aplicação

O ArchSpec faz o parse do Ruby com o Prism, extrai fatos sobre referências, herança, mixins, chamadas e definições, e então avalia as suas regras contra esses fatos. Paolino relata que a aplicação completa do Discourse, 1.899 arquivos, foi verificada em 2,5 segundos sem subir a aplicação. Trate o número como benchmark do próprio autor no blog dele, porque é isso que ele é. A afirmação ainda merece atenção, porque o mecanismo explica o resultado: parse estático, extração de fatos, avaliação de regras, sem runtime e sem chamada de rede.

As regras se leem quase como frases:

models.cannot_use :controllers
services.cannot_call :render, :redirect_to, receiver: :none
controllers.can_only_use :models, :services

Uma linha só também consegue puxar uma forma inteira: architecture :vanilla_rails. Existem presets para Rails, arquitetura em camadas, hexagonal, clean architecture, monólitos modulares, CQRS e desenhos orientados a eventos. Paolino posiciona a ferramenta em relação ao Packwerk, ou seja, esta não é a primeira tentativa de impor fronteiras em uma codebase Ruby. O que muda é o enquadramento de para quem a imposição existe.

A IA Está do Outro Lado do Laço

“O ArchSpec não usa IA”, escreve Paolino. “É determinístico, é offline e é rápido o suficiente para você deixar ligado.” Ele é explícito sobre a divisão de trabalho: “Ele também não vai adivinhar … Você descreve a arquitetura que quer, e ele diz se o código ainda corresponde. A IA está do outro lado do laço, escrevendo o código que é verificado.”

Essa frase carrega a decisão de projeto que vale copiar. Argumentamos em o oráculo binário versus o arquitetural que um agente merece confiança quando a pergunta tem resposta de passa ou falha, e começa a inventar assim que a pergunta fica aberta. “Este arquivo referencia uma constante de controller?” é do primeiro tipo. “Isto é boa arquitetura?” é do segundo. O ArchSpec só faz perguntas do primeiro tipo, e é por isso que ele consegue ser determinístico e que o veredito dele merece entrar em um build.

Um agente revisando o pull request de outro agente herda o mesmo comportamento probabilístico que deveria capturar. Um parser não herda.

O Arquivo de Spec É a Parte que Você Possui

Paolino espera que você rascunhe a spec com um agente. A instrução dele sobre o passo seguinte resume o argumento de governança inteiro: leia o que ele escreveu, com cuidado, porque a spec é a parte que você possui, e depois acrescente as partes que os agentes deixaram passar.

Um agente pode propor as regras. Ele não é a autoridade sobre elas. A assimetria importa porque uma spec rascunhada e aprovada pelo mesmo modelo que escreve o código é um laço sem referência externa. As regras descreveriam a codebase como ela está, deriva incluída, em vez da codebase como o time pretende que ela seja.

Esta é a versão prática do argumento de governe o harness, não o modelo. O controle mora em um arquivo que um humano assina embaixo e em um gate que roda independentemente de alguém lembrar de pedir. A imposição pertence ao CI e a um hook de pre-commit, porque revisão arquitetural que depende de um revisor atento numa sexta à tarde não é controle nenhum.

Intenção arquitetural escrita em prosa no AGENTS.md tem uma curva de decaimento específica. Ela disputa espaço na janela de contexto com o arquivo em edição, a saída dos testes, o diff e a conversa. Uma spec de arquitetura que roda como comando não disputa espaço com nada. Ou ela passa, ou ela nomeia a violação.

Uma Catraca para Código que Já Derivou

A história de adoção é onde eu já vi times travarem. Uma codebase com anos de exceções acumuladas não fica verde contra uma spec estrita no primeiro dia, e uma ferramenta que abre com um muro de violações é do tipo que acaba desligada antes que alguém leia a segunda.

A resposta do ArchSpec, segundo o autor, é o comando archspec check rodado com a flag de update-todo. Ele registra as violações de hoje em um arquivo de todo, então o build fica verde no código atual e falha em deriva nova. Você trabalha a lista quando der.

Isso inverte o sequenciamento habitual. A guarda não fica bloqueada atrás de uma migração. Você ganha a guarda imediatamente e a migração vira trabalho de fundo opcional. O número de violações registradas também vira métrica: se o arquivo de todo cresce entre releases, a catraca está sendo contornada.

Diagnósticos Escritos para Dois Leitores

O detalhe que mostra que a ferramenta foi desenhada na era dos agentes, e não adaptada para ela, é a saída de erro. A justificativa declarada de Paolino: “Um humano lê num relance. Um agente recebe tudo de que precisa para corrigir o próprio erro sem perguntar para você: o arquivo, a linha, a regra e o porquê.”

Uma verificação que falha e que o agente consegue tratar sem intermediário humano fecha o laço na velocidade da máquina. O agente escreve código, o gate rejeita com uma razão legível por máquina, o agente corrige. O humano vê o resultado em vez da ida e volta.

Sobre disciplina de release, Paolino afirma que cada versão é testada à exaustão contra checkouts fixados de Discourse, Mastodon e do Fizzy da Basecamp, onde as contagens de diagnóstico por regra precisam bater com snapshots gravados antes de qualquer coisa ser publicada. Para um gate que derruba builds, falso positivo é o modo de falha que faz a ferramenta ser desligada, então fixar as contagens esperadas contra aplicações reais é a coisa certa a testar. E isso também é, de novo, o autor descrevendo o próprio processo.

O que Transfere se Você Não Escreve Ruby

O ArchSpec é exclusivo de Ruby e depende do Prism. Um time de Python, TypeScript ou Go não consegue adotá-lo. O que transfere é o formato, e o formato tem quatro partes.

A arquitetura mora em um arquivo, numa sintaxe que um humano lê sem tutorial. Esse arquivo tem dono humano, rascunhado por um agente no máximo. O verificador é determinístico e rápido o bastante para ficar sempre ligado, o que significa análise estática em vez de chamada a modelo. As violações existentes são registradas em vez de corrigidas, para o gate começar a funcionar de imediato.

Toda linguagem relevante tem matéria-prima para isso. Linters de fronteira de import, regras customizadas de AST e ferramentas de fronteira de módulo já existem. O que eu raramente vejo decidido é que o arquivo resultante é um artefato de governança com dono, em vez de um config de lint que alguém adicionou uma vez e ninguém mantém.

Faça Isto Agora

Escolha a única regra arquitetural que o seu time teria mais vergonha de ver violada em um pull request já mergeado. A regra de camadas, a regra de “este módulo nunca importa aquele”, a regra de “nenhuma chamada de framework no domínio”. Escreva-a como verificação executável no que a sua linguagem oferece, registre as violações de hoje para o build ficar verde, e ligue a verificação ao CI e ao pre-commit ainda esta semana.

Uma regra imposta vale mais do que uma página de intenção arquitetural que nenhum gate lê. Depois acrescente a segunda regra. O arquivo vira a arquitetura, e a arquitetura vira algo que os agentes não conseguem renegociar em silêncio.

Paolino encerra o post dele com a linha que sustenta o argumento inteiro: “Agentes podem escrever o código. A arquitetura continua sendo sua para manter.”

---

Fontes

• Carmine Paolino. “ArchSpec 1.0: Executable Architecture Specification for Ruby’s Agentic Coding Era.” Agosto de 2026. Relato em primeira pessoa do autor da própria ferramenta.

A Victorino ajuda times de engenharia a transformar intenção arquitetural em gates impostos antes que o código escrito por agentes a corroa: contato@victorino.com.br | www.victorino.com.br