sa-daily-toolkit

A pergunta que me levou a montar este repositório não foi "qual template de ADR é melhor?", foi "onde está a decisão que tomamos há seis meses e por que a tomamos?". Na maioria dos times que vi, a resposta era um fio de chat, um slide de comitê ou um documento que parou na metade.

Arquiteto de soluções troca de contexto o dia inteiro: de manhã uma revisão de custo, à tarde uma proposta entre times, no fim do dia um parecer de segurança. Cada um desses artefatos tem uma estrutura que se repete. Reescrever a estrutura do zero toda vez não é só lento, é o que faz a decisão sair incompleta, porque a energia vai para o formato e não para o conteúdo.

O toolkit é deliberadamente pequeno e opinativo. Ele não tenta ser uma plataforma de governança; tenta reduzir o custo cognitivo de produzir o mesmo tipo de documento pela décima vez e deixar a decisão rastreável num lugar com histórico de commit.

O custo que ele ataca: não é o tempo de escrever o primeiro ADR, é o de reencontrar, auditar e atualizar dezenas deles ao longo de anos.

A estrutura do repositório tem três diretórios e cada um tem um papel só:

• frontend/: a aplicação Next.js 16 (App Router), em TypeScript 5 e Tailwind CSS 4. É onde os templates e calculadoras viram interface.
• docs/: arquitetura, diagramas e os ADRs do próprio toolkit. O projeto usa o formato que recomenda.
• .github/workflows/: quatro pipelines, CI, Frontend, Vercel e Security.

A escolha de ser uma aplicação web e não uma pasta de Markdown tem um trade-off que vale nomear. O ganho: calculadora de sizing e matriz ponderada precisam de conta, e conta em Markdown vira planilha paralela. O custo: para mudar um template você edita código TypeScript, não um arquivo de texto solto, e cada mudança passa pelo pipeline.

Para mim esse custo é aceitável justamente porque o pipeline é o que mantém o artefato confiável. O workflow de Security roda a cada mudança; um template de threat modeling que entra com erro é pior que template nenhum, porque a sessão de ameaças herda o erro sem perceber.

O projeto segue GitFlow e Conventional Commits (CONTRIBUTING.md), o que deixa o histórico legível quando você quiser saber por que um checklist mudou.

Decisão de arquitetura: começo pela matriz de decisão ponderada quando há três ou mais opções. Pesos explícitos obrigam a discussão a acontecer antes do resultado, e não depois. A opção vencedora vira um ADR MADR, com as opções descartadas registradas, porque daqui a um ano a pergunta vai ser "por que não fizemos X?".

Revisão de workload: o checklist do Well-Architected vai pilar por pilar. Não substitui a Well-Architected Tool da AWS; serve como primeira passada rápida antes de abrir a revisão formal.

Threat modeling: colo os prompts num fluxo com LLM para gerar a primeira lista de ameaças, e reviso cada item. O prompt acelera a enumeração; ele não decide o que é risco aceitável. Essa parte continua sendo sua.

Proposta entre times: o pacote de RFC dá a estrutura comum, e as notas de spike registram o que o experimento provou e o que não provou.