Jak przestać gubić decyzje architektoniczne w kodzie dzięki Log4brains

Czy kiedykolwiek patrzyłeś na moduł sprzed półtora roku, widziałeś dziwną decyzję architektoniczną i szczerze nie rozumiałeś, dlaczego została podjęta? Ręce swędzą cię, żeby go przepisać. Ale potem dowiadujesz się, że ta osobliwość została specjalnie zaprojektowana, aby obejść błąd w zewnętrznym API lub konkretne wymaganie bezpieczeństwa. Osoba, która to wymyśliła, dawno temu przeszła do innego zespołu, Confluence jest puste, a wszystko, co pozostało w git, to commit z lakonicznym fix: refactor storage.

Koncepcja Architecture Decision Records (ADR) rozwiązuje ten problem od trzynastu lat. Jednak ręczne utrzymywanie plików markdown i ich organizacja zazwyczaj jest czymś, do czego nikt nie ma ochoty. Francuski programista Thomas Vaillant stworzył Log4brains, narzędzie przekształcające rejestrowanie decyzji architektonicznych w wygodny workflow docs-as-code.

Co to za narzędzie

Log4brains pobiera twoje ADR, przechowywane w repozytorium obok kodu źródłowego, analizuje je i buduje szybką stronę statyczną z wygodnym wyszukiwaniem i osią czasu.

Narzędzie jest napisane w TypeScript i działa przez linię poleceń. Jednak projekt nie jest powiązany z ekosystemem JS. Możesz uruchomić je w repozytoriach Python, Go, Java lub Rust poprzez globalny pakiet npm lub obraz Docker.

Istorą ADR jest to, że te dokumenty są niezmienne. Rejestrujesz problem, kontekst, wybraną opcję i konsekwencje. Jeśli decyzja stanie się nieaktualna za rok, nie edytujesz starego pliku retroaktywnie. Tworzysz nowy ADR ze statusem supersedes, który odwołuje się do poprzedniego. Historia myśli pozostaje nienaruszona.

Co potrafi Log4brains

Pod maską narzędzie ukrywa kilka praktycznych funkcji oszczędzających czas podczas pracy z dokumentacją.

Lokalny podgląd z hot reload

Gdy piszesz dokumentację w swoim IDE, nie ma potrzeby ciągłego ręcznego przebudowywania strony statycznej. Polecenie log4brains preview uruchamia lokalny serwer oparty na Next.js z Hot Reload. Zapisałeś plik .md — przeglądarka natychmiast się aktualizuje.

Interaktywny CLI bez sztywnych ograniczeń

Wiele narzędzi ADR wymaga ścisłego numerowania plików jak adr-0001.md, adr-0002.md. Podczas równoległych pull requestów, gdy dwóch programistów tworzy dokumenty z tym samym numerem, staje się to koszmarem.

Log4brains nie polega na sztywnym numerowaniu. Metadane (autor, data utworzenia, status) są odczytywane z tekstu i git log. Szablony można dostosować do własnych potrzeb, chociaż domyślnie używany jest sprawdzony format MADR.

Tworzenie nowego wpisu wygląda prosto:

log4brains adr new

Polecenie zapyta interaktywnie o tytuł, utworzy plik markdown z szablonu i umieści go w strukturze projektu.

Wsparcie dla monorepozytoriów

Jeśli projekt jest podzielony na wiele pakietów, często желательно oddzielić dokumentację. Log4brains może obsługiwać globalne decyzje na najwyższym poziomie i rekordy zależne od pakietów w packages/service-name/docs/adr.

Jak zacząć

Wszystko zaczyna się od kilku poleceń w terminalu. Będziesz potrzebować Node.js LTS i Git:

npm install -g log4brains
log4brains init

Kreator instalacji zada kilka podstawowych pytań, utworzy plik konfiguracyjny .log4brains.yml, doda szablon do projektu i wygeneruje pierwszy powitalny ADR.

Plik konfiguracyjny okazuje się zwięzły:

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

Jeśli masz monorepo, możesz rozbudować strukturę:

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

Publikacja w CI/CD

Najcenniejszą częścią jest wdrożenie bazy wiedzy zewnętrznie, aby zespół mógł wyszukiwać rozwiązania przez interfejs sieciowy. Ponieważ kompilacja generuje czyste pliki statyczne, łatwo jest przesłać je do GitHub Pages, GitLab Pages lub S3.

Przykład dla 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

Istotny szczegół: zwróć uwagę na fetch-depth: 0. Narzędzie absolutnie potrzebuje pełnej historii commitów, aby wyodrębnić rzeczywiste daty utworzenia i autorów każdego dokumentu.

Kto skorzysta z tego projektu

Log4brains sprawdza się w zespołach od 3-4 inżynierów, gdzie ludzie okresowo zadają pytania w stylu „dlaczego wybraliśmy tę bibliotekę/bazę danych/wzorzec".

Narzędzie dobrze wpisuje się w proces przeglądu kodu. Dyskutujecie o architekturze w pull requeście, łączycie kod wraz z plikiem .md w tym samym commicie. Dokumentacja nie żyje oddzielnym życiem na zapomnianych stronach wiki — jest aktualizowana automatycznie podczas wdrażania.

Jeśli projekt jest mały i pracujesz nad nim sam, narzut związany z dokumentowaniem decyzji może wydawać się niepotrzebny. Ale w przypadku długowiecznych produktów to jeden z najbardziej bezbolesnych sposobów zachowania kontekstu decyzji.