Voc\u00ea pediu para o agente implementar uma fun\u00e7\u00e3o de c\u00e1lculo de frete considerando peso, dist\u00e2ncia e categoria de produto. O c\u00f3digo voltou limpo, bem indentado, com nomes de vari\u00e1veis sensatos e at\u00e9 um coment\u00e1rio explicando a regra de neg\u00f3cio. Voc\u00ea rodou, testou dois ou tr\u00eas casos na m\u00e3o, funcionou, fez o merge. Tr\u00eas semanas depois, o suporte reporta que pedidos internacionais com peso fracionado est\u00e3o gerando frete negativo. Ningu\u00e9m pegou isso porque ningu\u00e9m testou esse caminho \u2014 nem voc\u00ea, nem a IA, e muito menos um processo automatizado que devesse ter feito isso por voc\u00ea.<\/p>\n
Esse \u00e9 o padr\u00e3o mais recorrente de falha em times que adotaram gera\u00e7\u00e3o de c\u00f3digo por IA sem adaptar sua estrutura de verifica\u00e7\u00e3o. O problema n\u00e3o \u00e9 a IA escrever c\u00f3digo ruim \u2014 na maioria das vezes ela escreve c\u00f3digo sintaticamente correto e estilisticamente aceit\u00e1vel. O problema \u00e9 que c\u00f3digo plaus\u00edvel e c\u00f3digo correto s\u00e3o coisas diferentes<\/strong>, e a inspe\u00e7\u00e3o visual humana \u00e9 p\u00e9ssima para distinguir uma coisa da outra em volume. Voc\u00ea precisa de um harness: uma estrutura de testes desenhada especificamente para capturar as classes de erro que agentes de IA cometem com mais frequ\u00eancia, rodando de forma autom\u00e1tica, antes que o c\u00f3digo saia do seu ambiente local.<\/p>\n O termo “harness” j\u00e1 existe h\u00e1 d\u00e9cadas em engenharia de software \u2014 \u00e9 a estrutura que prepara o ambiente, executa o c\u00f3digo sob teste e verifica os resultados. O que mudou com a gera\u00e7\u00e3o de c\u00f3digo por agentes \u00e9 o prop\u00f3sito<\/em> desse harness: ele deixa de ser apenas “os testes do projeto” e passa a ser uma camada de conten\u00e7\u00e3o espec\u00edfica contra os modos de falha caracter\u00edsticos da IA.<\/p>\n Esse conceito tem sido tratado com mais profundidade recentemente sob o nome de Harness Engineering<\/strong>, que trata n\u00e3o apenas dos testes de comportamento, mas de restri\u00e7\u00f5es estruturais sobre o pr\u00f3prio c\u00f3digo-fonte gerado \u2014 como limites de tamanho de arquivo, complexidade ciclom\u00e1tica e padr\u00f5es arquiteturais que o agente n\u00e3o pode violar silenciosamente.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> O artigo da NxCode sobre Harness Engineering<\/a> define bem essa disciplina como “projetar ambientes, restri\u00e7\u00f5es e loops de feedback que tornam os agentes de codifica\u00e7\u00e3o de IA produtivos e seguros”. Vale a leitura para entender o pano de fundo te\u00f3rico antes de partir para a implementa\u00e7\u00e3o.<\/p><\/blockquote>\n Na pr\u00e1tica, um harness de testes para c\u00f3digo gerado por IA precisa cobrir tr\u00eas camadas que se complementam, n\u00e3o que se substituem:<\/p>\n Um agente de IA, ao gerar tanto a implementa\u00e7\u00e3o quanto os testes para ela (algo comum quando voc\u00ea pede “implemente X com testes”), tende a criar testes que confirmam o comportamento que ele mesmo implementou<\/strong>, n\u00e3o que o desafiam. Isso \u00e9 vi\u00e9s de confirma\u00e7\u00e3o estrutural: o modelo n\u00e3o vai gerar um teste que exponha uma falha na l\u00f3gica que ele acabou de escrever, porque ele n\u00e3o “sabe” que a l\u00f3gica est\u00e1 errada \u2014 ele s\u00f3 sabe que parece coerente com o que foi pedido.<\/p>\n Esse \u00e9 o motivo pelo qual pedir “gere os testes tamb\u00e9m” no mesmo prompt da implementa\u00e7\u00e3o \u00e9 uma pr\u00e1tica arriscada quando usada isoladamente. O harness precisa vir de uma fonte separada \u2014 idealmente escrita por voc\u00ea a partir da especifica\u00e7\u00e3o, n\u00e3o a partir do c\u00f3digo gerado.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> O material da Kimi AI sobre fluxos de trabalho confi\u00e1veis com IA<\/a> refor\u00e7a exatamente esse ponto: separar planejamento de execu\u00e7\u00e3o para que cada altera\u00e7\u00e3o seja f\u00e1cil de verificar de forma independente de quem (ou o que) a produziu.<\/p><\/blockquote>\n Isso n\u00e3o significa burocracia \u2014 significa uma lista objetiva de invariantes que o c\u00f3digo precisa respeitar, independentemente de como for implementado. Para o exemplo do c\u00e1lculo de frete:<\/p>\n Essas invariantes viram a espinha dorsal do seu harness. Note que nenhuma delas depende de como o agente vai implementar a fun\u00e7\u00e3o \u2014 elas descrevem o contrato, n\u00e3o a solu\u00e7\u00e3o.<\/p>\n Testes de propriedade (property-based testing) s\u00e3o a ferramenta mais subutilizada contra c\u00f3digo gerado por IA, porque testam a invariante contra centenas de valores gerados automaticamente, em vez de dois ou tr\u00eas casos fixos. Em Python, com Hypothesis<\/a>:<\/p>\n Se voc\u00ea trabalha em JavaScript\/TypeScript, o equivalente direto \u00e9 fast-check<\/a>. Em Java, jqwik<\/a>. Em Delphi, embora o ecossistema de property-based testing seja mais limitado, voc\u00ea consegue simular o padr\u00e3o com gera\u00e7\u00e3o de dados aleat\u00f3rios dentro do pr\u00f3prio DUnitX, iterando sobre um range de valores em vez de casos fixos \u2014 a l\u00f3gica da t\u00e9cnica n\u00e3o depende da linguagem.<\/p>\n Uma armadilha comum: voc\u00ea escreve os testes, eles passam, voc\u00ea acha que est\u00e1 protegido \u2014 mas os testes s\u00e3o fracos e passariam mesmo com a implementa\u00e7\u00e3o quebrada. Testes de muta\u00e7\u00e3o resolvem isso introduzindo pequenas altera\u00e7\u00f5es no c\u00f3digo (trocar `>` por `>=`, inverter uma condi\u00e7\u00e3o) e verificando se algum teste falha. Se nenhum teste falhar diante da muta\u00e7\u00e3o, seu harness tem um buraco.<\/p>\n Para JavaScript\/TypeScript, use Stryker Mutator<\/a>. Rodar muta\u00e7\u00e3o em todo commit \u00e9 caro computacionalmente, ent\u00e3o a pr\u00e1tica comum \u00e9 rodar apenas nos arquivos alterados por um PR, e reservar a su\u00edte completa para execu\u00e7\u00f5es noturnas ou semanais.<\/p>\n Al\u00e9m do comportamento, o harness precisa impedir que o agente produza estrutura problem\u00e1tica mesmo quando o comportamento est\u00e1 correto \u2014 fun\u00e7\u00f5es gigantes, complexidade excessiva, duplica\u00e7\u00e3o. Isso \u00e9 o que o material da AWS Builder chama de testes sobre o c\u00f3digo-fonte em si<\/strong>, separados dos testes comportamentais.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> O artigo da AWS Builder sobre constru\u00e7\u00e3o de software com humanos direcionando e IA executando<\/a> traz exemplos concretos desses limites estruturais, incluindo tamanho m\u00e1ximo de arquivo \u2014 uma restri\u00e7\u00e3o simples que evita que o agente “resolva” um problema complexo empilhando l\u00f3gica em uma \u00fanica fun\u00e7\u00e3o monol\u00edtica.<\/p><\/blockquote>\n Um exemplo pr\u00e1tico com ESLint em um projeto Node.js, for\u00e7ando limites de complexidade que o agente \u00e9 obrigado a respeitar:<\/p>\n Em Python, o equivalente \u00e9 configurar Radon<\/a> ou Ruff com regras de complexidade McCabe<\/a> dentro do pipeline de CI, falhando o build quando o limiar \u00e9 ultrapassado. O ponto central \u00e9 que essas regras n\u00e3o s\u00e3o sugest\u00f5es de estilo \u2014 s\u00e3o gates que bloqueiam merge, exatamente como um teste que falha.<\/p>\n Um harness eficaz n\u00e3o roda tudo de uma vez sem ordem \u2014 ele falha r\u00e1pido nas verifica\u00e7\u00f5es baratas antes de gastar tempo nas caras. Um pipeline t\u00edpico de CI (GitHub Actions, por exemplo) para c\u00f3digo com forte presen\u00e7a de IA na gera\u00e7\u00e3o:<\/p>\n Note a condi\u00e7\u00e3o no gate de muta\u00e7\u00e3o: ele s\u00f3 roda quando o PR altera menos de 15 arquivos, justamente para manter o pipeline r\u00e1pido em mudan\u00e7as pequenas \u2014 que s\u00e3o exatamente o tipo de contribui\u00e7\u00e3o mais comum quando voc\u00ea trabalha com agentes de forma iterativa.<\/p>\n Uma pr\u00e1tica que tem ganhado espa\u00e7o \u00e9 usar um segundo agente \u2014 com um prompt e contexto diferentes do que gerou o c\u00f3digo \u2014 para revisar o PR antes da fus\u00e3o, procurando especificamente por padr\u00f5es de risco: tratamento de erro ausente, valores m\u00e1gicos, aus\u00eancia de testes para caminhos de exce\u00e7\u00e3o.<\/p>\nO que \u00e9, de fato, um harness de testes para c\u00f3digo de IA<\/h2>\n
\n
Por que os testes “\u00f3bvios” n\u00e3o bastam<\/h2>\n
Passo a passo: construindo o harness na pr\u00e1tica<\/h2>\n
1. Escreva a especifica\u00e7\u00e3o de comportamento antes do c\u00f3digo<\/h3>\n
Especifica\u00e7\u00e3o: calcularFrete(peso, distancia, categoria)\n\n- Nunca retorna valor negativo\n- Peso <= 0 lan\u00e7a exce\u00e7\u00e3o de valida\u00e7\u00e3o\n- Dist\u00e2ncia <= 0 lan\u00e7a exce\u00e7\u00e3o de valida\u00e7\u00e3o\n- Categoria desconhecida usa tarifa padr\u00e3o, nunca lan\u00e7a exce\u00e7\u00e3o silenciosa\n- Frete cresce monotonicamente com o peso (mesma dist\u00e2ncia e categoria)\n- Frete cresce monotonicamente com a dist\u00e2ncia (mesmo peso e categoria)\n- Categoria "fr\u00e1gil" sempre adiciona sobretaxa fixa, nunca multiplicativa\n<\/code><\/pre>\n2. Transforme invariantes em testes de propriedade<\/h3>\n
from hypothesis import given, strategies as st\nimport pytest\nfrom frete import calcular_frete\n\n@given(\n peso=st.floats(min_value=0.01, max_value=1000),\n distancia=st.floats(min_value=0.01, max_value=20000),\n)\ndef test_frete_nunca_e_negativo(peso, distancia):\n resultado = calcular_frete(peso, distancia, \"padrao\")\n assert resultado >= 0\n\n@given(\n peso=st.floats(min_value=0.01, max_value=1000),\n distancia=st.floats(min_value=0.01, max_value=20000),\n)\ndef test_frete_cresce_com_peso(peso, distancia):\n frete_base = calcular_frete(peso, distancia, \"padrao\")\n frete_maior = calcular_frete(peso * 2, distancia, \"padrao\")\n assert frete_maior >= frete_base\n\ndef test_peso_invalido_lanca_excecao():\n with pytest.raises(ValueError):\n calcular_frete(-1, 100, \"padrao\")\n\ndef test_categoria_desconhecida_usa_tarifa_padrao():\n resultado = calcular_frete(10, 100, \"categoria_inexistente\")\n assert resultado > 0 # n\u00e3o lan\u00e7a, n\u00e3o retorna zero silencioso\n<\/code><\/pre>\n3. Adicione testes de muta\u00e7\u00e3o para validar o harness em si<\/h3>\n
# Python, com mutmut\npip install mutmut\nmutmut run --paths-to-mutate=frete.py\nmutmut results\n<\/code><\/pre>\n4. Trave limites estruturais no pr\u00f3prio c\u00f3digo<\/h3>\n
{\n \"rules\": {\n \"complexity\": [\"error\", 8],\n \"max-lines-per-function\": [\"error\", 40],\n \"max-depth\": [\"error\", 3],\n \"no-magic-numbers\": [\"warn\", { \"ignore\": [0, 1, -1] }]\n }\n}\n<\/code><\/pre>\n5. Monte o pipeline de gates em camadas<\/h3>\n
name: harness-ia\n\non: [pull_request]\n\njobs:\n gate-estrutural:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - name: Lint e complexidade\n run: |\n ruff check . --select C90\n ruff format --check .\n\n gate-comportamental:\n needs: gate-estrutural\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - name: Testes unit\u00e1rios e de propriedade\n run: pytest --hypothesis-seed=random -v\n\n gate-mutacao:\n needs: gate-comportamental\n runs-on: ubuntu-latest\n if: github.event.pull_request.changed_files < 15\n steps:\n - uses: actions\/checkout@v4\n - name: Testes de muta\u00e7\u00e3o nos arquivos alterados\n run: mutmut run --paths-to-mutate=$(git diff --name-only origin\/main | grep '.py$')\n<\/code><\/pre>\n6. Adicione um subagente revisor como camada extra, n\u00e3o como substituto<\/h3>\n