ストーリー
高
高橋アーキテクト
最後にもう一つ、大切なことを教えよう
高
高橋アーキテクト
アーキテクチャの選定理由を聞かれて、“なんとなく良さそうだったから”と答えるエンジニアは多い。でも、設計判断には必ず理由がある。その理由を記録しておかないと、後から”なぜこうなっているのか”がわからなくなる
あなた
記録…ですか。ドキュメントを書くのは苦手です
あ
高
高橋アーキテクト
大丈夫。ADRは軽量なフォーマットだ。1つの判断につき1ページ。誰でも書ける
ADR（Architecture Decision Record）とは
ADRは、アーキテクチャに関する設計判断とその理由を記録する軽量なドキュメントです。
ADRの基本フォーマット
# ADR-001: ヘキサゴナルアーキテクチャの採用
## ステータス
承認済み（2025-04-01）
## コンテキスト
ECサイトのバックエンドを新規開発する。
決済ゲートウェイ、配送API、在庫管理など外部サービスとの連携が多い。
テスト容易性を確保し、外部サービスの差し替えに対応したい。
## 決定
ヘキサゴナルアーキテクチャ（Ports & Adapters）を採用する。
## 理由
- 外部サービスとの接続をAdapterとして分離できる
- Portを介したテストが容易になる
- 将来的な外部サービスの変更に柔軟に対応できる
- チームメンバーがSOLID原則を習得済みであり、理解しやすい
## 却下した選択肢
- レイヤードアーキテクチャ: 外部連携が多く、テストの困難さが予見される
- マイクロサービス: チーム規模（4名）に対してオーバーエンジニアリング
## 結果
ドメイン層の独立性が保たれ、外部サービスのモック化が容易になった。ADRを書くタイミング
| タイミング | 例 |
|---|---|
| アーキテクチャパターンの選定 | ヘキサゴナル vs クリーン vs レイヤード |
| 技術スタックの選定 | PostgreSQL vs MongoDB |
| 設計方針の決定 | モノリス vs マイクロサービス |
| 重要なトレードオフの判断 | パフォーマンス vs 可読性 |
ADRの運用
docs/
└── adr/
├── ADR-001-hexagonal-architecture.md
├── ADR-002-postgresql-selection.md
├── ADR-003-jwt-authentication.md
└── ADR-template.md// ADRとコードの関連付け
// src/adapters/out/PostgresOrderRepository.ts
/**
* 注文のPostgreSQLリポジトリ実装
* @see docs/adr/ADR-002-postgresql-selection.md
*/
class PostgresOrderRepository implements OrderRepository {
// ...
}まとめ
| ポイント | 内容 |
|---|---|
| ADRとは | 設計判断とその理由を記録する軽量ドキュメント |
| フォーマット | ステータス、コンテキスト、決定、理由、却下案、結果 |
| タイミング | 重要な技術的判断のたびに書く |
| 効果 | 「なぜこうなっているのか」を将来の自分やチームが理解できる |
チェックリスト
- ADRの目的と価値を理解した
- ADRの基本フォーマットを把握した
- ADRを書くべきタイミングを理解した
次のステップへ
Step 1の内容を理解度チェッククイズで確認しましょう。アーキテクチャの基礎概念がしっかり身についているか試してみてください。
推定読了時間: 15分