アジャイルプロジェクトのアーキテクチャは、別々に記述され定義されなければなりません。すべての意思決定が一度にされるわけでもなく、プロジェクト開始時にすべての意思決定がされてるわけでもありません。
アジャイル手法では、ドキュメンテーションに反対はしませんが、価値のないドキュメンテーションはいけません。チーム自身の助けになるようなドキュメントは価値がありますが、ちゃんと最新化し続けなければなりません。膨大なドキュメントでは、最新化されなくなることでしょう。小さくまとまりのあるドキュメントは少なくとも更新される可能性はありますよね。
また膨大なドキュメントはだれも読みません。たいていの開発者はソースコードサイズの合計よりも(byte的な意味で)大きな仕様書が書かれたプロジェクトを少なくとも1回は経験したことがあるでしょう。開くのにも、読むのにも、更新するのにも、そんなドキュメントは大きすぎます。一口大のピースに分解すれば、すべての関係者にとって消化するのは簡単になりますよね。
プロジェクトが動いている間、追跡するのが難しいことの1つに、ある意思決定の裏に隠された「思い」があります。プロジェクトに新しく参画した人は、それまでに決定されたことに困惑したり、戸惑ったり、喜んだり、怒ったりすることでしょう。理念や因果関係を理解しておかないと、その人は次の2つの選択をすることになります。
- 何も考えず意思決定を受け入れる
もし意思決定がいまだ妥当なものならば、この行動はOKかもしれません。しかしコンテキストが変わって、意思決定が本当は見直されなければならないとしたら、これは良くないことです。 プロジェクトによく理解されずに積み重なった多くの意思決定事項があると、開発チームはどんな変更も怖がり、プロジェクトはその重みに耐えられなくなります。 - 何も考えず決定を覆す
意思決定が立ち戻る必要があるならば、これはOKかもしれません。が一方で、その思いや因果関係を理解せずに決定を覆すことは、プロジェクト全体の価値にダメージを与えることを意味します。 (たとえば、その決定はまだテストされていない非機能要求をサポートするものであった、など)
何も考えず受け入れることも、何も考えず覆すことも避けなければならないのです。
「アーキテクチャ上重要な」決定の記録をキープするようにしましょう。それは構造や非機能の性質、依存関係、インタフェース、構築手法などに影響するものたちです。
1つのアーキテクチャの意思決定の記録(ADR)は、アレグザンダーのパターンとよく似たフォーマットで手短にテキストファイルに記録します。 (意思決定自身がパターンである必要はないけれども、フォースのバランスをどうとったかは共有します)。 各記録はフォースの集合とそれらのフォースに対する1つの意思決定を記述します。 意思決定が中心のピースなので、複数のADRにある特定のフォースが現れるかもしれません。
ADRはプロジェクトのリポジトリの doc/arch/adr-NNN.md に配置します。MarkdownやTextileのような軽量なテキストフォーマット言語を使うとよいでしょう。
ADRは順番に番号を振り、再利用しないようにしてください。
もし決定を覆すことがあれば、古いものはそのままで、置き換えられた印を付けるようにします。
いくつかパート分けしたフォーマットを使います。各ドキュメントを要約するのが簡単になるからです。
ドキュメントの短い名前です。例えば "ADR 1: Ruby on Rails 3.0.10のデプロイ" や "ADR 9: マルチテナント統合のためのLDAP" のようなものです。
このセクションには技術的、政治的、社会的、プロジェクト固有のものを含むフォースを記述します。 これらのフォースはおそらく緊張状態にあるでしょうし、そのように記述すべきです。このセクションを構成する文章は、中立でなくてはなりません。 事実だけを書き下すようにしてください。
このセクションにはこれらのフォースへの対応を書きます。能動的な調子で完全な文章で記述してください。「私たちは〜するだろう」のように。
もし関係者みんなの同意がえられてないならば、その意思決定は「提案中」であり、同意がえられたら「可決」とします。 後にADRを変更したり、決定を覆すときには、その置き換えたADRを参照し、「廃止予定」または「保留」とします。
このセクションには意思決定した後の結果のコンテキストを書きます。「ポジティブ」なものに限らず、すべての結果をリストアップすべきです。 特定の決定はポジティブなもの、ネガティブなもの、どちらともいえないものなど様々な効果をもたらすでしょうが、 それらのすべてが将来のチームやプロジェクトに影響します。
可決
1つのADRには特定のプロジェクトにとっての重要な決定事項1つを書きます。それはプロジェクトの残りのものをどう実行するかに影響するものでしょう。
1つのADRの結果は後続のADRのコンテキストになる可能性が高いです。これはアレグザンダーのパターン・ランゲージの構想とも符合します。
開発者とプロジェクト関係者は、時間が経ってチーム構成が変わったとしても、ADRを参照できます。
事前の決定の裏にある思いは、過去・未来の誰にでも見える化します。 「何を考えてこうしたんでしょうか?」と頭をかきむしることはもはやなく、古い意思決定を変更する時間は プロジェクトのコンテキストにおける変更から明らかになるでしょう。
この記事自体がADRのようなフォーマットになっていることにお気づきでしょうか。 私たちは、このフォーマットをいくつかのプロジェクトで使ってきました。そんなに長い期間ではありませんが、 顧客と開発者双方から、かなりポジティブなフィードバックをもらっています。 ADRを使ったプロジェクトを6〜10人の開発者がローテーションしましたが、みんなADRを読んでコンテキストが分かったと評価しています。
ADRは特に長期的な視点の意図を捉えるのに有効なようです。私たちには現行のシステムを安定させようとしている顧客がいますが、近い将来大きなアーキテクチャの変更をしようとしています。 これらの意図を書き下しておけば、私たちが将来の変更が難しくなるなんてきっとないでしょう。
1つ想定される反論として、これらをコードと一緒にバージョン管理すると、プロジェクトマネージャや顧客関係者、 開発チームのようにバージョン管理をしない人たちがアクセスしにくいじゃないか、というものがあります。 実際に私たちのプロジェクトはほぼすべてGitHubのプライベートリポジトリにあり、masterの最新バージョンへ リンクをはることができます。GitHubは自動的にMarkdownを処理してくれるので、Wikiページと同じくらい フレンドリーなものになります。
ここまでADRは有用なツールであることが示されているので、引き続き使っていきたいと思います。
