Decision Log¶
Decisões de engenharia que não chegam ao nível de um ADR — escolhas de ferramentas, processo, convenções e trade-offs do dia a dia. Registradas aqui para que a próxima pessoa entenda o "por quê" sem precisar perguntar.
Diferença dos ADRs: ADRs documentam decisões arquiteturais estruturantes (monólito vs microsserviços, schema por módulo). O decision log cobre o restante — ferramentas, processo, convenções de código.
| # | Decisão | Alternativas consideradas | Motivo | Data |
|---|---|---|---|---|
| 1 | uv como package manager |
pip, poetry, pdm | Mais rápido que pip/poetry, lock file determinístico, compatível com PEP 517/518, adoção crescente no ecossistema Python | 2026-02 |
| 2 | ruff para lint + format |
flake8 + black + isort | Substitui três ferramentas em uma, 10-100x mais rápido, mesmas regras | 2026-02 |
| 3 | ty para type checking |
mypy, pyright | Mantido pela Astral (mesma equipe do ruff/uv), mais rápido que mypy, integração natural com o toolchain | 2026-02 |
| 4 | Conventional Commits obrigatório via pre-commit | Sem convenção, commitlint | Mensagens legíveis no changelog, base para automação futura de releases | 2026-02 |
| 5 | Sem threshold de cobertura de testes | Threshold fixo (ex: 80%) | Threshold numérico incentiva testes de qualidade baixa para bater o número. Preferimos cobertura qualitativa de código crítico | 2026-02 |
| 6 | Repositórios sem ABC/interface | Repositórios com protocolo/ABC | Concrete classes são suficientes — não há implementações alternativas planejadas. ABC adiciona indireção sem benefício real | 2026-02 |
| 7 | logfire para observabilidade |
Datadog, New Relic, OpenTelemetry direto | SDK Python first-class, integração nativa com Pydantic/FastAPI/SQLAlchemy, pricing acessível para early stage | 2026-02 |
| 8 | Doppler para secrets | .env files, AWS Secrets Manager, Vault |
Melhor DX que alternatives (UI simples, CLI), sem necessidade de infra própria, suporte a ambientes múltiplos por projeto | 2026-02 |
| 9 | Railway para deploy | AWS, GCP, Fly.io, Render | Menor overhead operacional, deploy simples por Dockerfile, boa integração com GitHub Actions, custo previsível | 2026-02 |
| 10 | Supabase para PostgreSQL | RDS, Neon, PlanetScale | pgvector nativo (necessário para RAG), Supabase CLI para migrations declarativas, preview branches por PR | 2026-02 |
| 11 | Celery + Redis para filas | ARQ, Dramatiq, SQS | Maturidade do ecossistema, compatibilidade com o codebase existente, Redis já usado para outros fins | 2026-02 |
| 12 | PrefixedULID como ID de entidades |
UUID, auto-increment, ULID puro | Prefixo encoda o tipo (depuração em logs), ordenável por tempo, legível em URLs, validação em dois níveis (Python + domínio PostgreSQL) | 2026-02 |
Como adicionar uma entrada¶
Adicione uma linha na tabela quando:
- Uma decisão não óbvia foi tomada e alguém pode questionar depois
- Uma ferramenta foi escolhida sobre alternativas relevantes
- Uma convenção foi definida por razão específica (não apenas preferência)
Não adicione para decisões óbvias, escolhas sem alternativas reais, ou decisões que já estão cobertas por um ADR.
Formato da linha: