Architecture Decision Records

한 줄 요약

무엇을 골랐는지보다 왜 그때 그것을 골랐는지가 더 중요합니다. 전제가 바뀌었을 때 결정을 다시 볼 수 있게 하는 유일한 방법입니다.

왜 이게 필요했나

6개월 뒤 누군가 묻습니다. "이거 왜 NAT 안 쓰고 엔드포인트로 했어요?" 아무도 기억하지 못합니다. 그래서 두 가지 중 하나가 일어납니다.

• 아무도 안 건드립니다 — 이유를 모르니 무서워서. 낡은 결정이 그대로 남습니다.
• 아무렇게나 바꿉니다 — 이유를 모르니 없다고 생각해서. 그리고 같은 문제가 재발합니다.

둘 다 나쁩니다. 필요한 것은 "그때 무엇을 알고 있었고, 무엇을 맞바꿨는가" 입니다.

어떻게 동작하나

ADR 한 장의 구조

파일 하나, 한 페이지면 충분합니다.

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

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

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

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

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

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

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

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

특히 중요한 두 절

맞바꾼 것(trade-off) — 이게 없으면 그냥 홍보문입니다. 모든 결정에는 포기한 것이 있고, 그걸 적어야 나중에 "그건 몰랐던 게 아니라 알고 택한 것" 이라고 말할 수 있습니다.

언제 다시 볼 것인가 — 결정에는 유효 조건이 있습니다. 그 조건이 깨지는 시점을 미리 적어 두면, 낡은 결정이 영원히 남는 일이 줄어듭니다.

무엇을 ADR 로 남기나

전부 남길 필요는 없습니다. 기준은 되돌리기 비싼 것입니다.

• 남긴다: VPC CIDR, 리전 선택, 관리형 vs 직접, 데이터 저장소 선택, 인증 방식, 멀티 리전 여부
• 안 남긴다: 인스턴스 타입 조정, 로그 보존 기간 변경, 알림 임계값

어디에 두나

코드 저장소 안에 둡니다(docs/adr/). 위키에 두면 코드와 따로 놀고, 결국 아무도 안 봅니다. 저장소에 있으면 변경이 PR 로 리뷰되고, 코드와 함께 버전이 남습니다.

현장에서 만나는 모습

• "왜 이렇게 했는지 모르겠지만 건드리면 안 될 것 같아요" → ADR 이 없었다.
• 3년 전 결정을 그대로 유지 → 전제가 바뀐 걸 아무도 확인하지 않았다.
• 같은 논쟁을 매년 반복 → 결론을 안 적었다.

비용 결정을 숫자로 쓰는 법

ADR 에 "더 싸다" 라고만 적으면 6개월 뒤 검증할 수 없습니다. 세 값 을 적으면 검증 가능한 문서가 됩니다.

## 대안 비교 (월 기준, 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년 전 결정이 그대로 유지되는데, 그동안 단가·서비스·트래픽이 전부 바뀌어 있습니다.

재검토에서 확인할 것은 셋입니다.

1. 가정이 아직 맞는가 — 사용률·트래픽·단가.
2. 대안이 늘었는가 — 클라우드는 매년 새 인스턴스와 요금제를 낸다.
3. 실제 비용이 예상과 얼마나 달랐는가 — 이 차이가 다음 추정의 정확도를 만든다.

세 번째가 가장 값집니다. 예상과 실제를 비교한 기록이 쌓이면 팀의 추정 능력이 실제로 늘어납니다.

이 코스를 마치며

클라우드에서 아키텍처 결정은 곧 비용 결정이고, 비용 결정은 곧 사업 결정입니다. 숫자로 말할 수 있으면 회의가 짧아지고, 그 근거를 적어 두면 다음 사람이 같은 길을 다시 걷지 않습니다.