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.
- 1Código mortoquebra o build
- 2Linters e formatadoresquebra o build
- 3Análise estáticaquebra o build
- 4Testes unitários e coberturaquebra o build
- 5Complexidade e duplicaçãoquebra o build
- 6Arquitetura e acoplamentoquebra o build
- 7Regras escritas (AGENTS.md)o CI não garante
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
| Nível | Python | PHP | JS/TS |
|---|---|---|---|
| Código morto | vulture | shipmonk/dead-code-detector (PHPStan) | knip |
| Linters e formatadores | ruff | PHP_CodeSniffer (phpcs) | ESLint + Prettier |
| Análise estática | mypy (strict) | PHPStan | tsc (strict) |
| Testes unitários e cobertura | pytest + coverage | PHPUnit | Jest / Vitest |
| Complexidade | complexipy | PHPMD, cognitive-complexity (PHPStan) | ESLint complexity |
| Duplicação | pylint duplicate-code | jscpd | jscpd |
| Arquitetura e acoplamento | import-linter | Deptrac | dependency-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 verifyno 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-projectE, 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.