📝 Cap 15: Documentação Arquitetural Viva: Architecture Decision Records (ADRs) e o Modelo arc42

🗺️ O Ciclo de Governança de Decisões Arquiteturais (ADRs)

flowchart TD
    NEED["Nova Necessidade Técnica ou Dilema Arquitetural"]
    --> PROPOSE["1. Redação de ADR em Markdown (Status: Proposto)"]

    PROPOSE --> DISCUSS["2. Discussão Técnica em Pull Request com o Time"]
    DISCUSS --> DECIDE{"Decisão Aprovada?"}
    
    DECIDE -- "SIM" --> ACCEPTED["3. Status: Aceito (Commit no repositório /docs/adr/)"]
    DECIDE -- "NÃO" --> REJECTED["Status: Rejeitado (Mantido para histórico do porquê NÃO foi feito)"]

    ACCEPTED --> DEPRECATED["4. Anos depois: Status: Substituído por nova ADR (Superceded) ⚡"]

    style NEED fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style PROPOSE fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style ACCEPTED fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style REJECTED fill:#ffebee,stroke:#d32f2f,stroke-width:1.5px
    style DEPRECATED fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px

📖 Fundamentos e Aplicação

A pior pergunta em um projeto de software é: “Por que diabos esse código foi feito desse jeito?”. Na maioria das vezes, a pessoa que tomou a decisão já trocou de empresa e o raciocínio original foi perdido.

Os Architecture Decision Records (ADRs) resolvem esse problema registrando o contexto, as opções avaliadas e as consequências de cada decisão estrutural como arquivos Markdown versionados no próprio repositório.

Estrutura Canônica de uma ADR (Michael Nygard):

Título: ADR-0004: Adoção do PostgreSQL com pgvector para Busca Semântica
Status: Aceito Proposto Rejeitado Substituído por ADR-0012
Contexto: O problema enfrentado e as restrições vigentes.
Decisão: A escolha técnica efetuada e a justificativa.
Consequências: O que se torna mais fácil e os novos trade-offs assumidos (positivos e negativos).

🧭 Navegação Rápida

🧭 Navegação do Capítulo: ⬅️ Capítulo Anterior · 📚 Sumário do Módulo · ➡️ Próximo Capítulo