IT 技書の森

ADR

アーキテクチャ上の意思決定とその背景・理由を記録する軽量なドキュメント形式

ドキュメントアーキテクチャ

ADR とは

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

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

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-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 の作成を自動化
npm install -g adr-log
adr new "Use DynamoDB for order management"

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

関連用語