O objetivo da documentação é que o sistema não dependa de pessoas específicas para ser entendido. Documentação demais desatualiza e ninguém lê; de menos, o conhecimento vai embora com quem sai do time. Três práticas cobrem a maior parte dos casos.
Modelo C4: diagramas em níveis
Criado por Simon Brown, organiza os diagramas como um mapa com zoom: cada nível mostra mais detalhe para um público diferente.
| Nível | Mostra | Para quem |
|---|---|---|
| Contexto | O sistema como uma caixa, usuários e sistemas externos | Todos, inclusive negócio |
| Containers | Aplicações, serviços e bancos, e como se comunicam | Time técnico, operação |
| Componentes | As partes principais dentro de um container | Desenvolvedores |
| Código | Classes e relações | Quase nunca vale desenhar; o código já é isso |
Na maioria dos projetos, os dois primeiros níveis já resolvem.
ADR: registro de decisões
Um Architecture Decision Record é um texto curto, um por decisão importante, guardado no repositório:
# 7. Usar PostgreSQL como banco principal
Status: aceita (2026-03-10)
Contexto: precisamos de transações e consultas flexíveis; o time já domina SQL.Decisão: PostgreSQL gerenciado na nuvem.Consequências: abrimos mão de escala horizontal simples; revisitar acima de 5 TB.O valor está no contexto: daqui a dois anos, ninguém lembra por que a decisão foi tomada. ADRs não são editados; uma decisão nova substitui a antiga.
Documentação junto do código
- README com como rodar, testar e publicar.
- Diagramas como código (Mermaid, Structurizr), versionados e revisados no mesmo pull request que muda o sistema.
- Contratos de API gerados do código (OpenAPI).
Veja também: Fundamentos de arquitetura.
- Para se aprofundar: c4model.com e Desvendando arquitetura de sistemas com o modelo C4