# sa-daily-toolkit

Skills, scripts e templates do dia a dia de um SA: ADR, WAF, threat model, sizing, RFC.

- URL: https://fernando.moretes.com/open-source/sa-daily-toolkit

- Markdown: https://fernando.moretes.com/open-source/sa-daily-toolkit/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/ref-sa-daily-toolkit

- Language: TypeScript

- Topics: 

- Stars: 0

- Forks: 0

- Updated: 2026-09-08T20:37:43Z

---

SA Daily Toolkit é o conjunto de templates, prompts e calculadoras que eu uso para produzir os artefatos recorrentes do trabalho de arquiteto — ADR, revisão Well-Architected, threat model, sizing e RFC — sem recomeçar do zero a cada decisão.

## O problema que ele resolve

Um arquiteto de soluções troca de contexto o dia inteiro. De manhã é uma revisão de segurança de um time, à tarde é um sizing para outro, no fim do dia alguém pede uma comparação de três serviços para fechar uma RFC. Cada um desses pedidos gera um artefato — e, sem um padrão, cada artefato nasce diferente: um ADR vira uma thread de chat, um threat model vira quatro slides, uma matriz de decisão vira uma planilha que ninguém mais abre.

O custo disso não aparece no dia em que o artefato é escrito — aparece seis meses depois, quando alguém precisa entender por que aquela decisão foi tomada e não encontra nada além de um resumo de reunião. Depois de anos operando plataformas em que decisões antigas voltam como incidente, aprendi que rastreabilidade é o único produto durável do trabalho de arquitetura. O diagrama envelhece; o registro de por que ele tem aquela forma, não.

Este repositório é a minha resposta: um kit pequeno e opinativo, com um template por tipo de artefato, para que o custo cognitivo de produzir algo bom seja baixo o bastante para eu produzir toda vez, e não só quando sobra tempo.

## O que vem no kit

- **Gerador de ADR** no template MADR — contexto, opções consideradas, decisão e consequências, na ordem em que um leitor futuro precisa delas.
- **Checklists Well-Architected** para os seis pilares, para revisar antes do go-live e não depois do primeiro incidente.
- **Prompts de threat modeling** prontos para colar num fluxo com LLM — o modelo enumera; você decide o que é real.
- **Calculadoras de sizing** para compute, storage e rede, para trocar 'grande' por um número antes de abrir o console.
- **Pacote de templates de RFC** e **matriz de decisão** com critérios ponderados — o peso é a decisão; a nota é só aritmética.
- **Gerador de tech radar** e template de **spike notes** para registrar apostas e experimentos antes que virem lenda oral.

## Como funciona por dentro

Não há backend nem conta AWS envolvida. O toolkit é uma aplicação Next.js 16 (App Router) com React 19, TypeScript 5 e Tailwind CSS 4, que vive inteira em `frontend/`. Cada skill é uma página: você preenche os campos, a página monta o artefato e você leva o resultado para o repositório do projeto real — o toolkit gera, mas não guarda. Essa escolha é deliberada: o lugar de um ADR é ao lado do código que ele explica, não dentro de uma ferramenta que pode sumir.

`docs/` guarda a arquitetura do próprio projeto, seus ADRs e diagramas — o kit usa em si mesmo o que recomenda. `.github/workflows/` tem quatro pipelines: **CI** (typecheck e build), **Frontend**, **Vercel** (deploy) e **Security** (varredura de dependências e segredos). A produção roda na Vercel com DNS pela Cloudflare; `OPERATIONS.md` descreve o GitFlow, os segredos da Vercel e o pipeline de segurança, e `SETUP.md` mostra como ligar Vercel e Cloudflare do zero.

O custo de manutenção é o que me fez escolher esse desenho: uma app estática numa plataforma gerenciada não tem servidor para atualizar, banco para fazer backup nem chave para rotacionar. O que precisa de cuidado é só o que sempre precisa — dependências e o próprio conteúdo dos templates.

## Do pedido ao artefato versionado

O toolkit fica no meio: transforma um pedido em um artefato padronizado, e o artefato vai para o repositório do projeto — não fica na ferramenta.

### 💻 Toolkit — frontend/ (Next.js 16)

- Skills ADR · WAF · threat model · RFC (frontend)
- Calculadoras sizing · matriz ponderada · radar (compute)

### 📁 Repo — docs/ e projeto alvo

- docs/ ADRs e diagramas do próprio kit (data)
- Repositório do projeto ADR ao lado do código (storage)

### 🔧 GitHub Actions

- CI + Frontend typecheck · build (ci)
- Security deps · segredos (security)

### ▲ Vercel + 🌐 Cloudflare

- Vercel deploy da app (edge)
- Cloudflare DNS (network)

### Fluxos

- sa -> skills: preenche o template
- sa -> calc: informa volumes
- skills -> target: artefato copiado e commitado
- calc -> skills: número entra no ADR/RFC
- docs -> skills: o kit documenta a si mesmo
- ci -> vercel: build verde → deploy
- sec -> ci: varredura por PR
- cf -> vercel: resolve o domínio

## Instalar e usar

1. **Clone e entre no frontend** — `git clone https://github.com/fernando-moretes/ref-sa-daily-toolkit && cd ref-sa-daily-toolkit/frontend`. Tudo que roda está nessa pasta; a raiz é documentação e pipelines.

2. **Instale e suba o servidor local** — `npm install` e depois `npm run dev`; abra `http://localhost:3000`. Não há variável de ambiente obrigatória nem credencial de nuvem — se a página não abre, o problema é a versão do Node, não configuração.

3. **Escolha a skill pelo artefato que você deve entregar** — Decisão com custo de reversão alto → ADR. Sistema indo para produção → checklist Well-Architected. Superfície nova exposta → prompts de threat modeling. Três ou mais alternativas → matriz de decisão, nunca parágrafo corrido.

4. **Leve o resultado para o repositório do projeto** — Copie o Markdown gerado para `docs/adr/` (ou o equivalente) do projeto real e abra um PR. O toolkit não persiste nada de propósito: artefato fora de controle de versão é artefato perdido.

5. **Para publicar sua própria cópia** — Siga `SETUP.md` para ligar Vercel e Cloudflare e `OPERATIONS.md` para o GitFlow e os segredos. Os quatro workflows em `.github/workflows/` rodam sem ajuste depois que os segredos da Vercel existem.

_Quickstart local — sem credenciais, sem backend_

```bash
git clone https://github.com/fernando-moretes/ref-sa-daily-toolkit
cd ref-sa-daily-toolkit/frontend
npm install
npm run dev
# open http://localhost:3000 and pick a skill (ADR, WAF review, threat model, sizing, RFC)
```

> **Links do README apontam para o caminho antigo:** Os badges de CI e os links do README ainda referenciam `fernandofatech/sa-daily-toolkit`. O repositório vive hoje em `fernando-moretes/ref-sa-daily-toolkit`; use a URL desta página. Badge quebrado não afeta o código — mas um link que não resolve é o tipo de defeito que eu mesmo aponto em documentação alheia, então está na fila.

## Como eu uso no dia a dia — e onde a ferramenta para

**ADR:** só para decisão cujo custo de desfazer é maior que o custo de escrever. Escolher uma lib de datas não merece ADR; escolher entre uma e várias AWS Organizations, sim. O template MADR força a listar as opções que perderam — é isso que um leitor futuro procura, não a vencedora.

**Well-Architected:** a checklist entra antes do go-live, com dono por item. Item sem dono é item marcado e não feito.

**Threat modeling com LLM:** o prompt produz uma lista longa de ameaças em minutos, e é aí que mora o risco — a lista parece completa e não é. Eu trato a saída como rascunho: corto o que não se aplica ao perímetro real, adiciono o que o modelo não vê (o processo de onboarding, o acesso do fornecedor, a chave estática que ninguém rotaciona) e só então o documento existe. O modelo enumera; a responsabilidade continua sendo minha.

**Matriz de decisão:** o passo que importa é atribuir os pesos antes de pontuar as opções. Peso definido depois da nota vira justificativa retroativa da opção que você já queria — e a matriz, que existia para expor o viés, passa a escondê-lo.

**Sizing:** a calculadora devolve um número de partida, não um veredito. Ela não conhece o padrão de tráfego, o pico sazonal nem a reserva que a área de finanças já comprou. Use o número para abrir a conversa com quem opera, não para encerrá-la.

## Perguntas frequentes

### Preciso de conta AWS ou de alguma credencial para rodar?

Não. É uma app Next.js sem backend; `npm install && npm run dev` em `frontend/` é tudo. As checklists e calculadoras falam de AWS, mas não chamam nenhuma API.

### Onde ficam os artefatos que eu gero?

Com você. O toolkit monta o Markdown e você o commita no repositório do projeto. Não há banco nem armazenamento na ferramenta — de propósito, para que a decisão fique ao lado do código que ela explica.

### Posso adaptar os templates ao padrão da minha empresa?

Sim, é MIT. Faça um fork, ajuste os templates em `frontend/` e publique sua cópia com `SETUP.md`. Se mudar a estrutura do ADR, registre a mudança como ADR — o kit é um bom lugar para praticar o que ele recomenda.

## Referências

- [fernando-moretes/ref-sa-daily-toolkit — GitHub](https://github.com/fernando-moretes/ref-sa-daily-toolkit)
- [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/)
- [AWS Well-Architected Framework — the six pillars](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
- [Next.js documentation](https://nextjs.org/docs)

## Para quem é — e para quem não é

Use este toolkit quando você produz esses artefatos toda semana e o problema é consistência, não conhecimento: você sabe escrever um ADR, só não quer decidir o formato de novo a cada vez. Ele também serve como ponto de partida para um time que ainda não tem padrão nenhum — é mais barato adaptar oito templates do que discutir do zero qual usar. Não use quando sua empresa já tem wiki, template e processo de revisão funcionando; um segundo padrão em paralelo custa mais em manutenção do que o ganho de qualquer template. E não confunda a ferramenta com o julgamento: a calculadora dá o número inicial e o prompt dá a lista inicial — quem assina a decisão continua sendo quem vai operá-la às duas da manhã.

## Links

- [GitHub repository](https://github.com/fernando-moretes/ref-sa-daily-toolkit)