Dívida cognitiva: o custo real do código gerado por IA

Eu venho rodando agentes autônomos de código no IGNIO há semanas. O código está limpo. Os testes passam. As PRs mergeam sozinhas. Por qualquer gráfico que eu apontar, o sistema funciona.

Mas às vezes abro um arquivo e percebo que não faço ideia de por que foi construído daquele jeito. O agente tomou a decisão. Eu aprovei. O entendimento nunca fez a viagem do prompt para dentro da minha cabeça.

Tem nome para isso. Dívida cognitiva.

Diferente de dívida técnica

Dívida técnica é algo que dá para ver. Uma função duplicada, uma variável hardcoded, uma classe fazendo o trabalho de duas. Mora nos arquivos, você consegue apontar, e você paga refatorando.

Dívida cognitiva mora na sua cabeça, ou melhor, na ausência de algo que deveria estar lá. O código pode estar limpo, bem estruturado, totalmente coberto por testes, e a dívida segue real se ninguém no time consegue explicar por que o design ficou como ficou. A forma do sistema está em disco. A razão da forma não está.

O programa real não é o texto na tela. É o modelo mental que o autor carrega: por que esses componentes se conectam, por que essa abordagem ganhou das outras, como a coisa vai reagir quando você muda uma parte dela. Quando o agente escreve o código, esse modelo pode não fazer a transferência.

Resíduo cognitivo

A frase que mais bateu veio de um fio sobre o tema. Alguém chamou de resíduo cognitivo.

Quando você itera com um agente, dá o prompt, rejeita a opção A, rejeita a opção B, fecha com a opção C. As opções rejeitadas não somem. Elas deixam trilhas fantasma no seu cérebro. Você gastou atenção de verdade lendo, avaliando, descartando. Dias depois você não consegue reconstruir como chegou na resposta final, porque o raciocínio está espalhado num chat log que você nunca mais vai abrir.

Livros didáticos e documentação oficial faziam o filtro das ideias ruins para você. Um editor já tinha feito esse trabalho. Hoje o agente gera infinitas opções e você é o filtro. Filtrar tem custo.

Meu próprio alerta

O padrão apareceu no IGNIO quando comecei a mergear mais PRs de agente. Código limpo, testes verdes, review passando. Semanas depois eu abria certos arquivos com aquela sensação de afundamento: shippei isso, e não consigo explicar.

Um caso específico. O agente reestruturou como as preferências de email se comportam quando tiers de assinatura são ignorados. O fix estava correto, os testes provavam, a descrição da PR resumia a mudança. Quando um bug relacionado apareceu um mês depois, tive que reler o diff inteiro para reconstruir o raciocínio, porque o modelo mental nunca tinha sido meu.

O agente resolveu o problema. A teoria ficou no prompt.

O que mudei

O primeiro movimento foi uma regra no workflow do agente: toda descrição de PR precisa documentar não só o que mudou, mas por que foi feito daquele jeito. Quem lê é o meu eu do futuro. O agente já sabe o o que na hora de abrir a PR; fazer ele escrever o por que custa quase nada e paga na primeira vez que aparece um bug relacionado.

Depois vieram arquivos de decisão. No estilo CLAUDE.md e AI_INSTRUCTIONS, onde o raciocínio por trás de escolhas arquiteturais de verdade fica em prosa. Quando uma nova sessão do agente começa, esses arquivos são a primeira coisa que ela carrega. A teoria não precisa morar na minha cabeça se ela mora num arquivo que a próxima sessão vai ler.

A mudança mais difícil é desacelerar nas decisões que importam. Velocidade é viciante quando o agente faz tudo parecer instantâneo, e todo atalho é um pequeno saque do seu próprio entendimento do sistema. Mais cedo ou mais tarde a conta entra no vermelho.

A IA já sabe o o que. A parte que ninguém pode fazer por você é o por que.

---

Inspirado pelo post da Margaret-Anne Storey sobre dívida cognitiva e a discussão que veio depois.