Architectural Decision Story · ADS-04
Knowledge as Infrastructure
Como transformar decisões e contexto em artefatos duráveis?
Contexto
Organizações dependem de decisões que ninguém registrou e de regras que vivem na memória de poucas pessoas — e agora também de agentes que só enxergam o que está escrito.
Problema
Wikis desatualizam, conversas se perdem e o porquê de cada escolha desaparece com a rotação do time.
Alternativas consideradas
- Wiki separada do código
- Conteúdo institucional que muda pouco.
- ADRs e regras versionados no repositório
- Decisões técnicas, padrões e restrições que precisam acompanhar o código.
- Contexto gerado automaticamente
- Mapas estruturais derivados do próprio código, para não divergirem dele.
Trade-offs
- Escrever decisões custa tempo agora para economizar muito tempo depois.
- Mais artefatos a manter — mitigado quando são revisados no mesmo PR que o código.
Decisão
Registrar decisões como ADRs, padrões como regras e contexto como arquivos versionados junto ao código, revisados no mesmo fluxo de pull request.
Consequências
- Onboarding de pessoas e agentes parte de uma base coerente.
- Mudanças de arquitetura exigem atualizar a decisão, o que torna a mudança explícita.
Aprendizados
- Conhecimento que não está versionado não existe para o agente — e aos poucos deixa de existir para o time.