Como documentar um sistema que a IA escreveu

Documentação tem má fama merecida. Quase toda que existe é longa, desatualizada e ninguém lê.

Só que sistema construído com IA tem um problema específico que a documentação resolve, e é um problema que quase ninguém antecipa.

O problema específico

Quando você escreve o código à mão, sobra memória. Você lembra por que aquela parte é daquele jeito, lembra do que tentou antes, lembra da gambiarra e do motivo dela.

Quando a IA escreve, essa memória não se forma. Você viu o resultado, aprovou, seguiu. Seis meses depois é como abrir código de estranho, com o agravante de que o estranho é você.

E existe uma pergunta que nem a IA responde depois: por que foi feito assim. O código mostra o que faz. Não mostra o que foi considerado e descartado, nem por quê.

A versão que cabe em uma página

Cinco blocos. Um arquivo na raiz do projeto. Meia hora pra escrever, cinco minutos por mês pra manter.

1. O que esse sistema faz. Três linhas, em português, como se explicasse pra alguém de fora. Se você não consegue em três linhas, o sistema faz coisa demais.

2. Onde cada coisa mora. Uma lista curta: usuário fica aqui, arquivo fica ali, segredo fica assim. É a informação que você mais vai procurar e a mais chata de descobrir de novo lendo código.

3. O que é sensível. Quais dados identificam pessoa, quais são financeiros, quais têm regra de LGPD. Essa lista decide onde a permissão precisa ser rígida.

4. O que acontece quando falha. As três ou quatro falhas mais prováveis e o comportamento esperado de cada uma. Se o pagamento confirma e o e-mail não sai, o que acontece.

5. Por que as decisões estranhas foram tomadas. O bloco mais valioso e o único que só você pode escrever. Toda escolha que pareceria errada pra quem chega agora: por que esse banco, por que esse campo duplicado, por que essa parte não é automática.

Onde a IA ajuda e onde ela não ajuda

A IA escreve o rascunho dos blocos 1 e 2 muito bem. Ela lê o projeto e descreve o que existe.

Ela não escreve o bloco 5. Não tem como. A decisão foi sua, o motivo estava na sua cabeça e nunca virou código.

O fluxo prático: pede o rascunho descritivo, corrige o que estiver errado, e escreve o porquê à mão. Meia hora no total.

O teste de que está boa

Um teste só, e é implacável.

Entrega o documento pra alguém que nunca viu o projeto e pergunta onde ela mexeria pra mudar o texto de um e-mail.

Se a pessoa acha o caminho, está boa. Se ela precisa perguntar, falta o bloco 2.

Como não virar mentira

Documentação errada é pior que documentação nenhuma, porque manda a pessoa pro lugar errado com confiança.

Duas regras evitam isso:

Documenta decisão, não detalhe. Nome de função muda toda semana. Onde o dado mora muda uma vez por ano. Documenta o segundo.

Atualiza quando a decisão muda, não quando o código muda. Se toda alteração exige atualizar o documento, ele está detalhado demais e vai apodrecer.

Por que isso vale mais em vibecoding

Porque a velocidade é maior e a memória é menor.

Um sistema construído com IA cresce em semanas o que antes levava meses. Mais superfície, no mesmo tempo, com menos memória formada sobre ela.

É a mesma lógica de quem volta num projeto e não reconhece o próprio código. Uma página escrita hoje é o bilhete que você deixa pra alguém que vai precisar muito dele.

Esse alguém provavelmente é você.

A decisão é sua.