Tbpgr Blog

Employee Experience Engineer tbpgr(てぃーびー) のブログ

アーキテクチャの意思決定を記録する Lightweight Architecture Decision Records について

f:id:tbpg:20170221232209p:plain

Lightweight Architecture Decision Records とは?

Lightweight Architecture Decision Records とは、 重要なアーキテクチャの意思決定を背景と結果とともに記録する手法 です。
Architecture Decision Records は ADR とも呼びます。
一般にこれらは Wiki や コラボレーションツールに保存されます。

ADRにお役立ち情報

以下のリポジトリに実際に ADR を導入する際の手順などがまとまっています。

github.com

と言ってもシンプルなもので、実際にやることといえば

  • テンプレートを決める
  • ファイル名のフォーマットを決める
  • アーキテクチャの意思決定をする
  • 意思決定内容をテンプレートにそって記載してバージョン管理ツールに残す

このぐらいです。

ツール

ADRのためのコマンドラインツール adr-tool です

github.com

インストール

$ 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

github.com

2つだけピックアップ。

まとめ

アーキテクチャの意思決定の記録を残している現場はどのくらいあるのだろう?
実際にそういった記録があることの恩恵の生の声をきいてみたいですね。

おまけ

この記事を投稿する前にアンケートを投げておきました。
結果はどうなるかな?

関連資料