Como parar de perder decisões arquiteturais no código com Log4brains

Já olhou para um módulo com mais de um ano e meio de idade, viu uma decisão arquitetural estranha e realmente não entendeu por que foi tomada? Suas mãos coçam para reescrever. Mas então você descobre que essa peculiaridade foi especificamente projetada para contornar um bug em uma API de terceiros ou um requisito de segurança específico. A pessoa que teve essa ideia já se mudou para outro time há muito tempo, o Confluence está vazio, e tudo o que resta no git é um commit com o lacônico fix: refactor storage.

O conceito de Architecture Decision Records (ADR) tem resolvido esse problema há treze anos. Mas manter arquivos markdown manualmente e mantê-los organizados geralmente é algo que todo mundo é preguiçoso demais para fazer. O desenvolvedor francês Thomas Vaillant criou o Log4brains, uma ferramenta que transforma a captura de decisões arquiteturais em um fluxo de trabalho conveniente de docs-as-code.

O que é essa ferramenta

O Log4brains pega seus ADRs, armazenados no repositório junto com seu código-fonte, analisa-os e constrói um site estático rápido com busca conveniente e uma linha do tempo.

O utilitário é escrito em TypeScript e funciona via linha de comando. No entanto, o projeto não está vinculado ao ecossistema JS. Você pode executá-lo em repositórios Python, Go, Java ou Rust através de um pacote npm global ou imagem Docker.

O ponto dos ADRs é que esses documentos são imutáveis. Você registra o problema, contexto, opção escolhida e consequências. Se uma decisão ficar desatualizada um ano depois, você não edita o arquivo antigo retroativamente. Você cria um novo ADR com um status de supersedes que referencia o anterior. O histórico de pensamentos permanece intacto.

O que o Log4brains pode fazer

Por baixo dos panos, o utilitário esconde vários recursos práticos que economizam tempo ao trabalhar com documentação.

Pré-visualização local com hot reload

Quando você está escrevendo documentação no seu IDE, não há necessidade de reconstruir manualmente o site estático constantemente. O comando log4brains preview inicia um servidor local baseado em Next.js com Hot Reload. Você salvou o arquivo .md — o navegador atualiza instantaneamente.

CLI interativo sem restrições rígidas

Muitos utilitários de ADR exigem numeração rígida de arquivos como adr-0001.md, adr-0002.md. Isso se torna um pesadelo durante pull requests paralelos quando dois desenvolvedores criam documentos com o mesmo número.

O Log4brains não depende de numeração rígida. Os metadados (autor, data de criação, status) são lidos do texto e do log do git. Os templates podem ser personalizados para suas necessidades, embora o formato MADR, já comprovado, seja usado por padrão.

Criar um novo registro parece simples:

log4brains adr new

O comando perguntará interativamente o título, criará um arquivo markdown a partir do template e o colocará na estrutura do projeto.

Suporte a monorepositórios

Se o projeto estiver dividido em vários pacotes, frequentemente deseja-se que a documentação seja separada. O Log4brains pode lidar com decisões globais de nível superior e registros dependentes de pacotes dentro de packages/service-name/docs/adr.

Como começar

Tudo começa com alguns comandos no terminal. Você vai precisar do Node.js LTS e do Git:

npm install -g log4brains
log4brains init

O assistente de configuração fará algumas perguntas básicas, criará o arquivo de configuração .log4brains.yml, adicionará um template ao projeto e gerará seu primeiro ADR de boas-vindas.

A configuração acaba sendo compacta:

project:
  name: My Service
  tz: Europe/Moscow
  adrFolder: ./docs/adr

Se você tiver um monorepositório, pode expandir a estrutura:

project:
  name: Core Platform
  tz: Europe/Moscow
  adrFolder: ./docs/adr
  packages:
    - name: auth-service
      path: ./packages/auth
      adrFolder: ./packages/auth/docs/adr
    - name: billing-service
      path: ./packages/billing
      adrFolder: ./packages/billing/docs/adr

Publicação no CI/CD

A parte mais valiosa é implementar a base de conhecimento externamente para que a equipe possa buscar soluções através de uma interface web. Como o build gera arquivos estáticos limpos, é fácil fazer push para GitHub Pages, GitLab Pages ou S3.

Exemplo para GitHub Actions:

name: Publish Log4brains
on:
  push:
    branches:
      - main
jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0 # обязательно, утилите нужна история git
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Build
        run: |
          npm install -g log4brains
          log4brains build --basePath /${GITHUB_REPOSITORY#*/}/log4brains
      - name: Deploy
        uses: JamesIves/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

Um detalhe importante: preste atenção em fetch-depth: 0. O utilitário absolutamente precisa do histórico completo de commits para extrair as datas reais de criação e autores de cada documento.

Quem se beneficiaria deste projeto

O Log4brains é uma boa escolha para equipes de 3-4 engenheiros ou mais, onde as pessoas fazem periodicamente perguntas como "por que escolhemos essa biblioteca/banco de dados/padrão".

A ferramenta se encaixa bem no processo de code review. Você discute arquitetura em um pull request, faz merge do código junto com o arquivo .md no mesmo commit. A documentação não vive uma vida separada em páginas de wiki esquecidas — ela é atualizada automaticamente durante o deploy.

Se o projeto é pequeno e você está trabalhando sozinho, a sobrecarga de documentar decisões pode parecer desnecessária. Mas para produtos de longa duração, esta é uma das formas mais indolores de preservar o contexto das decisões.