Registros de Decisão de Arquitetura

O que você leva

• ADR em PT-BR pronto para revisão, com contexto, critérios, alternativas, decisão, justificativa, consequências, riscos, mitigação e aprovações necessárias.
• Pare de perder decisões importantes em Slack, Jira e memória do time: registre o racional técnico em ADRs claros.
• Problema: Times técnicos tomam decisões relevantes em reuniões, PRs e chats, mas depois perdem o racional, repetem discussões, dificultam onboarding e assumem riscos sem rastreabilidade.
• Fluxo: Documentar

Exemplo de pedido pronto

Crie um ADR em PT-BR para uma SaaS brasileira que está decidindo entre usar PostgreSQL ou MongoDB para armazenar pedidos e pagamentos via Pix e boleto.

Esta é uma das skills que a gente deixa aberta pra leitura. O arquivo abaixo é exatamente o que quem tem o catálogo completo recebe — entrada, passos, revisão e formato de saída. Use no seu assistente e adapte ao seu contexto.

---
name: "registros-de-decisao-arquitetura"
description: "Cria, revisa e padroniza ADRs em PT-BR para decisões técnicas, com contexto brasileiro, riscos, LGPD e checklist de revisão humana."
---

# Registros de Decisão de Arquitetura

Skill para transformar decisões técnicas relevantes em ADRs, ou Registros de Decisão de Arquitetura, curtos, versionados e úteis. Use para documentar o racional por trás de escolhas de arquitetura, tecnologia, integração, segurança, cloud, dados, pagamentos, fiscal ou descontinuação. O objetivo não é criar burocracia: é evitar que decisões importantes fiquem perdidas em Slack, Jira, PRs ou na memória de poucas pessoas.

## Quando Usar

Use quando houver decisão técnica com impacto em custo, manutenção, segurança, disponibilidade, dados, integração ou estratégia do produto. Exemplos:
- Escolher PostgreSQL, MongoDB, Redis, fila, framework, provedor cloud ou padrão de API.
- Decidir entre gateway de Pix/boleto/cartão e integração direta com banco ou adquirente.
- Integrar NF-e/NFS-e via provedor fiscal, ERP ou solução própria.
- Migrar monólito para eventos, microserviços ou arquitetura modular.
- Descontinuar tecnologia legada ou substituir fornecedor.
- Revisar ADR existente antes de aprovação.

Não use ADR para tarefa trivial, bug pequeno, decisão reversível sem impacto ou documentação que deveria ser tutorial/runbook.

## Resultado Esperado

Entregar um ADR em Markdown, pronto para revisão, com: título, status, data, decisores, contexto, critérios de decisão, opções consideradas, decisão, justificativa, consequências, riscos, mitigação, plano de implementação e revisões necessárias. Se o contexto estiver incompleto, entregar perguntas objetivas ou marcar suposições explicitamente.

Status recomendados: Proposto, Aceito, Rejeitado, Substituído, Depreciado/Descontinuado.

## Entradas Necessarias

Coletar, ou pedir se faltar:
- Problema ou decisão a registrar.
- Contexto do sistema, produto, squad e restrições.
- Opções consideradas, incluindo “não fazer nada” quando fizer sentido.
- Critérios: custo em R$, prazo, complexidade, segurança, LGPD, performance, disponibilidade, manutenção, reversibilidade e lock-in.
- Decisores e partes impactadas.
- Riscos conhecidos, dependências e prazo.
- Onde o ADR será salvo: GitHub/GitLab, Confluence, Notion, Google Docs ou wiki interna.

Nunca invente dados críticos. Se a decisão envolver dados pessoais, pagamentos, fiscal, saúde, segurança ou alto custo, trate como triagem e peça revisão humana.

## Processo

1. Classifique o pedido: criar ADR, revisar ADR, criar template, atualizar índice ou transformar notas em ADR.
2. Confirme se ADR é adequado. Se for decisão simples, sugira registro mais leve.
3. Extraia contexto e lacunas. Faça até 5 perguntas essenciais se faltar informação; se o usuário pediu rapidez, siga com suposições marcadas.
4. Liste alternativas reais. Preferir pelo menos 2 opções e, quando útil, uma opção “manter estado atual”.
5. Compare por critérios: impacto técnico, custo em R$, operação, segurança, LGPD, reversibilidade, lock-in, experiência do usuário e prazo.
6. Redija a decisão sem vender certeza absoluta. Explique por que a opção escolhida é adequada ao contexto informado.
7. Registre consequências positivas e negativas. Não esconda trade-offs.
8. Adicione riscos, mitigação e gatilhos de revisão futura.
9. Marque revisões humanas obrigatórias quando houver segurança, LGPD, fiscal, jurídico, financeiro ou alta criticidade.
10. Sugira nome de arquivo: `docs/adr/0001-titulo-curto.md` e atualização de `docs/adr/README.md` quando aplicável.

Template base:
```md
# ADR-000X: Título da decisão

- Status: Proposto | Aceito | Rejeitado | Substituído | Depreciado
- Data: AAAA-MM-DD
- Decisores: nomes ou papéis
- Áreas impactadas: produto, engenharia, dados, financeiro, suporte etc.

## Contexto

## Critérios de decisão

## Opções consideradas
1. Opção A — prós, contras, riscos
2. Opção B — prós, contras, riscos
3. Manter situação atual — quando aplicável

## Decisão

## Justificativa

## Consequências
- Positivas:
- Negativas / trade-offs:

## Riscos e mitigação

## Plano de implementação

## Revisões necessárias

## Decisões relacionadas
```

## Ferramentas E Artefatos

Funciona bem com GitHub, GitLab, Azure DevOps, VS Code, Jira, Confluence, Notion, Google Docs, Slack e Microsoft Teams. Artefatos comuns: Markdown, `README.md`, `template.md`, pull request, wiki de arquitetura, checklist de revisão e índice de ADRs. Ferramentas como `adr-tools` podem ajudar, mas não são requisito.

## Exemplo Brasileiro

Pedido: “Somos uma SaaS B2B brasileira. Precisamos escolher entre PostgreSQL e MongoDB para pedidos e pagamentos via Pix e boleto. Temos 8 devs, usamos GitHub e precisamos auditar conciliação.”

Saída esperada: ADR em PT-BR com status Proposto; critérios como consistência transacional, conciliação de pagamentos, relatórios financeiros, custo em R$, maturidade do time, LGPD e operação; comparação PostgreSQL vs MongoDB vs manter solução atual; decisão justificada; riscos como modelagem rígida, gargalo de queries, retenção de dados pessoais; mitigação com índices, migrações, backups, segregação de dados sensíveis e revisão por segurança/DPO.

Outros bons casos brasileiros: integração NFS-e via provedor fiscal, escolha de gateway Pix/boleto, retenção de logs com dados pessoais, troca de cloud por custo em real, migração de checkout monolítico para eventos.

## Criterios De Qualidade

Um bom ADR deve:
- Ser compreensível para uma pessoa nova no time em 10 minutos.
- Explicar o contexto e a decisão, não apenas a solução.
- Ter alternativas reais e critérios explícitos.
- Mostrar consequências negativas e riscos, não só benefícios.
- Separar fatos, suposições e pendências.
- Indicar responsáveis, status e próxima revisão.
- Usar português brasileiro claro, mantendo termos técnicos conhecidos quando úteis.
- Não prometer conformidade jurídica, fiscal, médica, financeira ou de segurança.

Falhas comuns: ADR genérico, uma única opção, “porque é melhor”, ausência de riscos, omissão de custo/lock-in, incluir dados sensíveis, ou transformar ADR em tutorial de implementação.

## Cuidados, LGPD E Escalacao Humana

Privacidade e segurança:
- Não incluir CPF, e-mail de cliente, telefone, endereço, chaves de API, tokens, senhas, dumps de produção ou detalhes exploráveis de vulnerabilidade.
- Usar exemplos anonimizados e categorias de dados, não dados reais.
- Para dados pessoais, registrar finalidade, categorias, retenção, acesso, compartilhamento, controles e necessidade de revisão por DPO/jurídico.

Escalar para humanos:
- Segurança: autenticação, criptografia, exposição pública, permissões, segredos, vulnerabilidades ou dados sensíveis.
- Jurídico/DPO: LGPD, base legal, retenção, transferência internacional, consentimento ou compartilhamento com terceiros.
- Fiscal/contábil: NF-e, NFS-e, SPED, impostos, obrigações acessórias ou integração fiscal.
- Liderança/financeiro: custo relevante em R$, lock-in, disponibilidade, risco de receita ou baixa reversibilidade.

Disclaimers obrigatórios: ADR é documentação técnica e checklist de decisão; não substitui parecer jurídico, auditoria de segurança, validação fiscal, aconselhamento financeiro ou aprovação executiva.

Casos adversariais a bloquear ou redirecionar: pedido para esconder riscos, aprovar decisão insegura sem mitigação, incluir segredos, afirmar “está 100% conforme LGPD”, ou decidir sozinho sobre tema regulado.

## Smoke Test

Prompt: “Crie um ADR em PT-BR para uma SaaS brasileira que está decidindo entre usar PostgreSQL ou MongoDB para armazenar pedidos e pagamentos via Pix e boleto.”

Deve passar se retornar Markdown com status, contexto brasileiro, critérios de decisão, pelo menos duas alternativas, decisão justificada, consequências positivas e negativas, riscos, mitigação, plano de implementação e revisões humanas para segurança/LGPD quando aplicável. Deve falhar se der resposta genérica, sem alternativas, sem riscos, com certeza jurídica ou contendo dados pessoais/segredos reais.