오늘은 복잡하게 얽힌 마이크로서비스(MSA), 쿠버네티스, 그리고 클라우드 네이티브 환경에서 우리가 내리는 수많은 기술적 선택들을 어떻게 효과적으로 기록하고 공유할 수 있을지에 대한 이야기를 나눠보고자 합니다. 특히 기술 리더, 아키텍트, 그리고 모든 의사결정자들이 주목해야 할 강력한 도구, Architecture Decision Records(ADR)에 대해 깊이 있게 탐색해 보겠습니다.

ADR (Architecture Decision Record) 란 소프트웨어 시스템에서 내린 중요한 아키텍처 결정과 그 결정에 대한 이유와 결과를 기록해 두는 문서를 말합니다. 예를 들어 어떤 데이터베이스 기술을 선택했는지, 특정 프레임워크를 도입했는지 등의 결정 사항과 그 배경을 ADR로 남겨두면, 추후에 팀원들이 해당 결정의 맥락과 “왜 그런 선택을 했는지”를 쉽게 이해할 수 있습니다. 하나의 ADR 문서에는 단일한 아키텍처 결정 한 가지와 그와 관련된 상황(Context), 고려했던 옵션 및 최종 선택된 해법(Decision), 그리고 그 결정으로 인해 예상되는 영향(Consequences) 등이 구조화되어 담깁니다. 이러한 문서는 보통 마크다운(Markdown)과 같은 경량 포맷으로 작성하여 관련 코드 저장소에 함께 버전 관리하며, 필요하면 프로젝트 전반의 중앙 문서 저장소에도 함께 보관합니다. 실제로 Google Cloud의 예시를 보면, 만약 “왜 우리 서비스는 지역별 Kubernetes 클러스터를 사용하도록 설계되었는가?”와 같은 궁금증이 생길 경우 관련 ADR을 찾아 그 결정의 배경과 이유를 확인할 수 있습니다. 이처럼 ADR은 당시의 기술적 선택과 그 근거를 짧은 기록으로 남겨 둠으로써, 현재뿐 아니라 미래의 팀원들도 아키텍처 결정의 맥락을 투명하게 파악할 수 있게 해주는 중요한 도구입니다.

아키텍처 의사결정 기록(ADR)은 ‘아키텍처 기억상실증(Architecture Amnesia)’이라는 고질적인 문제를 해결하기 위해 탄생했다고 말씀드렸습니다. 그렇다면 이 기억상실증이란 정확히 무엇이며, 왜 이토록 위험한 것일까요? 이번에는 이 개념을 더 깊이 파고들어, 실제 프로젝트에서 어떤 모습으로 나타나는지 구체적인 사례를 통해 살펴보겠습니다.

• 아키텍처 기억상실증 (Architecture Amnesia) 이란,

시스템의 중요한 아키텍처가 어떤 ‘이유(Why)‘와 ‘배경(Context)‘ 속에서 결정되었는지에 대한 기억이 시간이 흐르면서 조직 내에서 사라지는 현상을 의미합니다. 이는 단순히 ‘무엇(What)’을 선택했는지를 잊는 것과는 차원이 다릅니다. 선택의 결과물인 아키텍처는 코드 속에 남아있지만, 그 선택을 이끌었던 수많은 고민, 대안 검토, 그리고 결정적인 트레이드오프에 대한 정보, 즉 ‘결정의 영혼‘이 소실되는 것입니다.

이 기억상실증은 마치 역사적 사건의 결과만 알고 그 원인과 과정을 모르는 것과 같습니다. 왜 그 전쟁이 일어났는지, 어떤 외교적 노력이 실패했는지 모른 채 결과만 본다면, 우리는 같은 실수를 반복할 수밖에 없습니다. 아키텍처도 마찬가지입니다. 기억상실증에 걸린 조직은 다음과 같은 심각한 문제에 직면하게 됩니다.

• 소모적인 논쟁의 굴레

이미 과거에 치열한 논쟁 끝에 결론 내린 사안을 새로운 팀원이나 리더가 다시 원점에서 제기합니다. 당시의 제약 조건이나 장기적인 비전을 알지 못하기에, “왜 이렇게 비효율적인 방식을 사용하죠?”라는 순수한 질문이 팀 전체의 에너지를 소모시키는 기나긴 논쟁으로 번집니다.

• 지뢰밭 위를 걷는 듯한 변경 작업

현재 아키텍처에 숨겨진 중요한 제약 조건을 알지 못한 채 변경을 시도하는 것은 마치 지뢰밭을 걷는 것과 같습니다. “이 코드는 비효율적이니 개선해야지”라고 생각하며 수정한 부분이, 사실은 특정 시스템의 피크 타임 성능을 보장하기 위한 의도적인 ‘희생’이었을 수 있습니다. 이처럼 배경을 모르는 최적화는 시스템 전체를 마비시키는 재앙으로 이어질 수 있습니다.

• 지식의 블랙홀, 영웅의 퇴사

결정의 모든 배경지식이 특정 시니어 아키텍트의 머릿속에만 존재한다면, 그 사람은 조직의 ‘영웅’이자 동시에 ‘시한폭탄’입니다. 그가 퇴사하거나 다른 프로젝트로 이동하는 순간, 조직의 중요한 지적 자산은 블랙홀처럼 함께 사라져 버립니다. 남은 팀원들은 거대한 지식의 공백 앞에서 속수무책이 됩니다.

이러한 아키텍처 기억상실증이 실제로 어떻게 프로젝트를 위협하는지, 세 가지 구체적인 사례를 통해 더욱 생생하게 알아보겠습니다.

빠르게 성장하는 이커머스 플랫폼이 있었습니다. 프로젝트 초기, 아키텍트 팀은 마이크로서비스 간 비동기 통신을 위해 메시지 큐를 도입하기로 했습니다. 후보로는 RabbitMQ와 Kafka가 올랐고, 치열한 논의 끝에 Kafka가 최종 선택되었습니다. 당시의 결정 이유는 단순히 ‘메시지를 전달하는 것’을 넘어, 모든 주문과 사용자 행동을 ‘이벤트 스트림’으로 간주하여 실시간 사기 탐지, 개인화 추천, 데이터 분석 플랫폼의 기반으로 삼으려는 장기적인 데이터 전략 때문이었습니다. Kafka의 강력한 내구성과 순서 보장, 그리고 대용량 스트림 처리 능력은 이 비전에 완벽하게 부합했습니다.

• 2년 후, 기억상실증이 시작됩니다.

초기 멤버 대부분이 회사를 떠나고 새로운 개발팀이 프로젝트를 이어받았습니다. 그들은 현재 시스템이 Kafka를 단순히 주문 완료 알림을 보내는 용도로만 사용하고 있다는 사실을 발견했습니다. Kafka의 복잡한 운영 포인트(주키퍼 관리, 파티션 리밸런싱 등)는 그들에게 큰 부담이었습니다. 팀 내부에서는 이런 목소리가 나오기 시작했습니다. “단순 알림용인데 왜 이렇게 복잡한 Kafka를 쓰지? 훨씬 가볍고 운영이 쉬운 RabbitMQ로 바꾸면 우리 삶이 편해질 텐데.”

• 결과

장기적인 데이터 전략이라는 핵심 ‘이유’는 누구의 기억에도 남아있지 않았습니다. 팀은 Kafka를 RabbitMQ로 교체하는 마이그레이션 프로젝트를 공식적으로 제안하고, 이를 위한 기술 검토와 회의에 몇 주간의 시간을 쏟아부었습니다. 과거에 이미 끝난 논쟁이 재점화되면서 귀중한 개발 리소스가 낭비되었습니다. 만약 이 결정이 그대로 진행되었다면, 회사의 미래 데이터 플랫폼 구축 계획은 기반을 잃고 원점으로 돌아가는 끔찍한 결과를 맞이했을 것입니다.

어느 핀테크 서비스는 사용자 인증 기능을 구현해야 했습니다. 기술적으로는 Auth0나 Okta 같은 검증된 상용 솔루션(SaaS)을 사용하거나, Keycloak 같은 오픈소스를 설치형으로 사용하는 것이 가장 합리적인 선택이었습니다. 하지만 당시 이 서비스가 진출하려는 국가에는 “모든 금융 소비자의 개인식별정보(PII)는 반드시 국내 데이터센터에, 특정 암호화 규격을 준수하여 저장해야 한다”는 강력한 데이터 주권 법규가 있었습니다. 당시 사용 가능한 글로벌 인증 솔루션들은 이 요구사항을 완벽히 만족시키지 못했습니다. 결국 팀은 울며 겨자 먹기로 JWT 기반의 인증 서버를 직접 구현하는 고통스러운 결정을 내렸습니다. 이는 기술적 선택이 아닌, 규제 준수를 위한 비즈니스적 필수 선택이었습니다.

• 1년 후, 기억상실증이 덮칩니다.

새로운 C-Level 기술 임원이 합류했습니다. 그는 보안 분야 전문가였고, “절대 직접 인증 시스템을 만들지 말라(Never roll your own crypto/auth)”는 업계의 금언을 신봉했습니다. 그는 유지보수 비용과 보안 위험이 큰 자체 인증 서버를 발견하고 경악했습니다. “이 중요한 걸 왜 직접 만들었습니까? 당장 검증된 상용 솔루션으로 교체합시다!”

• 결과

아무도 그 결정의 배경에 있던 ‘규제 준수’라는 결정적 제약 조건을 명확히 설명하지 못했습니다. 기술 임원은 자신의 신념에 따라 인증 서버 교체 프로젝트를 강력하게 추진했습니다. 만약 ADR 같은 기록이 없었다면, 팀은 규제 위반이라는 거대한 지뢰를 향해 걸어갔을 것입니다. 프로젝트가 한참 진행된 후에야 법무팀의 검토 과정에서 이 사실이 발견되어 프로젝트가 중단되고 막대한 매몰 비용이 발생했을 수 있으며, 최악의 경우 서비스 출시 후 막대한 벌금과 함께 사업 철수라는 위기에 직면했을 것입니다.

한 레거시 모놀리식 시스템을 마이크로서비스(MSA)로 전환하는 대규모 프로젝트가 진행 중이었습니다. 아키텍트들은 ‘스트랭글러 패턴(Strangler Fig Pattern)’을 적용하여, 기능별로 서비스를 점진적으로 분리해나가기로 했습니다. 하지만 데이터베이스를 한 번에 분리하는 것은 너무 위험하고 시간이 많이 걸리는 작업이라 판단했습니다. 그래서 1단계 전략으로, 애플리케이션 로직은 서비스별로 분리하되, 데이터베이스는 기존의 모놀리식 DB를 공유하는 구조를 택했습니다. 이는 MSA의 원칙에는 어긋나지만, 위험을 최소화하고 비즈니스 가치를 빠르게 전달하기 위한 의도적이고 실용적인 절충안이었습니다. 데이터베이스 분리는 2단계 과제로 명확히 계획되어 있었습니다.

• 6개월 후, 기억상실증이 문제를 일으킵니다.

MSA와 클라우드 네이티브 기술에 대한 열정으로 가득 찬 신입 개발자가 팀에 합류했습니다. 그는 서비스들이 하나의 데이터베이스를 공유하는 것을 보고 큰 충격을 받았습니다. “이건 MSA가 아니라 그냥 분산된 모놀리스(Distributed Monolith)입니다! 서비스 간에 강한 결합이 생기고 데이터베이스가 단일 장애점(SPOF)이 되잖아요! 당장 데이터베이스부터 쪼개야 합니다!”

• 결과

신입 개발자의 지적은 이론적으로는 완벽히 옳았지만, 프로젝트의 역사와 전략적 맥락을 전혀 고려하지 않은 것이었습니다. ‘점진적 전환’이라는 핵심 ‘이유’를 잃어버린 채, 그의 주장은 팀 내에 “우리가 잘못된 길을 가고 있나?”라는 불안감을 심어주었습니다. 이로 인해 현재 집중해야 할 1단계 목표에서 벗어나, 데이터베이스 분리라는 2단계 과제를 놓고 불필요한 논쟁과 혼란이 발생했습니다. 이는 잘 계획된 로드맵을 뒤흔들고 팀의 생산성을 저해하는 결과를 낳았습니다.

이 세 가지 사례는 아키텍처 기억상실증이 단순한 불편함을 넘어, 프로젝트의 시간, 비용, 안정성, 그리고 미래의 가능성까지 모두 파괴할 수 있는 심각한 질병임을 명확히 보여줍니다. ADR은 바로 이 질병에 대한 가장 효과적인 백신이자 치료제입니다.

애자일 방법론의 등장 이후 소프트웨어 개발 현장에서는 과거처럼 방대한 설계 문서를 미리 작성하지 않고 개발 중에 수시로 의사결정이 이루어지는 경우가 많아졌습니다. 그러다 보니 “무엇을 왜 그렇게 구현했는지”에 대한 맥락이 별도로 문서화되지 않고 결정자의 머릿속에만 남는 문제가 생겼습니다. 그 결과 시간이 흐르면 새로운 팀원들이 이전에 작성된 코드나 아키텍처를 보며 “왜 이걸 이런 방식으로 만들었지?” 하고 의아해하지만, 필요한 배경 지식이 공유되어 있지 않아 이해하고 기여하는 데 어려움을 겪게 됩니다. 이러한 문제를 해결하기 위해 2011년 소프트웨어 아키텍트인 마이클 나이가드(Michael Nygard)가 제안한 개념이 Architecture Decision Record, 즉 ADR입니다. 나이가드는 당시 애자일 프로젝트에서는 아키텍처를 전통적인 방식과 다르게 작고 연속적인 결정들의 모음으로 기록해야 함을 역설하였고, 결정의 이유(motivation)와 결과(consequences)를 남겨 프로젝트 내 지식으로 활용하자는 아이디어를 제시했습니다. 특히 규모가 크거나 분산된 프로젝트, 전담 아키텍트가 없는 팀, 새로운 인원의 잦은 합류가 있는 환경에서 이러한 기록의 필요성이 매우 크다고 보았으며, ADR이라는 경량 문서 포맷이 그런 상황에 꼭 맞는 해법이라고 판단한 것입니다.

ADR 개념은 발표 후 소프트웨어 업계에서 빠르게 주목받으며 널리 퍼지기 시작했습니다. 나이가드의 블로그 글로부터 약 7년 뒤인 2018년에는 글로벌 IT 컨설팅 기업 ThoughtWorks가 ADR을 자사의 기술 도입 권고 목록인 Technology Radar에서 ‘Adopt’ 항목으로 선정하여, 현대 소프트웨어 개발에서 ADR 사용을 적극 권장하기도 했습니다. 현재 많은 기업과 프로젝트에서 ADR을 활용하고 있으며, 영국 정부 산하 디지털서비스(GDS)에서도 ADR 포맷을 권장 사례로 공식 문서에 포함할 정도로 사실상의 표준 기법으로 자리잡았습니다. 다시 말해 ADR은 “아키텍처 결정은 기록되어야 한다”는 오래된 소프트웨어 공학 원칙을, 민첩한 현대 개발문화에 맞게 구현한 실용적인 방식이라 할 수 있습니다.

하나는, 전통적인 방식으로 작성된 방대한 설계 문서들이 현실을 따라가지 못하고 금세 쓸모를 잃는다는 점입니다. 수백 페이지짜리 아키텍처 명세서를 만들어 두어도 시간이 지나면 업데이트가 되지 않아 아무도 읽지 않게 되고, 실제 코드와 동떨어진 죽은 문서가 되어버리기 일쑤였습니다.

다른 하나는, 문서를 생략하고 구두로만 중요한 결정들이 이루어질 때 발생하는 지식 손실 문제입니다. 시간이 흐르고 사람이나 팀이 바뀌면, 과거에 왜 그런 결정을 내렸는지 알 길이 없어집니다. 이 경우 뒤늦게 그 결정을 접한 사람은 보통 두 가지 극단적인 대응을 보이기 쉬운데, 하나는 이유도 모른 채 그 결정을 그대로 따라가는 것이고 다른 하나는 맥락도 파악하지 못한 채 함부로 뒤엎는 것입니다.

전자는 상황이 변해 더 나은 대안이 필요해졌을 때 변경을 주저하게 만들어 시스템 개선을 가로막고, 후자는 해당 결정이 담고 있었던 숨은 의도를 무시한 채 변경을 시도함으로써 예기치 않은 부작용을 불러올 수 있습니다. 프로젝트가 진행됨에 따라 이러한 일이 누적되면 개발팀은 점차 기존 구조를 건드리는 것을 두려워하게 되고, 결국 시스템이 자신의 무게에 짓눌려 붕괴되는 사태까지 초래될 수 있습니다. ADR은 바로 이 두 가지 문제를 효과적으로 해소하기 위한 장치입니다. 중요한 건 아키텍처적인 결정이라면 무엇이든 빠짐없이 ADR로 남겨두기 때문에, 시간이 지나도 “당시 무슨 생각으로 이런 결정을 했을까”를 누구나 추적할 수 있고, 필요할 때 그 결정을 언제 변경해야 할지도 쉽게 판단할 수 있게 됩니다.

프로젝트 기간 동안 축적된 모든 ADR은 그 자체로 아키텍처 이력 저장소가 됩니다. 새로운 팀원이 합류하더라도 ADR 문서를 통해 선배 개발자들이 무슨 고민 끝에 어떤 선택을 했는지를 빠르게 이해할 수 있기 때문에, 온보딩에 드는 시간과 시행착오를 크게 줄일 수 있습니다. 마찬가지로 시간이 흐르면서 요구 사항이나 환경이 변하더라도, ADR에 남은 맥락 정보를 바탕으로 기존 결정이 여전히 유효한지, 아니면 재고해야 할 시점인지를 명확히 판단할 수 있습니다. 실제 사례에서도 ADR을 도입한 프로젝트 팀들은 “ADR을 읽고 나니 과거 결정들의 배경을 모두 알 수 있어서 좋았다”는 피드백을 많이 남기며, 두려움 없이 오래된 아키텍처를 개선하는 데에 자신감을 갖게 되었다고 합니다.

예를 들어 시스템에 장애가 발생하거나 성능 병목이 있을 때, 관련 ADR을 찾아보면 해당 구성 요소나 기술 선택의 원인을 파악할 수 있어 문제 해결의 실마리를 더 빨리 얻을 수 있습니다. 이는 곧 서비스의 신뢰성과 안정성 향상으로 이어집니다. 이렇게 축적된 ADR들은 새로운 기능을 설계하거나 시스템을 확장할 때도 유용한 참고자료가 됩니다. 과거에 유사한 결정을 내릴 때 어떤 옵션들을 검토했고 무엇을 이유로 채택 또는 기각했는지를 알 수 있으므로, 미래의 의사결정이 보다 현명하고 일관되게 이루어질 수 있습니다. 또한 ADR에는 결정 당시에 검토된 대안들과 그 장단점까지 기록되는 만큼, 여러 팀이 이 문서를 공유함으로써 서로 모범 사례를 전파하고 아키텍처에 대한 공통된 이해와 원칙을 갖도록 해줍니다. 다시 말해 ADR은 개별 팀의 지식에 머물렀을 정보를 조직 전체의 지식 자산으로 승격시켜, 부서나 서비스 경계를 넘어선 기술적 일관성을 확보하는 데 기여합니다.

아키텍처 결정 기록과 유사한 개념으로는 기술 설계서, 회의록, RFC(Request for Comments) 문서, 혹은 단순한 변경 이력 로그 등을 떠올릴 수 있습니다. 그러나 ADR은 기존의 이러한 문서들과 목적과 활용 면에서 분명한 차이가 있습니다.

• 유사점: 시스템의 아키텍처를 기술한다는 공통점이 있습니다.
• 차이점 및 ADR의 장점: SAD는 보통 프로젝트 초기에 ‘Big Design Up Front’ 방식으로 작성되는 거대하고 포괄적인 문서입니다. 이 문서는 한 번 만들어지면 변화하는 요구사항을 따라가지 못하고 금방 낡은 유물(outdated artifact)이 되기 쉽습니다. 반면, ADR은 작고, 집중적이며, 점진적입니다. 중요한 결정이 있을 때마다 하나씩 추가되므로 항상 최신 상태를 유지하기 용이하며, 애자일 개발 프로세스와 완벽하게 조화를 이룹니다.

• 유사점: 팀원들이 협업하여 기술적 내용을 기록하고 공유하는 데 사용됩니다.
• 차이점 및 ADR의 장점: 위키는 자유로운 형식 때문에 내용이 중구난방이 되거나 구조화되지 않은 정보의 ‘무덤’이 되기 쉽습니다. 또한, 누가 언제 어떤 내용을 수정했는지 추적하기 어렵고, 코드의 특정 시점과 문서의 버전을 일치시키기 어렵습니다. ADR의 가장 큰 장점 중 하나는 소스 코드와 함께 버전 관리된다는 것입니다. Git으로 코드를 관리하듯 ADR도 관리되므로, 특정 커밋 시점의 코드와 그 시점에 유효했던 아키텍처 결정을 함께 확인할 수 있는 강력한 컨텍스트를 제공합니다. git blame으로 코드 변경 이력을 추적하듯, 아키텍처 결정의 이력을 추적할 수 있는 것입니다.

• 유사점: 코드 변경의 ‘이유’를 기록하려는 시도입니다.
• 차이점 및 ADR의 장점: 커밋 메시지는 너무 세분화되어 있습니다. 이는 코드 라인의 변경(the ‘what’ and ‘how’ of code)을 설명하는 데는 유용하지만, 시스템 전반에 영향을 미치는 거시적인 아키텍처 결정(the ‘why’ of architecture)을 담기에는 부적합합니다. “API 게이트웨이로 Kong 대신 Spring Cloud Gateway를 선택한 이유”와 같은 복잡한 트레이드오프 분석을 커밋 메시지에 담을 수는 없습니다. ADR은 이러한 고수준의 전략적 결정을 기록하기 위해 특별히 고안된 도구입니다.

결론적으로, ADR의 독자적인 강점은 ①경량성(Lightweight), ②구조화된 형식(Structured format), ③버전 관리 연동(Version-controlled with code), 그리고 ④’이유’에 대한 집중(Focus on the ‘why’) 이라는 네 가지 특징의 조합에 있습니다.

ADR은 필요한 정보만 담은 짤막한 기록을 목표로 하며, 많은 페이지를 할애해 시스템 전체를 설명하기보다는 결정에 직접 영향하는 요소들만 핵심적으로 캡쳐합니다. 이런 특성 덕분에 ADR은 시간이 지나도 유지보수가 비교적 쉽고, 내용이 오래되어 가치가 떨어질 가능성을 최소화합니다.

• 아키텍처 의사결정 기록 (Architecture Decision Record, ADR) 작성하기

ADR은 아키텍처 의사결정의 투명성과 책임성을 한층 높여줍니다. 모든 주요 결정들이 근거와 함께 남아 있으므로 나중에라도 “왜 그때 이런 선택을 했는지”를 분명하게 설명할 수 있고, 의사결정 과정에 대한 신뢰를 구축할 수 있습니다. 이러한 특성은 특히 대규모 엔터프라이즈 시스템이나 공공 부문의 프로젝트에서 요구되는 거버넌스 기준을 충족하는 데 큰 도움이 됩니다. 실제로 ADR을 도입하면 프로젝트 이해관계자나 감사 기관에 의사결정의 정당성을 입증하기가 한결 쉬워지며, 정책적 판단에 대한 기록을 남김으로써 조직 차원의 지식 자산이 축적되는 효과까지 얻을 수 있습니다.

• • Documenting Architecture Decisions – Michael Nygard
  • Why you should be using architecture decision records – Red Hat Blog
  • How GPT-4 helps me make better Data Science decisions – Theodo Tech Blog
  • Can LLMs Generate Architectural Design Decisions? – arXiv