adr-decision-platform
ADRs e RFCs em MADR, Nygard e Y-statement, com índice navegável e sync do GitHub
git clone https://github.com/fernando-moretes/ref-adr-decision-platform.gitcerca de 4 min · áudio gerado ao tocar
O ADR Decision Platform é uma aplicação web em Next.js 16 para escrever, listar e versionar Architecture Decision Records e RFCs leves, com templates MADR, Nygard e Y-statement e um navegador de decisões filtrável por status, tag e data.
Por que este repositório existe
Depois de anos revisando arquitetura em times diferentes, aprendi que a pergunta mais cara não é "o que decidimos?", é "por que decidimos isso, e o que ainda vale?". A resposta quase sempre está num thread de chat de 2023, num slide que ninguém acha ou na cabeça de quem saiu da empresa.
ADR resolve isso no papel. Na prática, o formato morre por atrito: cada time usa um template, os arquivos ficam espalhados em docs/adr/ de dezenas de repositórios e ninguém sabe quais decisões estão Accepted, quais foram Superseded e quais nunca saíram de Proposed.
Construí esta plataforma para atacar o atrito, não o formato. Ela não inventa um padrão novo: oferece os três que já têm uso consolidado (MADR, Nygard e Y-statement), mais um template de RFC para propostas que cruzam times, e junta tudo num índice só.
O custo que importa aqui é o de manter: escrever um ADR leva 20 minutos. O que pesa é encontrar, revisar e substituir esse ADR dois anos depois, quando o contexto mudou e a decisão precisa ser revisitada.
O que vem no repositório
docs/adr/ de qualquer repositório.Qual template usar
Os três formatos não competem; servem a decisões de peso diferente. A escolha errada é o que faz o time abandonar ADR: template pesado demais para decisão pequena vira burocracia, template leve demais para decisão estrutural vira registro inútil.
| Template | Quando usar | Custo de escrita | Risco |
|---|---|---|---|
| Y-statement | Decisão local, reversível, de um time | Uma frase | Perde o contexto se a decisão crescer |
| Nygard | Decisão de um sistema, com contexto e consequências | Uma página | Não registra as opções descartadas |
| MADR | Decisão estrutural, com opções comparadas | Várias seções | Vira burocracia se usado para tudo |
| RFC | Proposta que cruza times e ainda está em discussão | Documento longo | Fica em Proposed para sempre sem dono |
O Y-statement segue a forma "no contexto de X, diante de Y, decidimos por Z e descartamos W, para atingir Q, aceitando D". Use quando a decisão cabe nisso. Use MADR quando: a decisão afeta mais de um serviço, envolve custo recorrente ou precisa sobreviver a uma auditoria. Use RFC antes do ADR quando a decisão ainda depende do aceite de outro time.
Instalar e rodar localmente
- 1
Clone o repositório
git clone https://github.com/fernando-moretes/ref-adr-decision-platform.gite entre no diretório. O código da aplicação mora emfrontend/, não na raiz. - 2
Confira a versão do Node
O Next.js 16 exige Node.js 20.9 ou mais novo. Com Node 18 o
npm run devfalha antes de subir o servidor. - 3
Instale as dependências
cd frontend && npm install. A stack é Next.js 16, React 19, TypeScript 5 e Tailwind CSS 4. - 4
Suba o servidor de desenvolvimento
npm run deve abrahttp://localhost:3000. Daí você escolhe o template e começa o primeiro ADR. - 5
Leia SETUP.md e OPERATIONS.md antes de publicar
A integração com GitHub e o deploy na Vercel têm configuração própria descrita nesses dois arquivos. Não pule: o README cobre só o caminho local.
git clone https://github.com/fernando-moretes/ref-adr-decision-platform.git
cd ref-adr-decision-platform/frontend
node --version # >= 20.9 for Next.js 16
npm install
npm run dev # http://localhost:3000Como uma decisão percorre a plataforma
Duas portas de entrada: o ADR escrito na própria plataforma a partir de um template, ou o ADR que já existe em docs/adr/ de um repositório. As duas terminam no mesmo índice.
- Templates · MADR · Nygard · Y · RFC
- Editor · ADR / RFC
- ADR browser · status · tag · data
- GitHub sync · leitura de docs/adr/
- docs/adr/ · de qualquer repo
- CI · Frontend · Security · Vercel
Como funciona por dentro
Stack: é uma aplicação Next.js 16 com React 19, TypeScript 5 e Tailwind CSS 4, publicada na Vercel com DNS na Cloudflare. Não há backend separado nem banco que você precise subir para rodar localmente; o código inteiro está em frontend/.
Integração com GitHub: é o ponto que mais muda a operação. Em vez de pedir que o time migre os ADRs para uma ferramenta nova, a plataforma lê o que já está em docs/adr/. O Markdown continua no repositório, versionado pelo Git e revisado em pull request, que é onde a decisão deveria morar. A plataforma vira a camada de leitura, não a fonte da verdade.
Navegador: o filtro por status é o que separa um índice útil de uma pasta de arquivos. Saber que existem 40 ADRs não ajuda; saber que 6 estão Proposed há mais de três meses ajuda.
Pipeline: o repositório traz quatro workflows de GitHub Actions: CI, Frontend, Vercel e Security. Os detalhes de arquitetura estão em docs/architecture.md.
Os badges e links do README apontam para o nome antigo
O repositório foi migrado de fernandofatech/adr-decision-platform para fernando-moretes/ref-adr-decision-platform. O GitHub redireciona o clone, mas os badges de CI do README ainda referenciam o caminho antigo e podem mostrar status desatualizado. Use a URL nova ao clonar e ao abrir issues.
Comece pelos ADRs que você já tem
Se seus repositórios já têm docs/adr/, aponte a sincronização para eles antes de escrever qualquer ADR novo. O primeiro valor da plataforma é mostrar o que já foi decidido e esquecido, não produzir mais documento.
Perguntas frequentes
Preciso de conta na AWS ou de banco de dados para rodar?
Não. O caminho local do README é npm install e npm run dev dentro de frontend/. A configuração do sync com GitHub está em SETUP.md.
Meus ADRs ficam presos na plataforma?
Os ADRs sincronizados continuam como Markdown em docs/adr/ do seu repositório. Se você parar de usar a plataforma, os arquivos continuam onde estavam.
Posso misturar templates no mesmo projeto?
Pode, e na maioria dos times deveria: Y-statement para decisão local, MADR para decisão estrutural. O navegador filtra por status, tag e data, independente do formato.
Qual a licença?
MIT. Pode usar, alterar e redistribuir, inclusive em contexto comercial.
Referências
Para quem é
Use quando: você tem ADRs espalhados em vários repositórios, mais de um time decidindo arquitetura e nenhuma visão de quais decisões estão vivas. Use também como referência de implementação se quiser montar a sua própria ferramenta de decisões em Next.js. Não use se o seu time tem um repositório só e cinco ADRs: uma pasta docs/adr/ e um template MADR resolvem sem mais nada para manter. O ganho aparece na escala, quando o custo de achar a decisão passa a ser maior que o custo de escrevê-la.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser