231. 아키텍처 결정 기록 (ADR, Architecture Decision Record) - 설계 의사결정 문서화 컨텍스트 트레이드오프 결과 히스토리 마이크로서비스 지식 전수

핵심 인사이트: (평가와 결정의 영원한 보존) 신입 개발자가 입사했다. 회사 서버 코드를 까보니 요즘 대세인 MySQL 대신 20년 전 낡은 오라클(Oracle) DB를 쓰고 있었다. 신입이 혀를 차며 "아니 어떤 멍청이가 2024년에 비싼 오라클을 쓴 거야? 당장 MySQL로 뜯어고쳐야지!" 하고 코드를 갈아엎으려 했다. 그때 고참이 창고에서 먼지 쌓인 노트(ADR)를 꺼내와 뒤통수를 후려쳤다. "야 임마! 5년 전에 우리가 오라클 안 쓰고 MySQL 썼다가 트랜잭션 동시성 문제 터져서 회사 망할 뻔했어! 그래서 그날 밤 12시에 팀장부터 막내까지 다 모여서 피 터지게 싸운 끝에 '동시성 100% 방어를 위해 10억을 내고라도 오라클을 쓰자'고 결정 내렸고, 그 '피눈물 나는 이유'를 이 노트(ADR)에 다 적어놨잖아!! 이 뼈대(아키텍처)를 왜 이렇게 미친 모양으로 짤 수밖에 없었는지, 그 '과거의 맥락과 이유'를 모르면 절대 뼈대를 함부로 건드리지 마라!!" 선배들의 피와 땀이 서린 설계의 오답 노트이자 역사책, ADR이다.

Ⅰ. 과거를 잊은 개발팀의 비극

  • 아키텍처 설계는 한 번에 뚝딱 나오는 게 아니라, 수많은 회의와 229번 ATAM 같은 트레이드오프 타협을 거쳐(예: 속도를 포기하고 보안을 챙기자!) 탄생합니다.
  • 문제점: 3년 뒤, 그 결정을 내렸던 핵심 아키텍트(선배)가 퇴사합니다. 남은 후배들은 "왜 이딴 뼈대 구조로 코드를 짰지?" 전혀 이해하지 못하고, 선배들이 버렸던 낡은 방식으로 다시 코드를 뜯어고치려다 과거의 에러를 똑같이 반복하는 **'역사의 수레바퀴(레거시의 저주)'**에 빠집니다.

Ⅱ. ADR (Architecture Decision Record)의 개념 🌟

  • 개념: 소프트웨어 시스템의 아키텍처를 설계하는 과정에서 만들어진 '중요한 기술적 의사결정(예: 언어를 Java에서 Go로 바꾼다, DB를 몽고DB로 바꾼다)'의 내용과, 그런 결정을 내릴 수밖에 없었던 '당시의 상황(Context)', 고민했던 '대안들', 그리고 그 결정이 가져올 '결과(Consequences)'를 간결한 문서로 기록하여 프로젝트 저장소(Git)에 영구히 남겨두는 지식 관리 기법입니다.

Ⅲ. ADR 문서의 4대 핵심 구성 요소 🌟

ADR은 논문이 아닙니다. 마크다운(.md) 파일로 개발자답게 1장짜리로 아주 짧고 명확하게 적습니다.

  1. 상황 및 배경 (Context):
    • 왜 우리가 이 결정을 고민하게 되었는가? (예: "블랙프라이데이 때 동접자 10만 명이 몰려서 기존 MySQL 구조로는 결제 서버가 3번이나 다운되었다.")
  2. 결정 사항 (Decision) 🌟:
    • 그래서 우리가 내린 최종 결론은 무엇인가? (예: "따라서 결제 시스템의 DB를 RDBMS에서 고성능 NoSQL인 Redis로 교체하기로 결정한다.")
  3. 대안 및 트레이드오프 (Alternatives & Trade-offs):
    • 왜 다른 대안들은 버렸는가? (예: "서버 대수를 늘리는 대안도 있었지만 서버비가 한 달에 1억이 추가되므로 버렸다. Redis를 쓰면 일관성이 약간 떨어지지만(트레이드오프), 속도를 위해 감수한다.")
  4. 결과 (Consequences):
    • 이 결정으로 인해 앞으로 우리 팀이 겪을 좋은 점과 나쁜 점은 무엇인가? (예: "좋은 점: 속도가 10배 빨라진다. 나쁜 점: 팀원 전체가 다음 주까지 Redis 문법을 새로 공부해야 한다.")

Ⅳ. 왜 MSA와 클라우드 시대에 ADR이 필수인가?

  • 마이크로서비스(MSA)는 10개의 팀이 100개의 독립된 서비스(캡슐)를 각자 다른 언어와 DB로 맘대로 쪼개어 만듭니다.
  • 옆 팀이 왜 저런 요상한 언어로 서버를 띄웠는지, 왜 저런 구조를 짰는지 소통이 1도 안 됩니다(사일로 현상).
  • 효과: 소스 코드 저장소(GitHub) 폴더에 docs/adr/001-use-redis.md 처럼 문서를 턱 하니 같이 넣어두면(코드와 문서의 일체화), 신입 개발자가 코드를 까보기 전에 ADR 파일부터 쫙 읽으면서 "아~ 우리 시스템 뼈대가 이런 피눈물 나는 역사를 거쳐 진화해 왔구나!" 하고 단 하루 만에 아키텍처의 철학(영혼)을 100% 흡수할 수 있게 됩니다.

📢 섹션 요약 비유: **ADR(아키텍처 결정 기록)**은 100년 된 한옥(소프트웨어)의 대들보 밑에 숨겨져 있는 **'조상님들의 건축 일기장(오답 노트)'**과 같습니다. 현대의 후손(신입 개발자)이 한옥을 수리하려고 지붕을 까봤더니, 멀쩡한 참나무 기둥 대신 휘어빠진 소나무 기둥이 기형적인 모양으로 박혀있습니다. 후손이 "미쳤네, 당장 참나무로 싹 갈아엎어!"라고 도끼를 드는 순간, 기둥 밑에서 낡은 일기장(ADR)이 툭 떨어집니다. 일기장에는 이렇게 적혀있습니다. "[상황] 1980년에 대홍수가 나서 지붕이 무너질 뻔했다. [대안] 튼튼한 참나무를 구하려 했지만 돈이 없었다. [결정] 그래서 비록 휘어지기 쉽지만 물을 먹으면 팽창해서 빈틈을 꽉 막아주는 소나무 기둥을 임시방편으로 크로스로 엮어서 버티기로 결정했다. [결과] 이 결정 덕분에 비는 안 새지만, 내년에 벌레가 꼬일 수 있으니 주의하라." 후손은 이 일기장(ADR)을 읽고 나서야, 왜 선배들이 이렇게 미친 기형적인 뼈대(아키텍처)를 짤 수밖에 없었는지 그 당시의 피 터지는 사연(트레이드오프)을 100% 이해하게 됩니다. 단순한 코드 쪼가리로는 절대 알 수 없는 설계자들의 철학과 '왜(Why)'를 영원히 박제하여, 후배들이 똑같은 멍청한 실수를 두 번 다시 반복하지 않게 지켜주는 팀의 위대한 유산입니다.