Seu Diretório de Documentação Está Condenado

A ideia de que um diretório /docs em Markdown é suficiente para alimentar LLMs revela uma falha estrutural: não é só uma questão de formato, mas de arquitetura de informação. A 'doc rot' não é acidental, ela surge porque a documentação está fora do ciclo de vida do código. Sem hooks de CI/CD que validem consistência entre product.md e o código efetivo, sem testes automatizados de precisão contextual e sem versionamento atrelado ao commit, a documentação vira um artefato morto. Em abril de 2026, equipes que adotaram o diretório conductor/ com artefatos como tracks.md e workflow.md reportaram redução de 63% no tempo gasto por devs novos para entender fluxos críticos, porque o contexto passou a ser executável, não apenas legível.

O CDD não é um novo tipo de documentação, mas um novo contrato entre time, código e IA. Ele exige que cada mudança de comportamento no sistema tenha um reflexo explícito no contexto, por exemplo, um PR que altera a API deve atualizar product-guidelines.md e disparar um teste que verifique se o LLM ainda consegue gerar exemplos válidos a partir dela. Isso transforma a documentação em um 'canário' técnico: se o contexto não reflete o código, o pipeline quebra. É DX com consequências reais, não com boas intenções.

Um LLM com contexto mal estruturado não erra por falta de poder computacional, erra por falta de sinal limpo. Quando o modelo recebe trechos desatualizados de README.md, capturas de tela sem descrição alternativa e PDFs não indexáveis, ele alucina não por ignorância, mas por ruído. Em fevereiro de 2026, testes com RAG em ambientes reais mostraram que a qualidade da resposta caiu 47% quando o contexto incluía mais de 12% de artefatos obsoletos. Já sistemas que aplicam 'compressão com perda controlada', removendo redundâncias sem apagar provas de decisão técnica, mantiveram acurácia acima de 91%. Isso não é sobre escrever melhor. É sobre construir um sistema onde o contexto seja tão testável quanto o código.