Architectural Decision Records

Keywords

最近、社内の一部プロダクトで導入されたArchitectural Decision Recordsについて。

github.com

文字通りアーキテクチャ決定の経緯について記録することを意味する。

決定の背景と結果が共有されることは、変化するソフトウェア開発において変更の判断や再検討のコストを大きく削減することができるだろう。

Architectural Decision Recordsはドキュメントの形式について規定はないが、テキストファイルとしてプロジェクトのソースコードと同じバージョン管理下に置かれることがよいと思われる。

$ mkdir doc/adr
$ vim database.txt

よく見られるフォーマットでは以下のような項目が採用されるようだ。

  • Title
    • 原則として1ファイルには1つの決定事項のみが記述される
  • Date
    • commit日時で分かるだろうという気もしないでもないけれど、技術選定には時代背景がそれなりに影響するので少なくとも日時が分かる状態であることは望ましい
  • Status
    • 承認された状態は Accepted
    • Proposed の状態でPull Requestを出すことはあるのだろう…が、取り込む場合には Accepted にする？？
    • 新しい技術に置き換わった場合は Deprecated などにして新しいドキュメントへのポインタを示すのが良さそう
  • Context
    • 技術選定に関わる背景について事実のみを記載する
    • ビジネス上の事情などでは経営層と現場での感覚の違いによって大いに主観が混ざってしまう部分な気もする
    • 組織の状況が最も影響しそうな感じであるかなあ
  • Decision
    • 決定について記すメインの項目
    • 具体的な判断はここに書くのか他の場所に書くのか迷う
  • Consequences
    • 適用後の状況について、ポジティブ/ネガティブ/どちらでもないいずれの結果についても記す
    • 振り返りは大事

この手のドキュメントとして個人的に求めたいのは、「採用したもの」だけではなく、採用されなかった他の選択肢とその検討についての情報が欲しいと思っている。多くの場合、判断はなんらかのトレードオフの結果として行われるので、結論だけで納得できることはないのではないか。

どこまでの決定を残していくかも判断に迷うところだろう。採用しやすいもの判断が明確なものとそうでないものがあり、後者についてのドキュメントが残りにくい状況になる懸念はある。いくつかのサンプルをメモしておく。

雑感

既に私見を交えながら書いてしまっているがメモ。

新機能やUI検討などの文脈では判断に迷うことが多く決定の経緯を残しておくことが多いが、アーキテクチャについては比較的最適解のような選択肢が狭まることからあまり採用経緯を残してこなかった気がする。実際には既存の仕組みが作り変えられない問題が多く発生するわけで、一因としては設計や技術採用の経緯がないためチーム人員の入れ替わりなどで新しく入ったメンバには安心して作り直せないという気持ちが働くのであろう。テストのないソースコードに似ている。

Architectural Decision Recordsはアジャイル/スクラムの文脈で語られ、透明性の確保を補うものとして機能する。 現実的には検索性の問題や膨大なドキュメントを新人が読むのかという問題はあるにしろ、既存メンバが説明の際に説得力をもつ資料として利用できるのは大きい。

意思決定の合理性をどこまで文章化できるかは、ある程度の情報整理能力や慣れが必要という気がする。漫然と決定だけを記されて判断に困るようなドキュメントが残らないように注意したい。

直近見かけたものでは技術選定の理由としてメンバが完熟しているというものがあり一面的には合理性があるようにも思われたが、別の理由として「時間がないので新しい技術を採用する時間がないため」とも併記されており、途端に合理性が揺らいでくるような印象があった。具体的にどれだけの時間があればチームの開発力やビジネス上のニーズに答えられるものだったのかが明確になっていると納得感が出たのだろうか。難しい。

参考記事