アーキテクチャ決定記録(ADR)

TT Labで続きを見る

一言でいうと

何を選んだかよりも、なぜそのときそれを選んだかのほうが重要です。 前提が変わったときに、決定を見直せるようにする唯一の方法です。

なぜ必要なのか

6か月後、誰かが尋ねます。「これ、なぜNATを使わずにエンドポイントにしたんですか」。誰も覚えていません。そのため、次の2つのうち1つが起きます。

誰も手を付けません: 理由がわからないので怖いからです。古い決定がそのまま残ります。
好き勝手に変えます: 理由がわからないので、ないものと考えるからです。そして同じ問題が再発します。

どちらも悪い結果です。必要なのは、「そのとき何を知っていて、何と引き換えにしたのか」です。

どう動くのか

ADR1枚の構造

ファイル1つ、1ページで十分です。

# ADR-014: 프라이빗 서브넷의 S3 접근에 게이트웨이 엔드포인트 사용

- 상태: 채택
- 날짜: 2026-08-20
- 관련: ADR-009(VPC 설계)

## 맥락
로그 적재로 S3 트래픽이 월 8TB. 현재 전량이 NAT 를 경유해
NAT 데이터 처리 요금이 월 비용의 31% 를 차지한다.

## 선택지
1. 현행 유지 — 변경 없음, 비용 유지
2. 게이트웨이 엔드포인트 — 요금 없음, 라우팅 테이블 변경 필요
3. 로그를 리전 밖 수집기로 전송 — 리전 간 요금 발생

## 결정
2번. 게이트웨이 엔드포인트를 추가하고 프라이빗 라우팅 테이블에 경로를 넣는다.

## 근거
- 엔드포인트 자체 요금이 없어 절감액이 그대로 남는다(월 약 240만 원 추정)
- 인터넷을 경유하지 않아 보안상으로도 낫다
- 엔드포인트 정책으로 우리 계정 버킷만 허용해 반출 경로를 좁힌다

## 맞바꾼 것
- 라우팅 테이블이 하나 더 복잡해진다
- 엔드포인트 정책을 잘못 쓰면 접근이 막힌다 → 스테이징에서 먼저 검증

## 언제 다시 볼 것인가
- S3 외 서비스 트래픽이 커지면(인터페이스형 엔드포인트 검토)
- 멀티 리전으로 가면 전체 재검토

特に重要な2つのセクション

引き換えにしたもの(trade-off): これがなければ、ただの宣伝文です。すべての決定には諦めたものがあり、それを書いておいてはじめて、あとで「それは知らなかったのではなく、知ったうえで選んだことだ」と言えます。

いつ見直すか: 決定には有効条件があります。その条件が崩れる時点をあらかじめ書いておけば、古い決定が永遠に残ることが減ります。

何をADRとして残すか

すべてを残す必要はありません。基準は、元に戻すのが高くつくものです。

残す: VPC CIDR、リージョンの選択、マネージドか自前か、データストアの選択、認証方式、マルチリージョンにするかどうか
残さない: インスタンスタイプの調整、ログ保存期間の変更、アラートのしきい値

どこに置くか

コードリポジトリの中に置きます(docs/adr/)。ウィキに置くと、コードと別々に動いて、結局誰も見なくなります。リポジトリにあれば、変更がPRでレビューされ、コードと一緒にバージョンが残ります。

現場での姿

「なぜこうしたのかわからないけれど、触ってはいけない気がします」 → ADRがありませんでした。
3年前の決定をそのまま維持しています → 前提が変わったことを、誰も確認していませんでした。
同じ議論を毎年繰り返しています → 結論を書いていませんでした。

コストの決定を数字で書く方法

ADRに「より安い」とだけ書くと、6か月後に検証できません。3つの値を書くと、検証可能なドキュメントになります。

## 대안 비교 (월 기준, 2026-09 단가)

| 안 | 고정비 | 변동비 | 예상 총액 | 손익분기 |
|---|---|---|---|---|
| A. m6i.2xlarge 온디맨드 ×3 | $0 | $0.384/h ×3 | $840 | — |
| B. 1년 예약 ×3 | 선납 $2,900 | $0.242/h ×3 | $530 | 8개월 |
| C. Fargate (평균 40% 사용) | $0 | $0.049/vCPU·h | $610 | — |

## 가정
- 평균 vCPU 사용률 40%, 피크 85% (지난 90일 CloudWatch)
- 트래픽 연 20% 증가
- 인스턴스 타입을 1년 안에 바꾸지 않는다   ← 이 가정이 깨지면 B 는 손해

## 결정: B
## 되돌리는 조건: 사용률이 3개월 연속 25% 아래이거나, 타입 변경이 필요해지면 재검토

核心は、前提を別に書くことです。結論はあとで間違いになることがありますが、前提が書かれていれば、「何が変わったから間違いになったのか」がわかります。前提のないADRは、6か月後に誰も手を付けられないドキュメントになります。

この決定をいつ見直すか

ADRに有効期限を書くチームが増えています。「2027-03に再検討」と書いておいて、カレンダーに入れます。そうしないと、3年前の決定がそのまま維持されますが、その間に単価・サービス・トラフィックがすべて変わっています。

再検討で確認することは3つです。

前提がまだ合っているか: 使用率・トラフィック・単価です。
選択肢が増えたか: クラウドは毎年、新しいインスタンスと料金プランを出します。
実際のコストが予想とどれだけ違ったか: この差が、次の見積もりの精度を作ります。

3つ目が最も価値があります。予想と実際を比較した記録がたまると、チームの見積もり能力が実際に伸びます。

このコースを終えるにあたって

クラウドでは、アーキテクチャの決定はそのままコストの決定であり、コストの決定はそのままビジネスの決定です。数字で語れれば会議が短くなり、その根拠を書いておけば、次の人が同じ道をもう一度歩かずに済みます。