Escrevemos documentação que ninguém lê (e nunca foi tão útil)

Toda empresa que eu conheci tem um cemitério de documentação. Um Confluence com trezentas páginas que ninguém abre há dois anos. Um Notion que começou organizado e virou depósito. Uma pasta no Drive com quatro versões do mesmo documento e nenhuma marcada como a certa.

O diagnóstico é sempre o mesmo: falta disciplina. O time não escreve, não mantém, não lê. E a solução proposta também é sempre a mesma: um processo novo, um responsável nomeado, um ritual de revisão trimestral. Nunca funciona por muito tempo.

Eu passei anos aceitando esse diagnóstico. Hoje acho que ele estava errado desde o começo. Não era disciplina. Eram dois problemas diferentes, nenhum deles de caráter, e os dois caíram nos últimos anos quase sem a gente perceber.

Antes de continuar, um aviso: isso não é receita. Volto nisso no fim.

Por que documentação sempre apodreceu

O primeiro problema é que o leitor era ruim. E não estou falando mal de ninguém. Eu sou esse leitor.

Humano lê documentação por cima. Lê o pedaço que confirma o que ele já achava. Pula a seção que parece burocrática. Lê uma vez, no onboarding, e nunca mais volta. Quando bate a dúvida seis meses depois, pergunta no Slack em vez de procurar, porque perguntar é mais rápido do que garimpar.

Isso destrói a economia da coisa. Escrever documentação boa é caro: exige que alguém que entende o assunto pare de fazer outra coisa e passe horas transformando conhecimento tácito em texto preciso. E a taxa de consumo daquilo era perto de zero. Custo alto, uso baixo. Qualquer líder que já fez essa conta uma vez aprendeu a não priorizar documentação, e estava certo dentro daquela lógica.

O segundo problema é que o meio não tinha defesa nenhuma.

Regra de negócio sempre morou em Confluence, Notion, Google Docs, planilha. Pense no que falta nesses lugares: não tem branch, não tem diff que se leia, não tem revisão obrigatória antes de valer, não tem histórico legível, não tem ninguém aprovando. Qualquer pessoa edita qualquer coisa a qualquer hora e não fica rastro nenhum de quem mudou o quê nem por quê.

Agora compare com código. Código não apodrece do mesmo jeito. E não é porque dev é mais disciplinado que gente de produto. É porque código vive num lugar que tem pull request, revisão, histórico e blame. O ambiente força a qualidade que a pessoa sozinha não sustentaria.

Documentação nunca teve nada disso. A gente culpou as pessoas por um defeito do meio.

Trocamos o leitor

A primeira mudança é a que ninguém formula em voz alta, porque parece pequena e não é.

Nos times onde estou tentando esse caminho, o desenvolvedor não lê a documentação de regras de negócio. Quem lê é o agente de IA dele.

E o agente é o leitor que a documentação sempre mereceu e nunca teve. Ele lê com uma consistência que nenhum humano sustenta: toda vez, do zero, sem se lembrar da versão de três meses atrás. Não pula parágrafo por parecer chato, não acha que já sabe, não confunde com o projeto anterior, não tem preguiça na sexta à tarde.

Mas eu estaria vendendo fácil demais se dissesse que ele lê tudo. Contexto longo degrada, o miolo do documento recebe menos atenção que as pontas, e sistemas de recuperação entregam trechos, não o texto inteiro. O agente também lê por cima. A diferença é que ele não avisa. O humano que pulou uma seção pelo menos sabe que pulou. Isso não anula a troca, mas muda o que ela é: eu não ganhei um leitor perfeito, ganhei um leitor incansável. São coisas diferentes, e a segunda já é muita coisa.

Perceba o que isso faz com a conta. O custo de escrever continua o mesmo. O consumo foi de perto de zero para o teto prático: automático, em toda tarefa, sem depender da disposição de ninguém. A mesma documentação que era desperdício virou o insumo mais rentável da engenharia sem que uma única linha dela precisasse mudar. O que mudou foi quem está do outro lado.

E a leitura humana não sumiu. Ela subiu de lugar e se concentrou. Antes, dez pessoas liam mal um documento cada. Agora, poucas pessoas (produto e liderança do projeto) leem bem, uma vez, no momento de escrever e aprovar. A leitura delas é replicada com fidelidade em todas as frentes de trabalho, sem se degradar no caminho.

Trocamos o meio

A segunda mudança é mais simples de descrever e igualmente decisiva: as regras de negócio saíram do editor de texto e foram para o repositório.

Cada mudança de regra abre um pull request. Alguém revisa. Alguém aprova. Fica registrado quem propôs, quem aceitou e quando. E porque é um repositório, cada regra pode carregar de onde veio: a decisão que a originou, o que foi considerado e descartado no caminho.

Isso resolve o problema que nenhum ritual de revisão trimestral resolveu: o conhecimento de negócio ganhou o mesmo sistema de rastreamento que o código sempre teve.

Faço questão de não esticar a analogia, porque ela é sedutora e engana. O que protege o código não é o ritual do pull request. É compilador, teste, tipo e retorno de produção. Prosa não tem nenhum dos quatro, e revisão de texto vira carimbo mais rápido do que revisão de código. O que eu ganhei foi histórico, autoria e rastreabilidade, que é muito e não existia antes. Verificação eu não ganhei.

Um efeito colateral que eu não previa: dá para fazer blame numa regra de negócio. Você consegue apontar o momento exato em que a empresa mudou de entendimento sobre o próprio domínio, quem propôs a mudança e o que se sabia na época. Seis meses depois, quando alguém pergunta “por que isso funciona assim?”, a resposta não depende da memória de quem estava na sala.

Nada disso é invenção minha, e vale dizer. Registrar decisão de arquitetura em repositório, tratar documentação como código e escrever especificação em formato executável são práticas com mais de uma década de estrada. O que mudou não foi a técnica de guardar. Foi quem passou a ler o que a gente guarda.

A revisão mais cara deixou de ser a do código

Aqui está a consequência que mais mudou a minha cabeça como líder.

Uma linha de código errada quebra uma funcionalidade. Alguém abre um chamado, alguém corrige, acabou.

Uma regra errada quebra a classe inteira de problemas. Porque a partir do momento em que ela é aprovada, todo agente, em toda frente de trabalho, vai lê-la e reproduzi-la com fidelidade perfeita. O agente não erra ao ler uma regra ruim. Ele executa a regra ruim com precisão, em cinco lugares ao mesmo tempo, e o resultado sai com toda a aparência de estar certo.

O ponto de controle de qualidade mudou de endereço. A revisão mais cara da minha engenharia hoje não é a do diff de código. É a que acontece antes, quando alguém aprova uma regra.

Isso também mudou o que a função de produto é na prática. Escrever um chamado para um humano interpretar é uma coisa. Escrever o substrato que vai governar como o sistema inteiro se comporta é outra bem diferente: muito mais alavancagem e muito mais raio de explosão.

E tem um efeito bonito nisso: a especificação não morreu, ela mudou de frequência. O documento de vinte páginas aprovado uma vez antes do projeto começar era especificação como evento, e era ruim justamente por isso, porque errava quase tudo e ninguém voltava para corrigir. O que existe agora é especificação como fluxo: mudanças pequenas, frequentes, cada uma com revisor. Mesma função, cadência oposta.

O protótipo continua sendo o plano (mas agora começa sabendo)

Uma coisa que eu aprendi cedo e nunca desaprendi: o melhor plano é um protótipo. Nenhuma especificação escrita antes do produto existir jamais descreveu o produto que acabou saindo. Você só descobre o que a coisa é construindo uma versão porca dela.

Isso continua valendo. O que mudou é de onde o protótipo parte.

Um exemplo inventado, para não usar nada do meu trabalho. Imagine um marketplace com uma regra de devolução fora do prazo. Antes ela era uma só: fora do prazo, o vendedor decide se aceita. Depois de uma discussão, virou duas:

• Se o produto é do estoque do próprio vendedor, ele pode abrir exceção.
• Se veio do catálogo compartilhado da plataforma, não existe exceção local, e a opção nem aparece na tela.

Repare no que essa regra realmente codifica. Não é uma restrição técnica. É um fato sobre onde mora a autoridade: você manda no que é seu, e não manda no que é da rede. Isso não está escrito em lugar nenhum do código, porque não é uma propriedade do código. É uma decisão organizacional.

Um agente que constrói o protótipo sem essa regra vai acertar um dos dois caminhos e errar o outro. Pior: vai errar de um jeito plausível, com tela bonita e fluxo coerente, e a pessoa que revisar não vai ter motivo para desconfiar.

O mesmo protótipo, com as regras do domínio carregadas, sai outra coisa. Mesma janela de tempo, mesmo esforço. Sem contexto é um chute caro. Com contexto é uma proposta.

É isso que dissolve o repasse de trabalho de uma pessoa para outra. Se a linha guia está escrita e é legível por máquina, eu não preciso de alguém traduzindo negócio para o desenvolvedor. Eu abro frentes de trabalho e cada pessoa avança pela mesma referência. Ninguém entrega nada para ninguém.

A parte que quase ninguém escreve

Se eu pudesse levar uma única coisa deste texto para outra empresa, seria esta.

Toda documentação corporativa é um monumento à certeza. Ela registra o que já se sabe e finge que o resto não existe. Só que a parte interessante de qualquer domínio complexo é justamente a que ninguém decidiu ainda: a ambiguidade que aparece na terceira reunião, some na quarta e volta a morder seis meses depois na forma de um bug que ninguém entende.

O que passou a fazer mais diferença nos meus times não foi documentar o que está decidido. Foi manter um registro explícito do que não está: a decisão em aberto, o que depende dela, e quem deve a resposta.

Isso muda o comportamento do agente de um jeito que eu não esperava. Um agente que encontra “isto ainda não foi decidido, o dono é fulano” para e pergunta. Um agente que não encontra nada preenche a lacuna sozinho, com confiança, e segue. O superpoder não é o agente saber as regras. É ele saber onde as regras acabam.

E tem um ganho que é só de gestão, sem nada a ver com IA: quando o que está em aberto vira uma lista com dono, a incerteza para de circular como sensação difusa no time e vira trabalho endereçável. Dá para ver, no histórico, as perguntas sendo retiradas da lista uma a uma. É a organização convergindo sobre o próprio domínio, com data e responsável.

As pontas que eu ainda não resolvi

Não vou terminar isso fingindo que está fechado.

A primeira é a deterioração. Nada nesse sistema mata regra velha. A regra que estava certa em janeiro e ficou errada em julho porque o negócio mudou não tem quem a derrube. Erro de escrita a gente pega na aprovação, porque tem alguém revisando, é para isso que serve. Deterioração não tem alarme. E deterioração é pior que erro, porque a regra continua ali com toda a autoridade de algo que foi revisado e aprovado, sendo lida com fidelidade perfeita por todo agente, muito tempo depois de ter deixado de ser verdade.

O instrumento para detectar isso existe: o repositório sabe exatamente quando cada regra foi tocada pela última vez, e regra parada há muito tempo num domínio que mudou é um sinal medível. O que não existe ainda é a vigilância. Ninguém é acordado por isso.

Se esse problema ainda não me mordeu, é por tempo de operação, não porque está resolvido.

A segunda é o que acontece com quem não lê mais. Se o desenvolvedor não precisa ler as regras de negócio, de onde vem o julgamento de domínio dele daqui a três anos? Boa parte do que eu sei sobre educação eu aprendi lendo coisa chata que não era da minha função. Concentrar a leitura em poucas pessoas resolve a fidelidade e cria um gargalo: as mesmas cabeças aprovando tudo, e um time que executa muito bem um domínio que não conhece. Ainda não sei se essa troca se paga.

A terceira é de segurança, e é a que menos aparece nessa conversa. Um repositório de regras que agentes leem e executam é, na prática, um motor de políticas sem nenhuma das garantias de um motor de políticas. É superfície de injeção, porque texto que entra vira comportamento, e é uma pergunta de auditoria que alguém de risco vai fazer antes de mim. Em setor regulado, e educação é um deles, essa pergunta tem resposta obrigatória. Eu ainda não tenho a minha.

O que eu levo disso

Eu não estou prescrevendo nada aqui. Hoje eu tenho times trabalhando em formatos diferentes, de propósito. O chão está se movendo rápido demais para eu padronizar a engenharia inteira em cima de uma hipótese que ainda não terminei de validar. E quem afirma com muita convicção que descobriu o jeito certo de trabalhar com IA em 2026 está, na melhor das hipóteses, sendo otimista.

O que eu tenho é uma aposta que está pagando até aqui, e uma leitura do porquê.

E “pagando” aqui é impressão, não medição. Não montei grupo de controle, não tenho número limpo de antes e depois, e existe pesquisa séria mostrando que a percepção de ganho com IA costuma ser bem maior que o ganho real. Em um estudo controlado de 2025, desenvolvedores experientes ficaram mais lentos com as ferramentas enquanto juravam ter ficado mais rápidos. Fica registrado que eu posso ser exatamente o sujeito desse viés.

Documentação nunca foi uma má ideia. Ela era uma boa ideia com dois defeitos estruturais: escrevíamos para um leitor que não lia, e guardávamos num lugar sem nenhuma defesa. Os dois defeitos caíram: um porque o leitor mudou, outro porque a gente finalmente mudou o meio. O trabalho de escrever continua exatamente tão caro quanto era. O que mudou foi o retorno.

E se eu estiver certo sobre isso, a habilidade que fica escassa não é escrever código. É conseguir olhar para uma operação que você conhece bem e transformar o que “todo mundo sabe” em texto preciso o suficiente para uma máquina agir em cima. Isso continua sendo trabalho humano. E acabou de ficar muito mais valioso.

---

Se esse tema te interessa, adoraria trocar ideias. Me encontre no LinkedIn.