Documentação que se mantém atualizada: o agente propõe, sua equipe aprova

A documentação fica desatualizada por uma razão sem graça: o código mudou e atualizar os documentos não era tarefa de ninguém. O README descreve a configuração do ano passado. O manual operacional tem uma etapa que já não existe. O registro de decisão de arquitetura estava correto no dia em que foi escrito e nunca mais foi atualizado. Os engenheiros deixam de confiar na documentação, o conhecimento migra para tickets, conversas no chat e a memória de uma pessoa, e cada mudança fica mais demorada de revisar e mais difícil de operar.

O código continua sendo a fonte da verdade. O problema é manter fiel à realidade tudo o que descreve o código — e essa é uma tarefa que um agente pode assumir, desde que uma pessoa tenha a última palavra.

O formato que funciona

Trate a documentação como um sistema com entradas, saídas e um controle de aprovação, e dê o ciclo a um agente:

• Detectar divergências. Comparar a documentação com o que realmente mudou: o código, a especificação da API, a configuração, os pull requests integrados nesta semana. Um documento que menciona uma flag removida está desatualizado; assim como um manual operacional cujos comandos já não correspondem ao script de implantação.
• Redigir a atualização. READMEs, manuais operacionais, guias de integração de novos profissionais, documentação de integração, registros de decisões de arquitetura. O rascunho cita suas fontes — o commit, a especificação, o diff — para que quem o revise possa conferi-las em vez de confiar no texto.
• Escrever as notas de versão a partir dos commits. Resumos de mudanças vinculados aos tickets e pull requests que as produziram, sem reconstruí-los de memória no dia do lançamento.
• Executar as verificações. Compilações da documentação, verificações de links, linters e os testes que executem os exemplos — em CI, antes que uma pessoa veja o rascunho.
• Abrir um pull request. Com as mudanças propostas, as fontes usadas e uma lista breve de revisão. O agente propõe; a equipe aprova, rejeita ou comenta; toda mudança pode ser rastreada até uma revisão.

Essa última etapa é a chave do projeto. Nada chega à branch principal sem que uma pessoa leia, o que permite que a documentação detecte divergências de forma rigorosa sem ficar errada em produção.

O mesmo ciclo, além da documentação

Quando o agente consegue ler o repositório, ver o que mudou e abrir um pull request revisável com evidências, a documentação é a primeira de várias tarefas de manutenção que ele pode assumir:

• Atualizações de dependências que continuam revisáveis. Uma atualização proposta com o changelog resumido, os pontos de chamada afetados listados e a execução dos testes anexada — para que quem a revise entenda o impacto antes de integrá-la.
• Relatos de bugs que chegam reproduzíveis. Uma reprodução mínima, um teste que falhe e capture o problema, uma correção proposta e o manual operacional atualizado se o comportamento tiver mudado.
• Inventários de sistemas que correspondem à realidade. Quais serviços existem, quem é responsável por eles e de que dependem — regenerados a partir do que está em execução, não de uma página da wiki.

Todos têm a mesma característica: o agente lê e redige, a pessoa decide e a evidência acompanha o pull request.

O que o agente não deveria decidir

Ele não deveria decidir o que é importante. Pode dizer que um documento ficou desatualizado; não pode dizer se esse documento importa. Não deveria escrever o "porquê" em um registro de decisão de arquitetura — a justificativa, as alternativas consideradas, a concessão aceita — porque isso exige julgamento, e uma justificativa gerada parece plausível mas não significa nada. Ele redige o "o quê"; uma pessoa escreve o "porquê".

E ele não deveria integrar mudanças. No dia em que o controle de aprovação for removido da documentação, ela passará a ser a opinião do agente sobre o sistema em vez da opinião da equipe.

Por onde começar

Um repositório, um tipo de documento. Os manuais operacionais costumam ser o melhor ponto de partida: ficam desatualizados mais rápido, a divergência é perigosa e "este comando ainda funciona?" é uma verificação que um agente consegue executar em vez de adivinhar. Se os pull requests que ele abrir valerem a aprovação durante um mês, amplie o escopo. Se não, você terá aprendido algo sobre o repositório, não sobre o agente.