Por que Wikis viram cemitério de páginas em poucos meses

Quase toda equipe de engenharia já passou por esse ciclo. No início de um projeto novo, alguém dedica uma semana inteira desenhando caixas bonitas em uma ferramenta de quadros brancos, exporta três imagens PNG e publica uma página longa na Wiki da empresa explicando a arquitetura. Dois meses depois, o ritmo de entregas aperta, o fluxo de autenticação muda, dois microsserviços são fundidos e um novo módulo nasce no aplicativo. Ninguém lembra de abrir a Wiki para redesenhar as figuras.

Em seis meses, aquele documento deixou de ajudar e passou a atrapalhar: um engenheiro recém-chegado lê a página desatualizada, implementa a feature seguindo o desenho antigo e descobre no code review que tudo mudou no trimestre passado. Quando isso acontece duas vezes, o time inteiro perde a confiança na Wiki e para de consultar qualquer texto escrito lá.

O extremo oposto tampouco funciona. Equipes que abandonam toda documentação sob a frase pronta de que "o código se explica sozinho" até conseguem mostrar como uma classe opera hoje, mas apagam o porquê de ela existir daquele jeito. Sem esse histórico, a cada oito meses alguém propõe reescrever um componente que já foi descartado antes por um limite técnico real de sistema operacional ou de negócio, e a equipe gasta semanas redescobrindo a mesma armadilha.

Princípio do Docs as Code: documentação que precisa continuar verdadeira deve viver no mesmo repositório Git do código, em texto puro (Markdown e diagramas declarativos), sujeita ao mesmo Pull Request que altera o comportamento do software.

Modelagem visual que sobrevive ao tempo: C4 e diagramas versionados

Desenhar arquitetura continua sendo o jeito mais rápido de alinhar pessoas de produto, backend e mobile em uma mesma conversa. O problema nunca foi o diagrama em si, mas o formato binário e desconectado do código. Quando um diagrama mora em texto versionado no Git, qualquer alteração aparece linha por linha no diff do Pull Request, pode ser comentada pelo revisor e acompanha a tag da versão em produção.

Para evitar diagramas confusos que tentam mostrar banco de dados, classes Swift e firewall na mesma folha, o Modelo C4 (Contexto, Contêineres, Componentes e Código) ajuda a separar níveis de zoom. Na prática de times mobile, o melhor retorno está nos dois primeiros níveis (como o app conversa com APIs, gateways e provedores externos) e em diagramas de sequência pontuais para fluxos sensíveis, como login biométrico, renovação de token ou fechamento de pagamento. Raramente vale a pena manter o quarto nível (diagramas manuais de classes), porque a própria IDE já gera essa visão sob demanda.

Veja abaixo a renderização limpa de um fluxo de autenticação biométrica com Secure Enclave, do toque do usuário até a validação da sessão no gateway:

Fluxo de Autenticação Biométrica (Diagrama de Sequência)UsuárioTela de LoginAutenticadorKeychain / EnclaveAPI Gateway1. Toca "Entrar com biometria"2. handleBiometric()3. unlockSignedKey()4. Chave desbloqueada5. POST /v1/auth/session (token assinado)6. 200 OK (JWT + refresh token)7. displayHomeScreen()
Diagrama de sequência do fluxo de autenticação biométrica com Secure Enclave e validação de sessão no gateway.

No repositório do projeto, esse mesmo desenho é mantido em texto puro com sintaxe Mermaid dentro de um arquivo docs/flows/biometric-auth.md. GitHub, GitLab e a maioria das IDEs renderizam o bloco automaticamente, e o time ganha histórico completo de quem mudou cada passo e por qual motivo:

```mermaid
sequenceDiagram
    autonumber
    actor User as Usuário
    participant View as Tela de Login
    participant Auth as Autenticador
    participant Keychain as Keychain / Enclave
    participant API as API Gateway

    User->>View: Toca em "Entrar com biometria"
    View->>Auth: handleBiometric()
    Auth->>Keychain: unlockSignedKey()
    Keychain-->>Auth: Chave desbloqueada
    Auth->>API: POST /v1/auth/session
    API-->>Auth: 200 OK (JWT)
    Auth->>View: displayHomeScreen()
```

Mapa de artefatos: o que vale documentar de verdade

Documentação viva precisa ser pequena o bastante para que alguém realmente leia e mantenha. Em vez de tentar registrar tudo, concentre o esforço em cinco artefatos objetivos, cada um com gatilho claro de atualização:

ArtefatoOnde fica no GitGatilho de atualizaçãoErro comum a evitar
README.md por móduloRaiz de cada pacote ou featureQuando muda a responsabilidade pública ou forma de compilar o módulo.Repetir a assinatura de cada método em vez de explicar limites e exemplos de uso.
ADRs (Decisões)docs/adr/0001-*.mdEscolha de biblioteca, padrão arquitetural ou troca de estratégia de dados.Editar um ADR antigo para mudar a decisão em vez de criar um novo que o substitui.
Diagramas Mermaiddocs/architecture/Alteração de fluxos críticos, integrações externas ou fronteiras de módulos.Colocar mais de 7 participantes em um único diagrama, tornando a leitura impossível.
Runbooks de operaçãodocs/runbooks/Após cada incidente em produção ou mudança de ferramenta de observabilidade.Escrever teoria longa em vez de comandos prontos de copiar e colar na hora do plantão.
Contratos OpenAPIdocs/contracts/ ou repo compartilhadoQualquer campo adicionado, renomeado ou depreciado em endpoint.Deixar o contrato desconectado dos testes de mock e dos modelos de decodificação.

Registros de decisões arquiteturais (ADRs) na prática

Entre todos os formatos acima, os Architecture Decision Records (ADRs) entregam o melhor custo-benefício para squads que crescem rápido. A regra de ouro de um ADR é a imutabilidade: depois que a decisão foi aprovada, você não reescreve o arquivo quando o time muda de ideia um ano depois. Você cria um novo arquivo (por exemplo, 0014-migrar-cache-para-sqlite.md) e marca o antigo com status Substituído por ADR-0014. Assim, o histórico de trade-offs fica preservado.

Um bom ADR cabe em menos de uma página e vai direto ao ponto:

# ADR-008: Adotar URLSession nativa com async/await no módulo Networking

- **Data:** 2026-04-12
- **Status:** Aprovado

## Contexto
O cliente HTTP atual depende de uma biblioteca externa presa à versão anterior
de concorrência, gerando 180 warnings no Swift 6 e aumentando o tempo de build
em 45 segundos no CI.

## Opções avaliadas
1. Atualizar a biblioteca externa para a versão major seguinte (alto esforço de migração).
2. Migrar para URLSession nativa com wrappers finos tipados e async/await.

## Decisão
Adotar URLSession nativa encapsulada por protocolo no módulo Networking, mantendo
compatibilidade de interceptação via URLProtocol nos testes herméticos.

## Consequências e trade-offs
- Menos uma dependência externa no Package.resolved e redução de 1,4 MB no binário.
- A equipe passa a manter internamente a política de retry com backoff exponencial
  (cerca de 120 linhas de código cobertas por testes unitários).

Como a documentação viva melhora agentes de IA no código

Existe um benefício prático muito recente em manter Markdown limpo e ADRs concisos dentro do repositório: assistentes e agentes de programação baseados em LLMs conseguem ler esses arquivos diretamente antes de propor qualquer alteração. Sem esse contexto explícito, o modelo costuma inventar padrões que contradizem a arquitetura do time, reintroduz bibliotecas que foram banidas meses atrás ou viola fronteiras entre módulos.

Quando você mantém um guia curto de convenções na raiz do projeto, acompanhado de ADRs enxutos e diagramas Mermaid dos fluxos centrais, o agente precisa ler poucos kilobytes de texto estruturado para gerar código alinhado ao padrão real da equipe e até sinalizar violações arquiteturais durante revisões automatizadas de Pull Request. Em times onde já testei esse modelo, o tempo de onboarding de um desenvolvedor sênior até o primeiro PR relevante caiu de três semanas para menos de cinco dias úteis, justamente porque as perguntas mais repetitivas sobre fronteiras de módulo, política de cache e fluxo de sessão passaram a ter resposta direta no repositório.

Outro ganho prático aparece nas revisões de código entre squads distribuídas em horários diferentes. Em vez de marcar uma reunião de uma hora para explicar por que uma dependência não pode importar outra, o revisor aponta diretamente para o ADR e para o diagrama de componentes no mesmo repositório. Para quem está estruturando esse fluxo com agentes autônomos, vale combinar essas práticas com os conceitos de memória persistente de longo prazo para agentes de código e engenharia de contexto e redução de tokens em LLMs.

Rotina simples para evitar que a documentação apodreça

Mesmo no Git, arquivos Markdown ficam obsoletos se o time não criar hábitos leves de manutenção. Quatro práticas simples costumam bastar sem virar burocracia:

  1. Inclua uma única pergunta no template de Pull Request: "Esta alteração muda contrato externo, fluxo sensível ou fronteira de módulo? Se sim, o arquivo em docs/ foi atualizado?"
  2. Rode um verificador automático de links quebrados no CI para arquivos Markdown, pegando referências a arquivos movidos ou renomeados na mesma hora.
  3. Reserve 30 minutos uma vez por trimestre para podar documentação morta: apagar uma página obsoleta ajuda muito mais a equipe do que deixá-la lá confundindo leitores.
  4. Mantenha cada documento curto e orientado a decisões ou exemplos executáveis; se um README precisar de dez minutos de leitura contínua, provavelmente deveria ser quebrado por módulo.