MADR

MADR は Markdown Architectural Decision Records の略。 アーキテクチャ上の意思決定を、Markdown で軽量に残すための ADR テンプレート集。

最低限のテンプレート

# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* … <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

<!-- This is an optional element. Feel free to remove. -->
### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* … <!-- numbers of consequences can vary -->

日本語バージョン

# {解決する問題と見出した解決策を表す短いタイトル}

## コンテキストと課題

{コンテキストと課題を記述する。例えば2〜3文の自由記述形式や、状況が伝わるストーリー形式でもよい。課題を疑問文の形で表現し、関連するコラボレーションボードやイシュー管理システムへのリンクを添えてもよい。}

## 検討した選択肢

* {選択肢1のタイトル}
* {選択肢2のタイトル}
* {選択肢3のタイトル}
* … <!-- 選択肢の数は可変 -->

## 決定結果

選んだ選択肢: 「{選択肢1のタイトル}」。理由は {正当化の根拠。例: 必須条件となる決定要因を満たす唯一の選択肢である | {特定の力学}を解消する | … | 総合的に見て最良である（下記参照） } から。

<!-- 以下は任意の項目。不要であれば削除してよい。 -->
### 影響

* 良い点: {ポジティブな影響。例: 望ましい品質特性の1つ以上が改善される、など}
* 悪い点: {ネガティブな影響。例: 望ましい品質特性の1つ以上が損なわれる、など}
* … <!-- 影響の数は可変 -->

使い方

公式ドキュメントでは、まず docs/decisions ディレクトリを作り、そこに adr-template-minimal.md をコピーする運用が紹介されている。

新しい ADR は、例えばこんな名前で追加する。

docs/decisions/0001-use-madr.md
docs/decisions/0002-use-postgresql.md

ファイル名は NNNN-title-with-dashes.md 形式。 番号を振っておくと、意思決定の履歴を時系列で追いやすい。

関連記事