So verhindern Sie, dass Architekturentscheidungen im Code verloren gehen – mit Log4brains

Schauen Sie sich jemals ein Modul an, das anderthalb Jahre alt ist, sehen eine seltsame Architekturentscheidung und verstehen genu in nicht, warum sie getroffen wurde? Ihre Hände jucken, es neu zu schreiben. Aber dann erfahren Sie, dass diese Eigenheit speziell entwickelt wurde, um einen Bug in einer Drittanbieter-API oder eine bestimmte Sicherheitsanforderung zu umgehen. Die Person, die sich das ausgedacht hat, ist längst in ein anderes Team gewechselt, Confluence ist leer, und alles, was in git übrig bleibt, ist ein Commit mit dem lakonischen fix: refactor storage.

Das Konzept der Architecture Decision Records (ADR) löst dieses Problem nun schon seit dreizehn Jahren. Aber die manuelle Pflege von Markdown-Dateien und deren Organisation ist normalerweise etwas, wofür jeder zu faul ist. Der französische Entwickler Thomas Vaillant hat Log4brains geschaffen, ein Tool, das die Erfassung von Architekturentscheidungen in einen praktischen Docs-as-Code-Workflow verwandelt.

Was ist dieses Tool

Log4brains nimmt Ihre ADRs, die im Repository neben Ihrem Quellcode gespeichert sind, analysiert sie und erstellt eine schnelle statische Website mit komfortabler Suche und einer Zeitleiste.

Das Tool ist in TypeScript geschrieben und läuft über die Kommandozeile. Das Projekt ist jedoch nicht an das JS-Ökosystem gebunden. Sie können es in Python-, Go-, Java- oder Rust-Repositories über ein globales npm-Paket oder ein Docker-Image ausführen.

Der Sinn von ADRs ist, dass diese Dokumente unveränderlich sind. Sie erfassen das Problem, den Kontext, die gewählte Option und die Konsequenzen. Wenn eine Entscheidung ein Jahr später veraltet ist, bearbeiten Sie die alte Datei nicht rückwirkend. Sie erstellen eine neue ADR mit einem Supersedes-Status, der auf die vorherige verweist. Die Gedankengeschichte bleibt erhalten.

Was Log4brains kann

Unter der Haube verbergen sich mehrere praktische Funktionen, die Zeit bei der Arbeit mit Dokumentation sparen.

Lokale Vorschau mit Hot Reload

Wenn Sie Dokumentation in Ihrer IDE schreiben, müssen Sie die statische Website nicht ständig manuell neu erstellen. Der Befehl log4brains preview startet einen lokalen Server basierend auf Next.js mit Hot Reload. Sie speichern die Datei .md – der Browser aktualisiert sich sofort.

Interaktive CLI ohne starre Einschränkungen

Viele ADR-Tools erfordern eine strikte Dateinummerierung wie adr-0001.md, adr-0002.md. Dies wird zum Albtraum bei parallelen Pull Requests, wenn zwei Entwickler Dokumente mit derselben Nummer erstellen.

Log4brains verlässt sich nicht auf starre Nummerierung. Metadaten (Autor, Erstellungsdatum, Status) werden aus dem Text und dem Git-Log gelesen. Vorlagen können nach Ihren Bedürfnissen angepasst werden, obwohl standardmäßig das bewährte MADR-Format verwendet wird.

Das Erstellen eines neuen Datensatzes sieht einfach aus:

log4brains adr new

Der Befehl fragt interaktiv nach dem Titel, erstellt eine Markdown-Datei aus der Vorlage und platziert sie in der Projektstruktur.

Monorepo-Unterstützung

Wenn das Projekt auf mehrere Pakete aufgeteilt ist, wird die Dokumentation oft getrennt gewünscht. Log4brains kann globale Entscheidungen auf oberster Ebene und paketabhängige Datensätze innerhalb von packages/service-name/docs/adr verarbeiten.

Wie Sie loslegen

Alles beginnt mit ein paar Befehlen im Terminal. Sie benötigen Node.js LTS und Git:

npm install -g log4brains
log4brains init

Der Setup-Assistent stellt ein paar grundlegende Fragen, erstellt die Konfigurationsdatei .log4brains.yml, fügt eine Vorlage zum Projekt hinzu und generiert Ihre erste Willkommens-ADR.

Die Konfiguration ist kompakt:

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

Wenn Sie ein Monorepo haben, können Sie die Struktur erweitern:

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

Veröffentlichung in CI/CD

Der wertvollste Teil ist die externe Bereitstellung der Wissensdatenbank, damit das Team über eine Weboberfläche nach Lösungen suchen kann. Da der Build saubere statische Dateien ausgibt, ist es einfach, sie auf GitHub Pages, GitLab Pages oder S3 zu pushen.

Beispiel für 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

Ein wichtiges Detail: Achten Sie auf fetch-depth: 0. Das Tool benötigt unbedingt die vollständige Commit-Historie, um das tatsächliche Erstellungsdatum und die Autoren jedes Dokuments zu extrahieren.

Wer von diesem Projekt profitiert

Log4brains eignet sich gut für Teams mit 3-4 Ingenieuren oder mehr, in denen people periodisch Fragen stellen wie „Warum haben wir diese Bibliothek/Datenbank/dieses Muster gewählt".

Das Tool passt gut in den Code-Review-Prozess. Sie besprechen die Architektur in einem Pull Request, mergen den Code zusammen mit der Datei .md im selben Commit. Die Dokumentation führt kein eigenständiges Leben auf vergessenen Wiki-Seiten – sie wird automatisch während der Bereitstellung aktualisiert.

Wenn das Projekt winzig ist und Sie allein daran arbeiten, könnte der Aufwand für die Dokumentation von Entscheidungen unnötig erscheinen. Aber für langlebige Produkte ist dies eine der schmerzlosesten Möglichkeiten, den Entscheidungskontext zu bewahren.