Skip to content

Instantly share code, notes, and snippets.

@kawasima
Last active October 1, 2024 12:54
Show Gist options
  • Save kawasima/e325eda1c910d2abc5fb5f69d6a692e2 to your computer and use it in GitHub Desktop.
Save kawasima/e325eda1c910d2abc5fb5f69d6a692e2 to your computer and use it in GitHub Desktop.

アーキテクチャ設計のドキュメンテーション

コンテキスト

アジャイルプロジェクトのアーキテクチャは、別々に記述され定義されなければなりません。すべての意思決定が一度にされるわけでもなく、プロジェクト開始時にすべての意思決定がされてるわけでもありません。

アジャイル手法では、ドキュメンテーションに反対はしませんが、価値のないドキュメンテーションはいけません。チーム自身の助けになるようなドキュメントは価値がありますが、ちゃんと最新化し続けなければなりません。膨大なドキュメントでは、最新化されなくなることでしょう。小さくまとまりのあるドキュメントは少なくとも更新される可能性はありますよね。

また膨大なドキュメントはだれも読みません。たいていの開発者はソースコードサイズの合計よりも(byte的な意味で)大きな仕様書が書かれたプロジェクトを少なくとも1回は経験したことがあるでしょう。開くのにも、読むのにも、更新するのにも、そんなドキュメントは大きすぎます。一口大のピースに分解すれば、すべての関係者にとって消化するのは簡単になりますよね。

プロジェクトが動いている間、追跡するのが難しいことの1つに、ある意思決定の裏に隠された「思い」があります。プロジェクトに新しく参画した人は、それまでに決定されたことに困惑したり、戸惑ったり、喜んだり、怒ったりすることでしょう。理念や因果関係を理解しておかないと、その人は次の2つの選択をすることになります。

  1. 何も考えず意思決定を受け入れる
    もし意思決定がいまだ妥当なものならば、この行動はOKかもしれません。しかしコンテキストが変わって、意思決定が本当は見直されなければならないとしたら、これは良くないことです。 プロジェクトによく理解されずに積み重なった多くの意思決定事項があると、開発チームはどんな変更も怖がり、プロジェクトはその重みに耐えられなくなります。
  2. 何も考えず決定を覆す
    意思決定が立ち戻る必要があるならば、これは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は有用なツールであることが示されているので、引き続き使っていきたいと思います。

Translated https://github.com/adr/adr.github.io/

アーキテクチャ決定録

アーキテクチャ設計 (AD) は、アーキテクチャ上重要な機能・非機能要求へ対処するソフトウェア設計の選択です。 アーキテクチャ要求 (ASR) はソフトウェアシステムのアーキテクチャと品質に計測可能な影響をもたらす要求です。 アーキテクチャ決定録 (ADR) は、1つのADについての個人のノートや議事録を書くときやるようなメモ書きで、 ADRを集めて、プロジェクト単位で作成されメンテナンされる意思決定のログを構成します。 これらすべてがアーキテクチャのナレッジ管理(AKM)のテーマになります。 注目: ADRの短い紹介が、Joel ParkerhendersonのGitHubリポジトリにあります。

GitHub adr organization には以下の目的があります。

  1. 共通のボキャブラリを確立するためのADの必要性とメリットを喚起する。
  2. ADRまわりのツールを強化し、イテレーティブでインクリメンタルなソフトウェアエンジニアリングプロセスと同様にアジャイルプラクティスを支援するものとする。
  3. AKMとADRのコンテキストに関する公開されたナレッジへのポインタを示す。(例えばこのページ)

注意: "アーキテクチャ決定録" という用語は同じ意味で使われます。

ADRの採用

ThoughtWorks は、technology radarの中で、 ADRを"adopt"として位置づけています。

私たちは MADR Markdown ADR (MADR: [ˈmæɾɚ]) を提供しています。

提供プロジェクト

  • MADR - The Markdown Architecture Decision Records (MADR: [ˈmæɾɚ]). Lean ADRs to quickly document architectural decisions in code. - Slogan: architectural decisions that matter [ˈmæɾɚ].
  • adr-toc - Generates a architectural decision log out of MADRs.
  • Embedded Architectural Decision Records, which shows how a distributed AD log can be embedded in Java Code via ADR annotations.
  • eadlsync - Synchronizes embedded architectural decision records with a repository of architectural decitions.
  • SE Repo - Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others.

Relation of ADRs, MADR, and others

ADR

Sustainable Architectural Decisions

We base our work on the guidelines and principles in Sustainable Architectural Decisions by Zdun et al., for instance the Y-statement format suggested in that article. However, we are open to other formats of ADRs as shown at https://github.com/joelparkerhenderson/architecture_decision_record.

In short, that Y-statement is as follows:

In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve <quality q>, accepting <downside d>.

The long form of it is as follows:

In the context of <use case/user story u>, facing <concern c> we decided for <option o> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside d/undesired consequences>, because <additional rationale>.

Related Projects

Existing ADR templates

Tooling

More related work:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment