SINTOMA 05
Nossa documentação está sempre desatualizada
Já houve mais de uma tentativa. Uma sprint dedicada, uma ferramenta nova, um responsável nomeado. Alguns meses depois o material voltou a descrever um sistema que não existe mais — e agora ninguém confia no que está escrito.
atualizado em
Como isso aparece no dia a dia
- o README descreve uma arquitetura de dois anos atrás
- decisões técnicas importantes não têm registro de por que foram tomadas
- a informação confiável está em threads de chat, não no repositório
- o time evita consultar o que está escrito porque já se enganou antes
- a documentação existe para auditoria, não para trabalho
Por que acontece
A causa raramente é disciplina. É posicionamento: quando a documentação vive num sistema separado do código, atualizar exige uma ação a mais, feita depois, por alguém que já considera a tarefa encerrada. Essa ação é a primeira a cair sob pressão de prazo — sempre.
Como nada quebra quando a documentação desatualiza, o custo só aparece muito depois: num onboarding lento, num incidente investigado no escuro, numa decisão refeita por desconhecimento.
Com agentes no fluxo, o custo passou a ser imediato. Documentação errada não é mais só um humano perdendo tempo: é contexto errado alimentando geração de código, que produz erro em escala e com aparência de correção.
Por que a correção óbvia não resolve
Uma sprint de documentação, ou migrar para uma ferramenta melhor de wiki.
A sprint corrige o estoque e não muda o fluxo: em três meses o material volta ao mesmo estado. A ferramenta nova muda onde o texto mora, e o problema nunca foi o editor — foi a distância entre o texto e o código.
O que muda o quadro
Isso não se resolve com mais uma ferramenta. Resolve-se instalando, no repositório, o sistema que a IA precisa ler — o que chamamos de Sistema Operacional de Engenharia.
A documentação precisa entrar no mesmo pull request que a mudança que a torna necessária. Isso exige que ela viva no repositório, num formato que o time já revisa, e que o pipeline sinalize quando um domínio muda sem que o texto correspondente tenha sido tocado.
Feito assim, a atualização deixa de ser tarefa extra e vira parte do que já é revisado. O material passa a ser confiável o suficiente para ser consultado — por pessoas e por agentes.
No framework de transformação, isso é o pilar AI Knowledge Layer. A definição completa da categoria está em Sistema Operacional de Engenharia.
Como saber se melhorou
Nenhuma dessas métricas significa alguma coisa sem o valor de partida. O baseline é levantado antes de qualquer mudança, com a janela e a fórmula registradas junto — o método está em métricas.
- Documentação atualizada
- proporção de domínios revisados no trimestre
- Tempo para localizar informação
- medido em sessões observadas, por tipo de pergunta
- Tempo de onboarding
- da entrada ao primeiro pull request aceito em produção
Por onde se começa
Para este problema, o degrau adequado costuma ser AI-Native Repository Foundation — 4 a 8 semanas, time que já sabe onde dói e quer o sistema instalado em um produto antes de escalar para os outros.
Antes disso, o diagnóstico gratuito já indica se o gargalo é mesmo este. Os outros quatro sintomas estão em problemas.