Log4brainsでコード内の設計判断を失わないようにする
1年半前のモジュールを見て、奇妙な設計判断を見つけ、その理由が本当に理解できない経験はありませんか？書き直したくなる衝動にかられます。しかし、この癖がサードパーティAPIのバグや特定のセキュリティ要件を回避するために特別に設計されたものであることが判明する場合があります。着想を得た人はとうに別のチームに移動しており、Confluenceは空で、gitに残っているのは簡潔なコミットメッセージだけです。
Architecture Decision Records（ADR）の概念は、13年間この問題を解決してきました。しかし、markdownファイルを手動で維持し、整理整頓することは、誰もが必要以上に怠惰になりがちな作業です。フランス人開発者のThomas Vaillantは、設計判断の記録を便利なdocs-as-codeワークフローに変換するツールLog4brainsを作成しました。
このツールとは
Log4brainsは、リポジトリ内のソースコードと一緒に保存されたADRを取得し、解析して、便利な検索とタイムライン機能を備えた高速な静的サイトを構築します。
このユーティリティはTypeScriptで書かれており、コマンドラインから実行されます。ただし、プロジェクトはJSエコシステムに依存していません。グローバルnpmパッケージまたはDockerイメージを通じて、Python、Go、Java、またはRustのリポジトリで実行できます。
ADRのポイントは、これらのドキュメントが不変であることです。問題、文脈、選択したオプション、結果を記録します。決定が1年後に時代遅れになった場合、古いファイルを遡及的に編集しません。前のドキュメントを参照するsupersedesステータスを持つ新しいADRを作成します。思考の歴史はそのまま保持されます。
Log4brainsでできること
ユーティリティの裏には、ドキュメント作業時間を節約するいくつかの実践的な機能が隠されています。
ホットリロード対応のローカルプレビュー
IDEでドキュメントを作成している場合、静的サイトを常に手動で再構築する必要はありません。log4brains previewコマンドはNext.jsベースのローカルサーバーを起動し、Hotreloadに対応します。adr-0001-choose-database.mdファイルを保存すると、ブラウザが即座に更新されます。
柔軟な制限のないインタラクティブCLI
多くのADRユーティリティは0001-architecture.md、0002-database.mdのような厳格なファイル番号付けを要求します。これは、2人の開発者が同じ番号のドキュメントを作成する並列プルリクエスト時に悪夢になります。
Log4brainsは厳格な番号付けに依存していません。メタデータ（作成者、作成日、ステータス）はテキストとgitログから読み取られます。テンプレートはニーズに合わせてカスタマイズできますが、デフォルトでは十分に実証されたMADR形式が使用されます。
新しいレコードの作成はシンプルに:
log4brains newコマンドはタイトルを対話的に尋ね、テンプレートからmarkdownファイルを作成し、プロジェクト構造に配置します。
モノレポサポート
プロジェクトが複数のパッケージに分割されている場合、ドキュメントは分離されることが望まれることが多いです。Log4brainsはdocs/ディレクトリ内のグローバルなトップレベルの決定と、パッケージ依存のレコードを処理できます。
始め方
すべてはターミナルでの数コマンドから始まります。Node.js LTSとGitが必要です:
npx log4brains initセットアップウィザードはいくつかの基本的な質問をし、log4brains.config.js設定ファイルを作成し、プロジェクトにテンプレートを追加し、最初のようこそADRを生成します。
設定はコンパクトになります:
log4brains.config.jsモノレポをお持ちの場合、構造を展開できます:
log4brains.config.jsCI/CDへの公開
最も価値のある部分は、チームがWebインターフェースで解決策を検索できるように、ナレッジベースを外部に展開することです。ビルドがクリーンな静的ファイルを出力するため、GitHub Pages、GitLab Pages、またはS3に簡単にプッシュできます。
GitHub Actionsの例:
log4brains.yml重要な詳細：fetch-depth: 0に注意してください。ユーティリティは、各ドキュメントの実際の作成日と作成者を抽出するために、完全なコミット履歴を絶対に必要とします。
このプロジェクト誰が恩恵を受けるか
Log4brainsは、3〜4人以上のエンジニアのチームに最適です。定期的に「なぜこのライブラリ/データベース/パターンを選択したのですか」という質問が発生するような環境に向いています。
このツールはコードレビュープロセスにもうまく適合します。プルリクエストでアーキテクチャについて議論し、adr/ディレクトリ内のファイルと同じコミットでコードをマージします。ドキュメントは忘れられたWikiページで別個の жизньを生きるのではなく、デプロイメント中に自動的に更新されます。
プロジェクトが小さく一人で作業している場合、判断を記録するオーバーヘッド是不必要に感じるかもしれません。しかし、長期間運用される製品にとっては、判断のコンテキストを保持する最も痛みのない方法の1つです。
関連プロジェクト