如何用 Log4brains 避免架构决策丢失在代码中

有没有遇到过这种情况：看到一个一年半前的模块，发现一个奇怪的架构决策，却完全不理解当初为什么要这样做？你的手痒得想重写它。但后来你发现，这个设计是为了解决第三方 API 的某个 bug 或满足特定的安全需求。当初提出这个方案的人早就转到其他团队了，Confluence 上一片空白，git 历史里只剩下一个写着 laconic fix: refactor storage 的提交记录。

架构决策记录（ADR）概念已经解决这个问题十三年了。但手动维护 markdown 文件并保持条理清晰，通常是每个人都想偷懒的事情。法国开发者 Thomas Vaillant 创建了 Log4brains，一款将架构决策捕获转变为便捷 docs-as-code 工作流的工具。

这个工具是什么

Log4brains 会获取你存储在代码仓库中的 ADR，解析它们，然后构建一个带有便捷搜索和时间线的快速静态站点。

该工具使用 TypeScript 编写，通过命令行运行。不过，这个项目并不依赖 JS 生态。你可以通过全局 npm 包或 Docker 镜像在 Python、Go、Java 或 Rust 仓库中运行它。

ADR 的核心在于这些文档是不可变的。你记录问题、背景、选择的方案和后果。如果一年后某个决策过时了，你不会去修改旧文件。你会创建一个新的 ADR，并设置 supersedes 状态来引用之前的文档。思考历史得以完整保留。

Log4brains 能做什么

在底层，这个工具隐藏了几个实用的功能，在处理文档时能节省大量时间。

带热重载的本地预览

在 IDE 中编写文档时，无需手动频繁重建静态站点。执行 log4brains preview 命令会启动一个基于 Next.js 的本地服务器，支持热重载。你保存了 .md 文件，浏览器立即更新。

无严格限制的交互式 CLI

许多 ADR 工具要求严格的文件编号，如 adr-0001.md、adr-0002.md。在并行处理 pull request 时，这会成为噩梦——两个开发者可能创建了相同编号的文档。

Log4brains 不依赖僵化的编号。元数据（作者、创建日期、状态）从文本和 git log 中读取。模板可以根据你的需求自定义，不过默认使用的是经过验证的 MADR 格式。

创建新记录的流程很简单：

log4brains adr new

该命令会交互式地询问标题，从模板创建 markdown 文件，并将其放入项目结构中。

支持 Monorepo

如果项目拆分为多个包，通常希望文档也能分离。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

如果你有 monorepo，可以扩展结构：

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

最有价值的部分是将知识库部署到外部，让团队可以通过 Web 界面搜索解决方案。由于构建输出的是干净的静态文件，推送到 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/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: .log4brains/out
          TARGET_FOLDER: log4brains

一个重要的细节：注意 fetch-depth: 0。该工具绝对需要完整的提交历史来提取每个文档的实际创建日期和作者。

谁会从这个项目中受益

Log4brains 非常适合 3-4 名或更多工程师的团队，在那里人们会周期性地问类似"为什么我们选择这个库/数据库/模式"的问题。

这个工具很好地融入了代码审查流程。你在 pull request 中讨论架构，将代码和 .md 文件合并到同一个提交中。文档不再在遗忘的 wiki 页面上独立生存——它会在部署过程中自动更新。

如果项目很小，而且你是独自工作，记录决策的开销可能看起来不必要。但对于长期维护的产品来说，这是保留决策上下文最轻松的方式之一。