아키텍처 결정 기록(ADR)

한 줄 요약

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

왜 이게 필요했나

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년 전 결정을 그대로 유지 → 전제가 바뀐 걸 아무도 확인하지 않았다.
• 같은 논쟁을 매년 반복 → 결론을 안 적었다.

이 코스를 마치며

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