LESSON 25分

ストーリー

高
高橋アーキテクト
この設計、なんでこうなっているか知ってる？
あなた
いえ…。当時のメンバーはもう退職していて、誰も経緯を知らないんです
あ
高
高橋アーキテクト
これが”アーキテクチャの記憶喪失”だ。決定の理由が残っていないから、なぜそうなっているか分からない。結果、同じ議論を何度も繰り返すか、理由なく変更して問題を起こすことになる
あなた
どうすれば防げるんですか？
あ
高
高橋アーキテクト
ADR — Architecture Decision Record だ。アーキテクチャ上の意思決定を、背景と理由とともに記録する。コードコメントとは違う。“なぜその構造にしたか”を未来の自分たちに伝えるためのドキュメントだ

ADRとは

ADR（Architecture Decision Record）は、アーキテクチャに関する重要な意思決定を記録するための軽量なドキュメントです。

interface ADR {
  // メタ情報
  id: string;           // ADR-001
  title: string;        // 短く明確なタイトル
  date: string;         // 決定日
  status: ADRStatus;    // ステータス
  deciders: string[];   // 決定者

  // 本文
  context: string;      // 背景（なぜ決定が必要なのか）
  decision: string;     // 決定（何を決めたか）
  consequences: {       // 結果（どうなるか）
    positive: string[];
    negative: string[];
    neutral: string[];
  };
}

type ADRStatus =
  | "proposed"    // 提案中
  | "accepted"    // 承認済み
  | "deprecated"  // 非推奨（新しいADRで置き換え）
  | "superseded"; // 置き換え済み

ADRのテンプレート

Michael Nygardが提唱した標準テンプレートです。

# ADR-001: APIの認証方式にJWTを採用する

## ステータス
承認済み（2025-03-15）

## コンテキスト
新規APIサービスの認証方式を決定する必要がある。
現在のモノリスではセッションベースの認証を使用しているが、
マイクロサービス化に伴い、サービス間通信での認証も考慮する必要がある。

検討時の制約条件:
- モバイルアプリからのアクセスに対応
- マイクロサービス間でのステートレスな認証
- 既存のユーザーデータベースとの統合

## 決定
JWT（JSON Web Token）を認証方式として採用する。

具体的には:
- アクセストークン: JWT（有効期限15分）
- リフレッシュトークン: Opaque Token（有効期限7日）
- 署名アルゴリズム: RS256（公開鍵暗号方式）

## 結果

### ポジティブ
- サービス間でトークンの検証が可能（各サービスが公開鍵で検証）
- 共有セッションストアが不要になり、インフラがシンプルに
- モバイルアプリとの統合が容易

### ネガティブ
- トークンの即時無効化が困難（有効期限切れを待つ必要がある）
  → 短い有効期限 + ブラックリストで軽減
- トークンサイズがセッションIDより大きい
  → ペイロードを必要最小限にする
- 秘密鍵の管理が必要
  → AWS Secrets Manager で管理

### ニュートラル
- チーム内のJWT実装経験者は2名。他メンバーへの教育が必要
- 既存のセッション認証は段階的に移行する

ADRを書くべきタイミング

書くべき場面例
技術スタックの選択フレームワーク、DB、クラウドサービス
アーキテクチャパターンの採用マイクロサービス、CQRS、Event Sourcing
設計上のトレードオフパフォーマンス vs 可読性
外部サービスの統合決済サービス、認証プロバイダー
コーディング規約の変更テスト戦略、エラーハンドリング方針
// ADRが不要な場合
const noADRNeeded = [
  "変数名の命名",          // コーディング規約で十分
  "UIの色やフォント",      // デザインシステムで管理
  "ライブラリの小さな更新", // CHANGELOG で十分
  "バグ修正の方法",        // PR の説明で十分
];

ADRの管理方法

## ディレクトリ構造

docs/
└── adr/
    ├── 0001-use-jwt-for-authentication.md
    ├── 0002-adopt-postgresql-as-primary-database.md
    ├── 0003-use-nestjs-for-api-services.md
    ├── 0004-implement-event-sourcing-for-orders.md
    └── README.md  ← ADR一覧と概要

## ファイル命名規則
- 連番-kebab-case のタイトル
- 例: 0001-use-jwt-for-authentication.md

## ADR一覧（README.md）
| ID | タイトル | ステータス | 日付 |
|----|---------|-----------|------|
| 001 | API認証にJWTを採用 | 承認済み | 2025-03-15 |
| 002 | PostgreSQLをメインDBに採用 | 承認済み | 2025-03-20 |
| 003 | NestJSをAPIフレームワークに採用 | 承認済み | 2025-04-01 |
| 004 | 注文にEvent Sourcingを適用 | 提案中 | 2025-04-10 |

ADRのベストプラクティス

プラクティス説明
イミュータブル一度承認したADRは変更しない。新しいADRで置き換える
簡潔に1-2ページに収める。長すぎると読まれない
コンテキスト重視「何を」だけでなく「なぜ」を記録する
代替案を記録却下した選択肢とその理由も書く
コードの近くにリポジトリ内の docs/adr/ に保管する

まとめ

ポイント内容
ADRとはアーキテクチャの意思決定を記録する軽量ドキュメント
テンプレートコンテキスト → 決定 → 結果の3部構成
書くタイミング技術選択、パターン採用、トレードオフの判断時
管理リポジトリ内に連番ファイルで保管。イミュータブル

チェックリスト

  • ADRの目的と構造を説明できる
  • ADRを書くべきタイミングを判断できる
  • 標準テンプレートの各セクションを理解した
  • ADRの管理方法を把握した

次のステップへ

次は「RFCプロセスの設計」を学びます。ADRが決定を記録するものなら、RFCは決定に至るまでの議論プロセスを構造化するものです。

推定読了時間: 25分