Architecture Decision Records

In one line

Why you chose something then matters more than what you chose. It is the only way to make it possible to revisit a decision when its premises change.

Why this was needed

Six months later someone asks, "Why did we use an endpoint here instead of the NAT?" Nobody remembers. So one of two things happens.

• Nobody touches it — because they do not know the reason and are afraid. The outdated decision stays as it is.
• They change it carelessly — because they do not know the reason and assume there is none. And the same problem comes back.

Both are bad. What is needed is "what did we know then, and what did we trade off?"

How it works

The structure of a one-page ADR

One file and one page are enough.

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

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

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

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

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

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

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

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

Two sections that matter especially

What was traded off (trade-off) — without it, it is just a press release. Every decision has something given up, and only by writing it down can you later say "we did not fail to know it; we chose it knowing."

When to revisit — a decision has conditions under which it is valid. If you write in advance the point at which those conditions break, outdated decisions linger forever less often.

What to record as an ADR

You do not need to record everything. The criterion is what is expensive to undo.

• Record: the VPC CIDR, region choice, managed vs. self-run, choice of data store, authentication method, whether to go multi-region
• Do not record: instance type adjustments, log retention period changes, alert thresholds

Where to keep it

Keep it inside the code repository (docs/adr/). If you put it in a wiki, it drifts apart from the code and in the end nobody looks at it. If it is in the repository, changes are reviewed as PRs, and versions are kept together with the code.

What you see in the field

• "I don't know why it was done this way, but it seems we shouldn't touch it" → there was no ADR.
• A decision from three years ago is kept as it is → nobody checked that the premises had changed.
• The same debate repeats every year → the conclusion was never written down.

How to write cost decisions in numbers

If you write only "cheaper" in an ADR, it cannot be verified six months later. Write three values and it becomes a verifiable document.

## 대안 비교 (월 기준, 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% 아래이거나, 타입 변경이 필요해지면 재검토

The key is writing the assumptions separately. The conclusion may turn out to be wrong later, but if the assumptions are written down, you can tell "what changed that made it wrong." An ADR with no assumptions becomes a document that nobody dares touch six months later.

When to revisit this decision

More and more teams write an expiry date in the ADR. They write "revisit in 2027-03" and put it on the calendar. Otherwise a decision from three years ago stays in place, even though the unit prices, services, and traffic have all changed in the meantime.

There are three things to check in the revisit.

1. Are the assumptions still correct? — utilization, traffic, unit prices.
2. Have the alternatives grown? — the cloud releases new instances and pricing plans every year.
3. How much did the actual cost differ from the estimate? — this gap builds the accuracy of the next estimate.

The third is the most valuable. As records comparing estimates with actuals accumulate, the team's estimation ability genuinely improves.

Wrapping up this course

In the cloud, an architecture decision is a cost decision, and a cost decision is a business decision. If you can speak in numbers, meetings get shorter, and if you write down the reasoning, the next person does not walk the same road again.