ADR

ADR とは

ADR (Architecture Decision Record) は、アーキテクチャ上の重要な意思決定を、タイトル、ステータス、コンテキスト、決定内容、結果の構造で記録する軽量なドキュメント形式である。Michael Nygard が 2011 年に提唱し、コードと同じリポジトリで管理する。

「なぜ DynamoDB を選んだのか」「なぜ REST ではなく GraphQL にしたのか」を後から振り返れるようにする。

ADR のテンプレート

ADR のテンプレートの例を示す。

# ADR-001: データベースに DynamoDB を採用

## ステータス
承認済み (2026-03-20)

## コンテキスト
注文管理システムのデータベースを選定する必要がある。
要件: サーバーレス構成、低レイテンシ、自動スケーリング。

## 検討した選択肢
1. DynamoDB: サーバーレス、自動スケーリング、シングルテーブル設計
2. Aurora Serverless v2: SQL、リレーショナル、自動スケーリング
3. PostgreSQL on RDS: SQL、豊富な機能、手動スケーリング

## 決定
DynamoDB を採用する。

## 理由
- Lambda との親和性が高い (IAM 認証、VPC 不要)
- オンデマンドキャパシティで使用量に応じた課金
- シングルテーブル設計でアクセスパターンを最適化

## 結果
- シングルテーブル設計の学習コストが発生する
- 複雑な JOIN が必要なクエリは DynamoDB では困難
- 分析用途には Athena + S3 エクスポートで対応する

ADR の構造

ADR は 1 つの意思決定につき 1 ファイルで、以下のセクションで構成される。コンテキストで「なぜ決定が必要になったか」を説明し、検討した選択肢を列挙した上で、採用した選択肢とその理由を記録する。結果にはトレードオフや今後の影響を記載する。

セクション	内容
タイトル	決定の要約 (ADR-001: xxx を採用)
ステータス	提案中 / 承認済み / 廃止 / 置き換え
コンテキスト	決定が必要になった背景・制約
検討した選択肢	比較した代替案
決定	採用した選択肢
理由	なぜその選択肢を採用したか
結果	決定によるトレードオフ、影響

ADR を書くべきタイミング

• プログラミング言語やフレームワークの選定
• データベースの選定
• アーキテクチャパターンの採用 (マイクロサービス、モノリス)
• 認証方式の選定 (Cognito、Auth0)
• CI/CD パイプラインの設計
• 重要なライブラリの採用・変更

ファイル管理

ファイル管理を図で示す。

docs/
  adr/
    0001-use-dynamodb.md
    0002-adopt-next-js.md
    0003-use-cognito-for-auth.md
    0004-replace-rest-with-graphql.md

Git リポジトリに含めることで、コードの変更と意思決定の履歴が紐づく。

ADR のメリット

• 新メンバーが「なぜこの技術を使っているのか」を理解できる
• 同じ議論を繰り返さない (過去の検討結果を参照)
• 決定を覆す際に、元の理由と現在の状況を比較できる

adr-tools

adr-tools の例を示す。

# ADR の作成を自動化
npm install -g adr-log
adr new "Use DynamoDB for order management"

実務での活用方法は関連書籍にも詳しい。