Comment cesser de perdre les décisions architecturales dans le code avec Log4brains

Vous êtes-vous déjà retrouvé face à un module vieux d'un an et demi, découvrant une décision architecturale étrange, sans vraiment comprendre pourquoi elle avait été prise ? Vos mains vous démangent de le réécrire. Mais vous découvrez ensuite que cette bizarrerie avait été spécifiquement conçue pour contourner un bug dans une API tierce ou une exigence de sécurité particulière. La personne qui l'a conçue a depuis longtemps rejoint une autre équipe, Confluence est vide, et tout ce qui reste dans git est un commit avec le laconique fix: refactor storage.

Le concept d'Architecture Decision Records (ADR) existe depuis treize ans pour résoudre ce problème. Cependant, maintenir manuellement des fichiers markdown et les organiser est généralement quelque chose que personne n'a envie de faire. Le développeur français Thomas Vaillant a créé Log4brains, un outil qui transforme la capture des décisions architecturales en un workflow docs-as-code pratique.

Qu'est-ce que cet outil

Log4brains extrait vos ADR, stockés dans le dépôt aux côtés de votre code source, les analyse, et génère un site statique performant avec une recherche pratique et une frise chronologique.

L'utilitaire est écrit en TypeScript et fonctionne via la ligne de commande. Cependant, le projet n'est pas lié à l'écosystème JS. Vous pouvez l'exécuter dans des dépôts Python, Go, Java ou Rust via un package npm global ou une image Docker.

L'intérêt des ADR est que ces documents sont immuables. Vous enregistrez le problème, le contexte, l'option choisie et les conséquences. Si une décision devient obsolète un an plus tard, vous ne modifiez pas rétroactivement l'ancien fichier. Vous créez un nouveau ADR avec un statut supersedes qui référence le précédent. L'historique des réflexions reste intact.

Ce que Log4brains peut faire

Sous le capot, l'utilitaire cache plusieurs fonctionnalités pratiques qui font gagner du temps lors du travail avec la documentation.

Prévisualisation locale avec hot reload

Lorsque vous écrivez de la documentation dans votre IDE, il n'est pas nécessaire de reconstruire manuellement le site statique en permanence. La commande log4brains preview démarre un serveur local basé sur Next.js avec Hot Reload. Vous avez sauvegardé le fichier .md — le navigateur se met à jour instantanément.

CLI interactif sans restrictions rigides

De nombreux utilitaires ADR nécessitent une numérotation stricte des fichiers comme adr-0001.md, adr-0002.md. Cela devient un cauchemar lors de pull requests parallèles lorsque deux développeurs créent des documents avec le même numéro.

Log4brains ne repose pas sur une numérotation rigide. Les métadonnées (auteur, date de création, statut) sont lues à partir du texte et du log git. Les modèles peuvent être personnalisés selon vos besoins, bien que le format MADR bien éprouvé soit utilisé par défaut.

Créer un nouvel enregistrement semble simple :

log4brains adr new

La commande demandera interactivement le titre, créera un fichier markdown à partir du modèle et le placera dans la structure du projet.

Support des monorepos

Si le projet est divisé en plusieurs packages, la documentation est souvent souhaitée séparée. Log4brains peut gérer les décisions globales de niveau supérieur et les enregistrements dépendants des packages au sein de packages/service-name/docs/adr.

Comment démarrer

Tout commence avec quelques commandes dans le terminal. Vous aurez besoin de Node.js LTS et Git :

npm install -g log4brains
log4brains init

L'assistant de configuration posera quelques questions de base, créera le fichier de configuration .log4brains.yml, ajoutera un modèle au projet, et générera votre premier ADR de bienvenue.

La configuration se révèle compacte :

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

Si vous avez un monorepo, vous pouvez développer la structure :

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

Publication dans la CI/CD

La partie la plus précieuse est de déployer la base de connaissances en externe pour que l'équipe puisse rechercher des solutions via une interface web. Comme la construction génère des fichiers statiques propres, il est facile de les pousser vers GitHub Pages, GitLab Pages ou S3.

Exemple pour 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

Un détail important : faites attention à fetch-depth: 0. L'utilitaire a absolument besoin de l'historique complet des commits pour extraire les dates de création réelles et les auteurs de chaque document.

Qui bénéficiera de ce projet

Log4brains convient bien aux équipes de 3-4 ingénieurs ou plus, où les gens posent périodiquement des questions comme « pourquoi avons-nous choisi cette bibliothèque/cette base de données/ce patron ».

L'outil s'intègre bien dans le processus de revue de code. Vous discutez de l'architecture dans une pull request, vous fusionnez le code avec le fichier .md dans le même commit. La documentation ne vit pas une vie séparée sur des pages wiki oubliées — elle se met à jour automatiquement pendant le déploiement.

Si le projet est minuscule et que vous travaillez seul, la surcharge de documentation des décisions peut sembler superflue. Mais pour les produits durables, c'est l'une des façons les plus indolores de préserver le contexte des décisions.