Vibecoding
Como documentar um sistema que a IA escreveu
Documentação longa ninguém escreve e ninguém lê. Existe uma versão curta que cabe em uma página e resolve 90% do problema, principalmente quando quem escreveu o código foi a IA.
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.
Perguntas frequentes
Perguntas rápidas
+Por que documentar se a IA pode explicar o código depois?
A IA explica o que o código faz, não por que ele foi feito assim. O motivo de uma decisão não está no código: está na conversa que ninguém guardou. É justamente essa parte que custa caro recuperar.
+Qual o tamanho ideal da documentação?
Uma página por sistema. Documentação longa não é escrita nem lida, e desatualiza mais rápido porque ninguém tem paciência de manter. Uma página curta e verdadeira vale mais que vinte páginas obsoletas.
+Dá para a IA escrever a documentação?
Dá para o rascunho da parte descritiva, o que o sistema faz e onde as coisas estão. A parte do porquê tem que ser sua, porque a decisão foi sua. Peça o rascunho, corrija e acrescente os motivos.
+Quando atualizar?
Quando uma decisão estrutural muda: onde um dado mora, quem pode acessar o quê, ou uma escolha de tecnologia. Mudança pequena de tela não precisa entrar. Se tudo precisa entrar, o documento está grande demais.
Continue lendo
O agente de código entrou no canal do time. Ver não é revisar
O Slack lançou canais onde agentes de IA programam na frente de todo mundo, com Claude, Copilot, Devin, ChatGPT e Vercel. É a melhor notícia de governança do ano e a maior armadilha de teatro de revisão.
VibecodingComo estruturar um projeto antes de pedir a primeira linha pra IA
Trinta minutos decidindo cinco coisas antes de abrir o chat economizam semanas de retrabalho. É a parte que todo mundo pula porque parece que não está produzindo.
VibecodingComo não virar refém de uma ferramenta de IA
A ferramenta que você ama hoje pode dobrar de preço, mudar de dono ou fechar amanhã. Não construa em cima de uma só.