Lightweight Architecture Decision Records とは?
Lightweight Architecture Decision Records とは、 重要なアーキテクチャの意思決定を背景と結果とともに記録する手法 です。
Architecture Decision Records は ADR とも呼びます。
一般にこれらは Wiki や コラボレーションツールに保存されます。
ADRにお役立ち情報
以下のリポジトリに実際に ADR を導入する際の手順などがまとまっています。
と言ってもシンプルなもので、実際にやることといえば
- テンプレートを決める
- ファイル名のフォーマットを決める
- アーキテクチャの意思決定をする
- 意思決定内容をテンプレートにそって記載してバージョン管理ツールに残す
このぐらいです。
ツール
インストール
$ brew install olleolleolle/adr-tools/adr_tools
試行
- 全体のヘルプ確認
$ adr help usage: /usr/local/bin/adr-help COMMAND [ARG] ... COMMAND is one of: generate help init list new Run 'adr help COMMAND' for help on a specific command. ~
- init のヘルプ確認
$ adr help init usage: adr init [DIRECTORY] Initialises the directory of architecture decision records: * creates a subdirectory of the current working directory * creates the first ADR in that subdirectory, recording the decision to record architectural decisions with ADRs. If the DIRECTORY is not given, the ADRs are stored in the directory `doc/adr`.
- init を実行
$ adr init sample_adr sample_adr/0001-record-architecture-decisions.md $ cat sample_adr/0001-record-architecture-decisions.md # 1. Record architecture decisions Date: 21/02/2017 ## Status Accepted ## Context We need to record the architectural decisions made on this project. ## Decision We will use Architecture Decision Records, as described by Michael Nygard in this article: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions ## Consequences See Michael Nygard\'s article, linked above.
- new で新たなADRを記載する
$ adr new "サンプルADR" # エディタが起動するので ADR の中身を記載する $ cat sample_adr/0002-adr.md # 2. サンプルADR Date: 21/02/2017 ## Status Accepted ## Context コンテキストだよ ## Decision 決定事項だよ ## Consequences 結果だよ
- list で一覧を確認する
$ adr list sample_adr/0001-record-architecture-decisions.md sample_adr/0002-adr.md
- generate で目次を生成する
$ adr generate toc # Architecture Decision Records * [1. Record architecture decisions](0001-record-architecture-decisions.md) * [2. サンプルADR](0002-adr.md)
事例
ADR の事例として Clojure の Web Application Framework である Arachne Web Framework をみてみましょう。
ADR
2つだけピックアップ。
- モジュールローディングのアーキテクチャのARD - adr-004-module-loading.md
- DB Migration のアーキテクチャのARD - adr-016-db-migrations.md
まとめ
アーキテクチャの意思決定の記録を残している現場はどのくらいあるのだろう?
実際にそういった記録があることの恩恵の生の声をきいてみたいですね。
おまけ
この記事を投稿する前にアンケートを投げておきました。
結果はどうなるかな?
【アンケート】アーキテクチャ設計の意思決定の過程(何故そうしたか?どのような効果を期待しているか?)をドキュメント化していますか?
— てぃーびー📺 (@tbpgr) 2017年2月21日