Perfluorodecalin

ADR(Architectural Decision Records) - 의사 결정 기록

14 min read

배경

의사 결정 기록이 왜 필요해졌나.
사실 이 방법론으로 기록을 남기는 것은 옵션. 선택이다.
하지만 내 경험상으로는 이런 기록 방법론이 필요해진 이유를 간단히 얘기하라면 다음과 같다.

기록으로써 근거를 남기기 위해.

지금까지는 기억력과 주석을 더듬어 어떻게든 응답과 해결이 됐던 것 같긴해도 아쉬움이 있었다.
내가 그 순간에 매번 최선의 선택을 한다는것을 의심할 여지가 없다고 스스로 자부하지만,
한 5년쯤 지난 프로젝트에서 왜 이걸 이렇게 했는지 질문 공격을 받으면 바로 응답하기도, 그 응답으로 상대를 설득하고 납득 시키기도 어렵다.

프로페셔널 하지 않아보인다.

기술 특성 상, 지금은 더 나은 해결방법이 있다 할 지라도 그 시대와 그 당시의 제약 조건 하에서는 그게 정말 최선으로 조치되어있는 걸 수도 있다. 아무리 위키에 써놨어도 이런 배경과 결정에 대한 것을 따로 정리해 두는 것은 의미있다고 생각한다.

이런 배경에서 의사 결정, 기술 결정에 대한 특화된 기록 방법론이 있는지를 찾다가 ADR을 접하게 되어 사용해 보려한다.

ADR(Architectural Decision Records)

ADR GitHub 공식 페이지를 보면 이 방법론에 대해 언급해온 자료 근거와(나름 Azure Well-Architected Framework에도 소개되고, 애자일 관련 서적, 설계 패턴 서적 등등에서 소개된 듯 하다.) 배경 정보, 템플릿 에 대한 소개가 잘 정리되어있다.
한국어 페이지는 없는데 나중에 folk 떠서 보기 쉽게 추가해 볼까 싶다.

ADR을 작성하는 템플릿이 다양한 듯 하며(ADR이 기록에 대한 것이라 템플릿이 있는 듯 하다), 일단 나는 사용이 목적이니 전체 번역 말고 쓸만한 부분만 정리해보겠다.

AD Management/Modeling Steps

이 프로세스는 문제 해결을 위한 대략적인 의사 결정 흐름을 표현한다.
이 중 의사 결정 및 기록, 실행 단계에서 ADR이 작성되는 것이다.

  1. 디자인 문제와 이를 해결할 수 있는 방법 파악
  2. 기준 수집 및 옵션 분석
  3. 의사 결정(AD)
  4. 의사 결정 기록(ADR)
  5. 의사 결정 실행

ADR 의 특성

ADR은 의사 결정을 기록하는 것이 목적이기 때문에 아래의 특성들을 지켜 작성되어야 한다.

  • 요약
  • 판단, 장단점, 모든 옵션의 비교와 객관적 평가
  • 의사결정 책임(결정권자, 실행자 명시)
  • 실행성(결정된 것은 반드시 실행되어야 합니다)

ADR 안티 패턴

ADR은 기록이고 미래에 사용될 근거이기 때문에 논리적으로 문제없고 객관적이고 공평한 결정 과정을 기록하면 된다.
내 입장에서는 그냥 당연한 이야기이긴 한데, 방법론을 설명하는 입장에서는 ADR이 확증 편향적이고 과장된 거짓 의도를 포함하지 않고 사실 기반이어야 하는 것이 중요하다고 강조, 또 강조를 하는 것 같다.
뻔한 말 같기는 한데, 사실 이 정도로 강조를 하는 것은 ADR을 다른 의도로 사용하려는 사람들이 있어왔기 때문이겠지..?(모든 규칙은 피로 쓰이니까)

내용 및 논리 부족형

  • Fairy Tale (동화식 사고 / 소원성취형) : 장점만 언급하고 단점은 무시함.
    ex) “로드 밸런서를 쓰면 부하가 분산되므로 좋다.”

    • 개선 방법: 장단점을 균형 있게 서술해야 함.

  • Sales Pitch (광고 문구식) : 과장된 표현, 미사여구 사용. 근거 없는 찬양.

    • ex) “이 기술은 매우 뛰어나며 모두가 행복해한다.”
    • 개선 방법: 형용사/부사를 줄이고, 근거 없는 표현은 배제.

  • Free Lunch Coupon (공짜 점심 / 캔디바) : 불리한 영향, 장기적 비용은 언급하지 않음.

    • ex) “이벤트 기반 아키텍처는 decoupling이 된다.”
    • 개선 방법: 숨겨진 비용, 유지보수 부담 등도 반드시 명시.

  • Dummy Alternative (가짜 대안) : 말도 안 되는 대안을 제시하고 주 선택지를 정당화함.

    • ex) “직접 DBMS 만들기는 너무 힘드니 PostgreSQL 선택.”
    • 개선 방법: 현실성 있는 대안을 최소 2개 이상 비교할 것.

시간과 범위 부족형

  • Sprint (단기 집착 / 조급증) : 단기 영향만 고려하고 하나의 대안만 채택함.

    • 개선 방법: 중장기 영향과 다양한 대안 탐색 필요.

  • Tunnel Vision (좁은 시야 / 터널 시야) : 특정 모듈이나 역할에만 집중, 전체 맥락은 무시.

    • 개선 방법: 운영자, 유지보수자 등 다양한 관점 반영.

  • Maze (주제 일탈) : ADR의 주제와 무관한 상세 내용으로 흐름이 흐려짐.

    • 개선 방법: 비핵심 내용은 별도 문서 또는 부록으로 분리.

문서 구성 문제형

  • Blueprint or Policy in Disguise (설계서/정책 위장형) : 결정 기록이 아닌 메뉴얼/법령처럼 작성됨.

    • 개선 방법: 저널 형식으로 서술하고 명령형 어투 피할 것.

  • Mega-ADR (거대 ADR) : 코드, 다이어그램 등 상세 정보가 과도하게 포함됨.

    • 개선 방법: 상세 설계는 별도 문서로 분리.

  • Novel or Epic (소설/서사시형) : ADR 하나에 전체 설계를 다 넣고 문체도 감성적임.

    • 개선 방법: 간결하고 사실 기반의 작성 유지.

기타 마법 부리기형

  • Magic Tricks (마법 부리기) : 가짜 문제 제시, 결론 정해놓고 끼워맞추기, 허위 수치화.
    • ex)
      • 존재하지 않는 문제로 긴급성 조작
      • 문제와 무관한 솔루션을 미는 경우
      • 근거 없는 숫자 비교: 4×독립성 + 3×정책 / 2
    • 개선 방법: 문제-해결의 실제 연결성 명확히. 수치화는 신뢰 가능한 경우만.

ADR 템플릿

Markdown Architectural Decision Records (MADR)

마크다운을 통해 ADR을 작성하는 방법이다.
MADR 작성을 위한 툴들이 휴고, Log4brains 등 여러가지 있다.
아무래도 마크다운 기반이다 보니까 프로젝트에 doc으로 아얘 ADR을 md파일로 템플릿을 제공, 작성 및 저장할 수 있는 하는 방식으로 동작하는 툴 들인 것 같다.

VS Code에서 ADR 작성 확장 프로그램 ADR Manager을 설치해서 사용할 수도 있다고 한다.
아래와 같이 각 ADR 구성 요소에 대해 입력 폼을 지원해주는 듯 하다.

Nygard ADR

ADR을 제목, 상태, 컨텍스트, 결정 및 결과로 구성한다.
MADR과 크게 달라보이지는 않는데, 템플릿 항목이 간략화 되어있어 별개의 템플릿으로 인정받는 모양이다.

  • Status(상태): 현재 이 결정의 상태를 작성한다.
    ex) proposed(제안됨), accepted(승인됨), rejected(거절됨), deprecated(사용 중단), superseded(대체됨) 등.
  • Context(배경): 이 결정을 내리게 된 배경이나 문제 상황을 설명한다. 현재 발생하고 있는 문제, 기술적 제약, 외부 요인 등 무엇이 이 변경을 유도했는지를 기술한다.
  • Decision(결정): 실제로 내린 결정 또는 실행할 변경 사항을 구체적으로 기술한다. 선택한 기술/패턴/방식과 그 이유를 명확히 서술한다.
  • Consequences(결과): 이 결정으로 인해 무엇이 쉬워지고 무엇이 어려워지는지를 설명한다. 장점뿐 아니라 단점, 리스크, 장기적인 영향 등도 포함하여 기록한다.

Y-Statement

왜 이름이 Y-Statement가 했더니, Y가 Why랑 발음이 비슷하면서도, 아래의 6가지 요소를 가지고 Y라는 이미지로 표현가능해서 붙여진 이름인 듯 하다.

  • Context(배경): 기능적 요구사항 또는 아키텍처 구성요소를 설명한다.
  • Facing(직면한 조건): 비기능적 요구사항, 예를 들어 원하는 품질 속성 등을 기술한다.
  • We Decided(결정): 최종적으로 선택한 설계 결정 또는 방향을 서술한다.
  • And Neglected(배제된 대안): 고려했으나 채택하지 않은 대안들을 명시한다.
  • To Achieve(달성하고자 하는 효과): 이 결정을 통해 충족하고자 하는 요구사항 또는 기대 효과를 설명한다.
  • Accepting That(감수해야 할 결과): 이 결정으로 인해 발생할 수 있는 단점, 다른 품질 특성이나 맥락에 미치는 영향, 단기 및 장기적 비용 등을 기술한다.

이 방식 자체도 정리하는 항목(템플릿)이 다를뿐 텍스트 기반으로 위키나 마크다운으로 작성되는 듯 하다.

그 외의 다양한 템플릿

아래 Repo에 들어가보면 다양한 템플릿들에 대한 정보가 있다.

마치며

사실 난 조금더 직관적이고 시각적인 기록법을 원했는데, 아무래도 객관적이고 논리적인 자료가 가득한 근거 자료를 준비하려면 문서의 형태를 띄어야 하는가보다..
지금까지도 이런 결정과 히스토리에 대한 것들은 위키에 적어왔는데, 이전과 다른점은 아얘 위키에 의사결정만을 위한 ADR 항목을 만들어서 중요한 의사결정에 대한 근거를 미리미리 준비해 놔야겠다 싶었다.

전반적으로 논리적이고 객관적이고 설득력 있는 비교이기만 하면 유의미하게 대비가 가능할 것 같아서 굳이 엄청 복잡한 템플릿을 사용할 필요는 없는 것 같다.
의사 결정의 중요도에 따라 템플릿 복잡도를 그때그때 선택해 가며 작성해 보고자 다짐하며 마무리한다.

그래프 뷰