← Blog

Agentes de IA

Entropia do código: como verificações de CI impedem a IA de acumular legado

A lei de que a complexidade do código cresce sozinha continua valendo com a IA; ela só ficou mais rápida. Aqui estão sete níveis de verificações de CI que impedem o legado de se acumular, na ordem em que eu os adiciono.

A entropia cresce sozinha. Na física, essa é a segunda lei da termodinâmica. No desenvolvimento de software é parecido: a bagunça se acumula com facilidade, e a ordem exige esforço.

Sempre foi assim. Conforme o projeto cresce, cresce também a complexidade: o legado se acumula, o projeto fica mais difícil de manter, cada mudança pesa mais, e o risco de quebrar algo só aumenta. Em 1974, Manny Lehman registrou isso como uma lei da evolução de software: a complexidade de um sistema aumenta, a menos que se trabalhe para reduzi-la. A IA não mudou isso. Só fez o legado se acumular mais rápido.

O ideal é manter o código o mais simples possível, e é aqui que as verificações de CI ajudam.

  1. 1Código mortoquebra o build
  2. 2Linters e formatadoresquebra o build
  3. 3Análise estáticaquebra o build
  4. 4Testes unitários e coberturaquebra o build
  5. 5Complexidade e duplicaçãoquebra o build
  6. 6Arquitetura e acoplamentoquebra o build
  7. 7Regras escritas (AGENTS.md)o CI não garante
As verificações mais baratas ficam embaixo. Os níveis 1–6 quebram o build toda vez; as regras escritas, no topo, orientam o agente, mas não conseguem detê-lo.

1. Código morto

O passo mais simples é apagar o que não é mais usado. Isso também dá para automatizar: coloque um detector de código morto no CI (vulture para Python, knip para JS/TS), e o código sem uso simplesmente quebra o build.

2. Linters e formatadores

Depois vem o linter: phpcs para PHP, ruff para Python, ESLint e Prettier para JS/TS, e assim por diante. Cada linguagem tem seu estilo de código, e qual você escolhe pouco importa. O que importa é parar de gastar tempo e dinheiro lendo código e escrevendo comentários de revisão como “troque aspas duplas por simples”. Combine o estilo uma vez, e a partir daí o CI verifica sozinho.

3. Análise estática

O nível seguinte são os analisadores estáticos: PHPStan para PHP, mypy para Python, tsc para JS/TS. A checagem estrita de tipos pega erros simples: uma string passada onde se esperava um número, ou esquecer que um valor pode vir vazio. Ela deixa a lógica por sua conta e elimina uma classe inteira de erros. Valores vazios são o caso clássico: Tony Hoare, que inventou a referência nula, chamou-a de seu “erro de um bilhão de dólares”, e, segundo dados de 2020 da Harness, o NullPointerException ainda estava entre as 10 exceções mais comuns em 70% dos ambientes Java de produção analisados.

4. Testes unitários e 80% de cobertura

Por quê? Porque código ruim é muito difícil de testar com testes unitários. Para que o código possa ser coberto por eles, é preciso dividi-lo em classes e funções separadas, pensar em acoplamento e interfaces, decidir o que fica público e o que fica privado, usar injeção de dependência e evitar estado global. Claro que isso não é garantia de 100%, até porque a IA infla a cobertura com facilidade, com testes que não verificam quase nada. Mas, de um jeito ou de outro, a meta impõe restrições ao design e aumenta as chances de um bom código.

5. Complexidade e duplicação

A memória de trabalho humana guarda só alguns itens independentes por vez: George Miller contou 7 ± 2 em 1956, e Nelson Cowan refinou para cerca de quatro em 2001. O que passa disso fica difícil e vai para o swap. Não vi pesquisas sobre isso para a IA, mas, se o código é compreensível para uma pessoa, aumentam as chances de a IA não alucinar. E, se o código é tão emaranhado que uma pessoa não consegue acompanhá-lo, o mais provável é que a IA empilhe novas camadas de legado por cima.

Por isso eu defino limites rígidos para as métricas de duplicação e de complexidade. Limite ultrapassado → o CI falha → é preciso refatorar e extrair código para métodos e classes separados. Para Python, um exemplo é o complexipy.

Veja como isso fica num projeto real. Numa plataforma em que trabalhei, agentes de IA escreveram a maior parte do backend. Seis semanas depois, antes de qualquer uma dessas verificações existir, a primeira medição encontrou 143 funções com complexidade acima de 10 e 202 trechos copiados e colados, cerca de 5% do código. Mais tarde, quando entrou um teto rígido, a pior função processava recibos, ou seja, mexia com dinheiro: 490 linhas com complexidade 73. Assim que esse teto passou a quebrar o build, ela caiu de 73 para 30 em quatro dias de refatoração, uma função por commit. Nos dois meses seguintes à primeira medição, a duplicação caiu para cerca de 3%.

Se o legado já se acumulou, dá para começar de onde você está: defina o limite na sua função mais complexa, e pelo menos nada vai piorar. A dívida, porém, continua lá e é paga à parte: reserve tempo para refatorar e baixe o limite depois de cada passo, para consolidar o resultado. As verificações só impedem que a bagunça cresça; a limpeza fica por sua conta.

6. Arquitetura e acoplamento

Limites rígidos também reduzem a complexidade, um nível acima. É como o encapsulamento em OOP: o sistema é feito de blocos grandes cujo interior você não precisa guardar na cabeça; basta conhecer o contrato deles. E a implementação de um bloco pode ser trocada quando necessário, sem reescrever o resto do sistema. Em vez de dezenas de classes e conexões, você raciocina sobre alguns blocos grandes. De novo, você reduz o número de coisas que precisa manter na cabeça ao mesmo tempo, agora em todos os níveis da arquitetura.

Na prática, isso significa Clean Architecture e Arquitetura Hexagonal: o código é dividido em camadas, e as dependências entre elas são estritamente limitadas. O domínio não sabe nada sobre o banco de dados, o HTTP ou as APIs externas, e o código de fora chega até ele por interfaces predefinidas. Isso também é verificado automaticamente (com o import-linter para Python, por exemplo): apareceu um import proibido, o CI falha.

7. Regras escritas

O último nível são as regras escritas. Antes eram guias e documentação para desenvolvedores; hoje são um arquivo AGENTS.md e a documentação para a IA. Diferente das verificações acima, aqui o resultado não é determinístico: a IA pode ler uma regra e mesmo assim quebrá-la. Por isso, as regras escritas são a última milha. Elas guardam só o que não deu para cobrir com verificações. Em igualdade de condições, troque o texto por uma verificação rígida no código.

A IA vive tentando desligar a verificação em vez de corrigir o código: subir o limite, adicionar uma exceção, silenciar a regra com um comentário. Por isso o meu arquivo de regras diz isso numa linha separada: enfraquecer uma verificação para ela passar é gambiarra.

As ferramentas, por linguagem

Veja o que eu uso em cada nível; as ferramentas específicas importam menos do que cada nível quebrar o build.
NívelPythonPHPJS/TS
Código mortovultureshipmonk/dead-code-detector (PHPStan)knip
Linters e formatadoresruffPHP_CodeSniffer (phpcs)ESLint + Prettier
Análise estáticamypy (strict)PHPStantsc (strict)
Testes unitários e coberturapytest + coveragePHPUnitJest / Vitest
ComplexidadecomplexipyPHPMD, cognitive-complexity (PHPStan)ESLint complexity
Duplicaçãopylint duplicate-codejscpdjscpd
Arquitetura e acoplamentoimport-linterDeptracdependency-cruiser

Existe também uma versão passo a passo deste texto, escrita para agentes de código: o playbook de verificações de CI (em inglês). Para aplicá-lo a um repositório, diga ao seu agente: Aplique https://sg4.tech/blog/code-entropy-ci-checks-ai-legacy/playbook.md a este repositório.

Resumindo

A entropia vai crescer de qualquer jeito; a única questão é quem a segura. Quanto mais regras saem dos guias escritos e viram verificações automáticas de CI, menos tudo depende da atenção de uma pessoa na revisão. A IA roda as verificações sozinha, vê o que falhou e corrige: ela pode pular uma linha do AGENTS.md, mas não consegue pular um CI que falhou. E quanto mais dessas verificações você tem, com mais tranquilidade pode entregar o código a ela.

Se você é fundador e não lê código, esta lista ainda serve como um roteiro de perguntas para a sua equipe: quais desses níveis de fato quebram o build? Cada resposta do tipo “isso a gente pega na revisão” é uma regra que depende da atenção de alguém num dia qualquer. Por que o código escrito por agentes precisa dessas proteções é outra história: gerenciar a IA como um júnior.

Um template para Python

A abordagem vale para qualquer linguagem. Para Python, juntei tudo isso num template pronto; fique à vontade para usar: python-guardrails-template.

Dentro dele:

  • todas as verificações deste texto atrás de um único comando make verify no Docker, e o mesmo comando no GitHub Actions;
  • camadas de arquitetura com verificação de imports;
  • um scanner de segredos que roda a cada commit;
  • um AGENTS.md em que quase toda regra aponta para a verificação que a garante;
  • um pequeno exemplo, para que as verificações passem logo depois de criar o projeto.

Um projeto novo é criado com um comando:

copier copy gh:sg4tech/python-guardrails-template my-project

E, quando o template é atualizado, copier update leva as novas verificações para os projetos existentes e preserva as suas mudanças. Chega de configurar tudo do zero a cada projeto novo.

Perguntas frequentes

Verificações de CI rígidas não vão deixar a equipe mais lenta?

As verificações levam o custo da revisão e da produção para um build que falha, onde ele sai mais barato. Num código legado, você parte do nível atual, então nada trava no primeiro dia.

Dá para adicionar essas verificações a um projeto legado que já existe?

Sim: congele o nível atual como limite, para que nada piore, e depois baixe-o passo a passo conforme refatora.

A revisão de código não basta para pegar isso?

A revisão depende da atenção e não acompanha a velocidade com que os agentes escrevem código. Uma verificação roda em cada mudança e falha do mesmo jeito todas as vezes.

Preciso dos sete níveis de uma vez?

Não. Adicione-os em ordem: código morto, formatação e tipos primeiro, porque são baratos. Os limites de complexidade e de arquitetura compensam quando o código cresce.