ADR（アーキテクチャ決定記録）の実践

ストーリー

田

田中VPoE

RFCは「提案と議論」のプロセスだ。次は議論の結果を「永続的に記録」する仕組み — ADRを導入する

あなた

ADR…Architecture Decision Recordですか？

あ

田

田中VPoE

そうだ。「なぜこの技術を選んだのか」「なぜこの設計にしたのか」。半年後、1年後に新しいメンバーが入ったとき、その判断の「なぜ」を知る手段がなければ、同じ議論が何度も繰り返される

あなた

確かに「なぜMongoDBを使っているんですか？」と聞いて「誰も知らない」という状況は見たことがあります

あ

田

田中VPoE

ADRはまさにその問題を解決する。決定の「コンテキスト」「判断理由」「結果」を記録する。RFCで議論して決まったことをADRとして記録する流れだ

ADRとは

基本概念

項目	内容
正式名称	Architecture Decision Record（アーキテクチャ決定記録）
目的	技術的な意思決定の「なぜ」を永続的に記録する
特徴	不変（Immutable）。後で判断が変わった場合は新しいADRで上書き
粒度	1つの決定に対して1つのADR

ADRの価値

価値	説明
新メンバーのオンボーディング	過去の決定の「なぜ」を自分で理解できる
再議論の防止	同じ議論を繰り返さない。既に検討済みの代替案が記録されている
判断の透明性	誰が、いつ、どのようなコンテキストで決定したかが明確
標準の根拠	技術標準の各項目が「なぜそうなっているか」をADRで参照可能
進化の記録	技術標準がどう進化してきたかの歴史がわかる

ADRテンプレート

Michael Nygard形式（推奨）

# ADR-NNNN: [タイトル]

## ステータス

Accepted / Deprecated / Superseded by ADR-XXXX

## コンテキスト

[この決定を行った背景。当時の状況、課題、制約条件を記載]

## 決定

[何を決定したか。明確かつ簡潔に記載]

## 結果

[この決定によって生じるポジティブ・ネガティブな影響]

拡張形式（組織向け推奨）

# ADR-NNNN: [タイトル]

## メタ情報

| 項目 | 内容 |
|------|------|
| ADR番号 | ADR-NNNN |
| ステータス | Accepted |
| 日付 | YYYY-MM-DD |
| 決定者 | [名前・チーム] |
| 関連RFC | RFC-XXXX |
| 影響範囲 | [影響するサービス・チーム] |

## コンテキスト

[決定の背景と制約条件]

## 検討した選択肢

### 選択肢A: [名前]
- メリット: ...
- デメリット: ...

### 選択肢B: [名前]
- メリット: ...
- デメリット: ...

### 選択肢C: [名前]
- メリット: ...
- デメリット: ...

## 決定

[選択肢Xを採用する。理由: ...]

## 結果

### ポジティブな影響
- ...

### ネガティブな影響（トレードオフ）
- ...

### 今後のアクション
- ...

ADRの具体例

例: ADR-0003 バックエンドAPIの主要言語としてGoを採用

# ADR-0003: バックエンドAPIの主要言語としてGoを採用

## メタ情報

| 項目 | 内容 |
|------|------|
| ADR番号 | ADR-0003 |
| ステータス | Accepted |
| 日付 | 2025-06-15 |
| 決定者 | 技術標準委員会 |
| 関連RFC | RFC-0012 |
| 影響範囲 | 全バックエンドチーム |

## コンテキスト

バックエンドAPIの開発言語がGo、Node.js（TypeScript）、Java、
Pythonの4言語に分裂しており、以下の問題が生じている:

- チーム間の人材流動性が低い
- 共通ライブラリが言語ごとに4つ必要
- コードレビューの相互支援ができない
- 運用チームが4つの言語のランタイムを管理

## 検討した選択肢

### 選択肢A: Go
- メリット: 高パフォーマンス、シングルバイナリ、
  並行処理に強い、学習曲線が緩やか
- デメリット: ジェネリクス導入が最近、
  ORM等のライブラリがJavaほど充実していない

### 選択肢B: TypeScript (NestJS)
- メリット: フロントエンドとの共通化、
  NPMエコシステムの充実、型安全性
- デメリット: Node.jsのランタイムパフォーマンス、
  大規模プロジェクトでの型の複雑化

### 選択肢C: Java (Spring Boot)
- メリット: エンタープライズ実績、
  充実したORM、堅牢なエコシステム
- デメリット: 冗長なコード、起動時間の長さ、
  若手エンジニアの敬遠

## 決定

選択肢A: Goを採用する。

理由: APIサービスに求められるパフォーマンス特性に最適。
シングルバイナリによるデプロイの簡素化。
既にAPIチームで2年間の本番実績があり、安定性が実証済み。
採用市場でのGo人材の増加傾向。

## 結果

### ポジティブな影響
- バックエンドの共通言語が確立
- デプロイの簡素化（コンテナイメージの軽量化）
- サービス間のコードレビュー相互支援が可能に

### ネガティブな影響（トレードオフ）
- 既存のJava/Node.jsサービスの移行コストが発生
- フロントエンド（TypeScript）との言語共通化は断念
- データパイプライン（Python）は別管理のまま

### 今後のアクション
- Goプロジェクトテンプレートの作成（2週間）
- Java/Node.jsサービスの移行計画策定（1ヶ月）
- Go研修プログラムの整備（1ヶ月）

ADRの運用ルール

記録のタイミング

タイミング	内容
RFCが承認されたとき	RFCの決定事項をADRに記録
標準が変更されたとき	変更理由と新しい標準をADRに記録
重要な技術選定をしたとき	チームレベルでも影響が大きい決定は記録

ADRのステータス管理

ステータス	意味	対応
Proposed	提案中	議論中（RFC経由）
Accepted	承認済み	現在有効な決定
Deprecated	非推奨	新しい決定に置き換え予定
Superseded	上書きされた	ADR-XXXXが後継

不変性の原則

原則	説明
ADRは修正しない	決定時の内容をそのまま保持する
誤りがあれば新ADRで上書き	「Superseded by ADR-XXXX」と記載
コンテキストは当時のまま	後から「当時はこう考えていた」を改変しない

管理方法

ADRの管理:

保管場所:
├── リポジトリの docs/adr/ ディレクトリ（推奨）
├── 組織共通の tech-standards リポジトリ
└── 両方に配置（サービス固有 + 組織共通）

検索性:
├── 一覧ページ（index.md）を自動生成
├── タグ付け（言語、アーキテクチャ、インフラ等）
└── 全文検索可能な場所に配置

「ADRは”未来の自分たちへの手紙”だ。なぜこう決めたのか、何を考えていたのか。文書に残さなければ組織の記憶は消える」 — 田中VPoE

まとめ

ポイント	内容
ADRの目的	技術的意思決定の「なぜ」を永続的に記録
テンプレート	コンテキスト、検討した選択肢、決定、結果
不変性	ADRは修正しない。変更は新しいADRで上書き
RFCとの連携	RFCで議論→ADRで記録、の流れ

チェックリスト

ADRの目的と価値を理解した
ADRテンプレートの構成要素を理解した
ADRのステータス管理と不変性の原則を理解した
RFCとADRの連携方法を理解した

次のステップへ

次は「レビューとガバナンス体制」を学びます。RFC/ADRプロセスを組織として運用するためのガバナンス体制の設計方法を身につけましょう。

推定読了時間: 30分