# adr-decision-platform ADRs e RFCs em MADR, Nygard e Y-statement, com índice navegável e sync do GitHub - URL: https://fernando.moretes.com/open-source/adr-decision-platform - Markdown: https://fernando.moretes.com/open-source/adr-decision-platform/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/ref-adr-decision-platform - Language: TypeScript - Topics: - Stars: 0 - Forks: 0 - Updated: 2026-09-29T16:22:14Z --- 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 - **Template MADR:** ADR em Markdown com status, contexto, decisão e consequências. - **ADR Nygard:** o formato curto original, para decisões que cabem em uma página. - **Y-statements:** captura da decisão em uma frase, para times que decidem rápido. - **Template de RFC:** para propostas que afetam mais de um time antes de virar decisão. - **Navegador de ADRs:** filtro por status, tag e data em um índice único. - **Integração com GitHub:** sincroniza os ADRs que já estão em `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.git` e entre no diretório. O código da aplicação mora em `frontend/`, 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 dev` falha 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 dev` e abra `http://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. _Quickstart completo_ ```bash 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:3000 ``` ## Como 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. ### ▲ Vercel: Next.js 16 - Templates MADR · Nygard · Y · RFC (frontend) - Editor ADR / RFC (frontend) - ADR browser status · tag · data (frontend) - GitHub sync leitura de docs/adr/ (compute) ### 🌐 GitHub: repositórios - docs/adr/ de qualquer repo (external) ### 🔧 CI: GitHub Actions - CI · Frontend Security · Vercel (ci) ### Fluxos - architect -> templates: escolhe o formato - templates -> editor: preenche - editor -> browser: publica no índice - repo -> sync: ADRs existentes - sync -> browser: entra no mesmo índice - architect -> browser: consulta e revisita - ci -> browser: build e deploy ## 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 - [GitHub: fernando-moretes/ref-adr-decision-platform](https://github.com/fernando-moretes/ref-adr-decision-platform) - [MADR: Markdown Architectural Decision Records](https://adr.github.io/madr/) - [Michael Nygard: Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [ADR GitHub organization: templates and tooling](https://adr.github.io/) ## 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. ## Links - [GitHub repository](https://github.com/fernando-moretes/ref-adr-decision-platform)