Как перестать терять архитектурные решения в коде с помощью Log4brains

Знакома ситуация, когда смотришь в полуторагодовалый модуль, видишь странное архитектурное решение и искренне не понимаешь, зачем так сделано? Руки чешутся переписать. Но потом выясняется, что именно эта странность обходила баг в стороннем API или специфическое требование безопасности. Человек, который это придумал, давно сменил команду, в Confluence пусто, а в гите остался коммит с лаконичным fix: refactor storage.

Концепция Architecture Decision Records (ADR) решает эту проблему уже лет тринадцать. Но вести markdown-файлы вручную и держать их в порядке обычно всем лень. Французский разработчик Тома Вайян сделал инструмент Log4brains, который превращает фиксацию архитектурных решений в удобный процесс по принципу docs-as-code.

Что это за инструмент

Log4brains берет ваши ADR, лежащие в репозитории рядом с исходным кодом, парсит их и собирает в быстрый статический сайт с удобным поиском и таймлайном.

Утилита написана на TypeScript и работает через командную строку. При этом проект не привязан к JS-стеку. Его можно запускать в Python, Go, Java или Rust-репозиториях через глобальный npm-пакет или Docker-образ.

Смысл ADR в том, что эти документы неизменяемы. Вы фиксируете проблему, контекст, выбранный вариант и последствия. Если через год решение устаревает, вы не редактируете старый файл задним числом. Вы создаете новый ADR со статусом supersedes, который ссылается на предыдущий. История мысли остается нетронутой.

Что умеет Log4brains

Под капотом утилиты скрыто несколько практичных вещей, которые экономят время при работе с документацией.

Локальный предпросмотр с горячей перезагрузкой

Когда вы пишете документацию в IDE, не нужно постоянно пересобирать статику руками. Команда log4brains preview запускает локальный сервер на базе Next.js с Hot Reload. Сохранили .md файл — браузер мгновенно обновился.

Интерактивный CLI без жестких ограничений

Многие утилиты для ADR требуют строгой нумерации файлов вроде adr-0001.md, adr-0002.md. Это превращается в ад при параллельных пулреквестах, когда два разработчика создают документ с одним номером.

Log4brains не привязывается к жесткой нумерации. Метаданные (автор, дата создания, статус) утилита считывает из текста и git-лога. Шаблоны можно настраивать под себя, хотя по умолчанию используется проверенный формат MADR.

Создание новой записи выглядит просто:

log4brains adr new

Команда интерактивно спросит название, создаст markdown-файл по шаблону и откроет его в структуре проекта.

Поддержка монорепозиториев

Если проект разбит на несколько пакетов, документацию часто хотят разделить. Log4brains умеет работать с глобальными решениями верхнего уровня и пакето-зависимыми записями внутри packages/service-name/docs/adr.

Как запустить проект

Стартует все за пару команд в терминале. Вам понадобятся Node.js LTS и Git:

npm install -g log4brains
log4brains init

Мастер настройки задаст пару базовых вопросов, создаст конфигурационный файл .log4brains.yml, положит в проект шаблон и сгенерирует ваш первый приветственный ADR.

Конфиг получается компактным:

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

Если у вас монорепа, структуру можно расширить:

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

Публикация в CI/CD

Самое ценное — выкатить базу знаний наружу, чтобы команда могла искать решения через веб-интерфейс. Поскольку сборка выдает чистую статику, ее легко отправить в GitHub Pages, GitLab Pages или S3.

Пример для 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/github-pages-deploy-action@3.7.1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

Важная деталь: обратите внимание на fetch-depth: 0. Утилите обязательно нужна полная история коммитов, чтобы вытащить реальные даты создания и авторов каждого документа.

Кому проект пригодится

Log4brains подойдет командам от 3-4 инженеров, где люди периодически задают вопросы «а почему мы выбрали именно эту библиотеку/БД/паттерн».

Инструмент хорошо вписывается в процесс код-ревью. Обсудили архитектуру в пулреквесте, смерджили код вместе с .md файлом в том же коммите. Документация не живет отдельной жизнью на забытых вики-страницах, а обновляется автоматически при деплое.

Если проект крошечный и вы пишете его в одиночку, накладные расходы на оформление записей могут показаться лишними. Но для долгоживущих продуктов это один из самых безболезненных способов сохранить контекст решений.