Seus Agentes de IA Têm um Arquivo de Regras. Eles Não Têm um Modelo do Seu Sistema.

Abra o CLAUDE.md, AGENTS.md ou .cursor/rules na raiz do seu repository e leia do jeito que ele chega a um agente: como um bloco de texto, sem nada dentro dele marcando quais linhas ainda são verdadeiras.

A maior parte do que você vai encontrar são convenções. Use tabs. Nada de any. Retorne cedo. Envolva os erros com %w. Essas linhas são duráveis, porque descrevem como escrever uma linha de código, e o agente as aplica ao código que está na frente dele.

Aí tem o outro tipo de linha. A que descreve o seu sistema: quais serviços existem, qual package é dono do quê, como as camadas têm permissão de conversar entre si. São essas linhas que fazem o arquivo valer a pena, e são elas que apodrecem.

Eu sei, porque o nosso apodreceu.

O que envelheceu no nosso

O repository do Archyl tem um CLAUDE.md na raiz. É um dos bons pelos padrões do gênero: 422 linhas, uma árvore de arquitetura, as variáveis de configuração, a fiação da injeção de dependências, uma descrição do pipeline de discovery. Todo agente que toca nessa codebase lê o arquivo antes de fazer qualquer outra coisa.

Aqui está o que ele dizia na manhã em que escrevi isto, 5 de agosto de 2026. Linha 392:

No test suite: The codebase currently has no Go test files or frontend tests.

Sem suíte de testes: a codebase atualmente não tem arquivos de teste em Go nem testes de frontend.

Existem 146 arquivos _test.go em backend/ e 31 arquivos de teste em frontend/src/.

A linha 140 diz:

AI Provider Abstraction: Supports both OpenAI and Ollama via ai.Provider interface.

Abstração de provider de IA: suporta tanto OpenAI quanto Ollama via interface ai.Provider.

backend/internal/adapter/ai/resolver.go roteia para OpenAI, Anthropic, Gemini, Bedrock e qualquer endpoint compatível com OpenAI, além do caminho de OpenAI e Ollama gerenciado pela plataforma. Cinco tipos de provider em um único switch. O arquivo nomeia dois.

E a árvore de arquitetura, nas linhas 74 a 87, lista onze packages em internal/domain/: c4, project, user, team, adr, projectdoc, flow, insight, subscription, dependency, history. Hoje existem quarenta e um diretórios em internal/domain/. Entre os trinta que ele não menciona: conformance, drift, apicontract, marketplace, reality, managedagent, mcpsession. Ou seja, a maior parte daquilo em que o produto se transformou desde que o arquivo foi escrito.

Cada uma dessas linhas era verdadeira no dia em que foi digitada. Nenhuma foi corrigida depois, porque corrigir exige que uma pessoa perceba, e não havia nada vigiando.

Esta é uma empresa que vende documentação de arquitetura. Se disciplina fosse a solução, teria funcionado aqui.

As duas metades desse arquivo não têm nada em comum

A metade das convenções é aplicável. "Nada de fmt.Println em Go" é um grep. "Arquivos Go precisam ser snake_case" é um script. Se um agente violar alguma, um linter avisa no CI. Se a própria convenção mudar, o linter começa a falhar e alguém atualiza o arquivo. Existe um ciclo de feedback, e ele é curto o bastante para funcionar.

A metade do sistema não tem equivalente. Não existe go vet para "o serviço de pagamentos está proibido de acessar o banco diretamente". Nada faz o parsing dessa frase, nada a compara com o repository, nada falha quando ela deixa de bater. É prosa em um arquivo markdown, e prosa não tem modo de falha.

Então um arquivo de regras são dois documentos dividindo um nome de arquivo. Um é verificado continuamente, o outro nunca é verificado, e nada no arquivo distingue os dois. "Envolva os erros com %w" e "a codebase não tem testes" ficam na mesma lista, na mesma voz. Um é uma regra sobre o código que está na frente do agente. O outro é uma afirmação sobre 146 arquivos que ele nem está olhando.

A ausência é a metade mais difícil

Envelhecer é a falha que todo mundo consegue imaginar. A mais silenciosa importa mais: um arquivo de regras contém apenas o que alguém se lembrou de escrever, e nada dentro dele distingue "isso não existe" de "ninguém mencionou".

O nosso nunca menciona internal/adapter/marketplace/. Esse package contém uma interface de provider e oito adapters: GitHub, GitLab, Argo CD, Datadog, Prometheus, Sentry, SonarQube, PagerDuty. A lista de adapters no CLAUDE.md para em git, ai, stripe, email, osv e registry. Nada do que o arquivo diz sobre o marketplace está errado. O arquivo não tem um.

Eu não fiz o experimento de pedir a um agente que adicione uma nona integração, e não vou te dizer o que ele produziria, porque eu estaria inventando o resultado. O que eu posso te dizer é que o mapa não tem marketplace nenhum nele, e que essa é a condição comum de todo arquivo de regras que já li, inclusive os que eu mesmo escrevi.

Um modelo não tem essa propriedade. Você pode perguntar a um modelo o que existe e receber uma resposta que significa alguma coisa, porque a resposta é uma consulta sobre um conjunto e não uma busca dentro de prosa. "O que conversa com o serviço de pagamentos" é uma pergunta que um grafo consegue responder e um parágrafo não.

As duas respostas óbvias, e por que nenhuma se sustenta

Escreva um arquivo de regras melhor. Mais longo, mais caprichado, com um checkbox no template de pull request. Times fazem isso, e funciona por algumas semanas. Não se sustenta, por um motivo que não tem nada a ver com disciplina: toda linha que descreve o sistema é uma cópia em cache de algo que vive em outro lugar, e caches precisam de invalidação. Aqui, a invalidação é uma pessoa perceber. Esse é o mecanismo inteiro, e é o mesmo que deveria ter mantido os diagramas de arquitetura precisos nos últimos vinte anos. Sabemos como isso terminou; o guia de detecção de drift é a versão longa desse argumento.

Deixe o agente ler o repository. Ele consegue, e para uma pergunta sobre um único arquivo ele deveria. Mas ler o código não te diz quais fronteiras foram deliberadas. A interface na frente de um serviço tem exatamente a mesma cara, esteja ela ali por causa de uma decisão tomada dois anos atrás depois de um incidente, ou porque alguém gosta de interfaces. Intenção não é recuperável a partir do artefato que resultou dela. É por isso que o arquivo de regras existe, para começar, e é por isso que apagá-lo também não é a resposta.

Alguém de fora desta empresa notou a mesma coisa

A Thoughtworks colocou "Architecture drift reduction with LLMs" no anel Assess do Technology Radar Vol. 34, publicado em abril de 2026. A abertura deles:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

O uso crescente de agentes de código com IA pode acelerar o afastamento em relação à codebase e aos designs de arquitetura pretendidos. Sem controle, esse drift se acumula à medida que agentes e humanos replicam padrões existentes, inclusive os degradados, criando um ciclo de feedback em que código ruim gera código pior.

Assess, na definição do próprio radar, significa "worth exploring with the goal of understanding how it will affect your enterprise" — vale a pena explorar com o objetivo de entender como isso vai afetar a sua empresa. Não é uma recomendação de nada, e certamente não de nós. É uma nota de que alguns times deles estão tentando isso e de que ainda é cedo.

A parte útil é o formato que eles descrevem: ferramentas de análise determinística (eles citam Spectral, ArchUnit e Spring Modulith) combinadas com avaliação por LLM, porque estrutura é verificável por um programa e intenção não. A lição que eles relatam também vale ser roubada: a primeira varredura traz à tona mais violações do que qualquer um quer triar.

Repare no que não está nessa receita. A resposta de ninguém para o drift acelerado por agentes é um arquivo markdown mais longo.

O que o artefato teria que fazer

Duas propriedades. Nenhuma delas é exótica.

Ele tem que enumerar. Você deveria conseguir perguntar o que existe e receber o conjunto, não a lembrança que alguém tem dele. Isso significa um artefato que você consulta em vez de ler, e a diferença aparece com mais força justamente nas perguntas que ninguém escreveu.

Ele tem que ser falseável. Alguma coisa precisa compará-lo com o código e reportar quais partes deixaram de ser verdadeiras, em uma cadência que não seja "quando um humano perceber". O ArchUnit faz isso para regras de camada em Java. O dependency-cruiser faz para imports de JavaScript. Ambos são deliberadamente estreitos, e ambos deixam o ponto claro: o artefato que vale a pena ter é aquele com o qual um programa pode discordar.

Um arquivo de regras reprova nas duas. Ele não enumera, e nada consegue discordar dele.

Onde estamos, e o que eu não posso te dizer

O Archyl mantém um modelo C4 do seu sistema: sistemas, containers, componentes, relacionamentos, gerados a partir do repository pela descoberta por IA e aprovados por uma pessoa em vez de desenhados por uma. Esse modelo é a metade enumerável, e os agentes chegam nele por MCP, o equivalente a 181 ferramentas, para que um agente pergunte o que existe em vez de torcer para alguém ter escrito. A metade das convenções é um catálogo de conformance: 169 regras distribuídas por 23 tecnologias nomeadas mais um conjunto agnóstico de linguagem, checagens determinísticas em vez de prosa. E o modelo é reconferido contra o código e pontuado, que é a propriedade da falseabilidade.

Ter um servidor MCP não é a parte interessante, e quem te vende um como diferencial está te vendendo uma tomada. O Structurizr entrega um e o do IcePanel está em beta aberto. A pergunta que vale a discussão é se a coisa atrás da tomada é mantida, porque um endpoint servindo um modelo que envelheceu em março é só um jeito mais rápido de estar errado.

Eu acho que essa é a diferença que importa. Não consigo provar. Ninguém mediu se um agente trabalhando a partir de um modelo mantido escreve código melhor formado do que um agente trabalhando a partir de um arquivo de regras caprichado, e até alguém medir, essa frase é uma afirmação sobre um mecanismo, não um resultado. Segure a frase desse jeito, e conteste quem a enunciar de forma mais categórica do que eu acabei de enunciar.

Tem uma dobra honesta aqui também. O Archyl gera um arquivo de regras. A ferramenta MCP get_agent_context devolve a arquitetura como um briefing em markdown que você pode commitar no seu repository, o que é um arquivo de regras com outro nome. O arquivo nunca foi o problema. O problema era que não havia nada por trás dele, então nada podia regenerá-lo. Um arquivo de regras que é o cache de um modelo mantido está ótimo. Um arquivo de regras que é a única cópia é um retrato do que uma pessoa acreditava numa tarde.

A versão de cinco minutos, que não te custa nada

Ignore tudo acima e faça isto no lugar.

Abra o seu arquivo de regras. Vá linha por linha e marque cada uma como convenção, ou seja, ela diz ao agente como escrever código, ou como afirmação, ou seja, ela diz ao agente algo sobre o seu sistema. Depois, para cada afirmação, escreva o que te avisaria que ela deixou de ser verdadeira.

Meu palpite é que você vai chegar ao fim do arquivo com a segunda coluna vazia. Essa é a lacuna. O que você faz a respeito é uma decisão separada, e você não precisa comprar nada para enxergá-la.

O nosso levou alguns minutos e revelou três linhas erradas. Corrigir é um commit, e não muda nada estrutural: a próxima linha vai envelhecer do mesmo jeito, e não há nada vigiando essa também.