아키텍처 결정 레코드(ADR)

아키텍처 결정을 가장 효과적으로 문서화하는 방법은 아키텍처 결정 레코드(Architecture Decision Reccord, ADR)을 작성하는 것 입니다

기본 구조

ADR의 기본 구조는 제목(Title), 상태(Status), 콘텍스트(Context), 결정(Decision), 결과(Consequences) 이렇게 5개 섹션으로 구성됩니다

여기에 컴플라이언스(Compliance)와 노트(Notes)라는 추가 섹션을 덧붙일 수 있습니다

제목

• 아키텍처 결정을 짤막한 문구로 표현합니다. 일련번호를 붙여서 쓰기도 합니다.

상태

• 제안됨(Proposed), 수락됨(Accepted), 대체됨(Superseded) 과 같은 상태를 사용합니다
• 제안됨 : 해당 결정이 상위 레벨의 의사 결정권자의 승인이 필요한 상태입니다
• 수락됨 : 결정이 승인되어 구현할 준비가 된 상태입니다
• 대체됨 : 결정이 번복되어 다른 ADR에 의해 대체된 상태로, 이전 ADR 상태는 수락됨 상태여야 합니다.
  • 대체됨 상태는 어떤 결정이 내려졌고, 당시 왜 그런 결정을 했는지, 새로운 결정은 무엇이고 어쩌다 변경을 하게 됐는지 등에 관한 이력을 보관하는 강력한 수단입니다.

콘텍스트

• '어떤 사정 때문에 그렇게 결정할 수밖에 없었나?'를 표현하는 섹션입니다
• 이 섹션에서 특수한 상황이나 문제점을 이야기하고 다른 대안에 대해 상술합니다
• 각 대안을 상세히 분석한 문서가 필요할 경우, 콘텍스트 섹션 대신 ADR에 대한(Alternative) 섹션을 추가합니다

결정

• 아키텍처 결정과 그렇게 결정하게 된 사유를 전부 밝힙니다.
• 수동적 어조 대신, 매우 긍정적이고 당당한 어조로 아키텍처 결정을 설명합니다
  • e.g.
    • BAD: '서비스 간의 비동기 메시징이 최선의 선택이라고 생각합니다'
    • GOOD: '서비스 간에는 비동기 메시징을 사용할 것입니다'
• 결정 섹션의 큰 강점은 방법(how)보다 이유(why)에 무게를 실을 수 있다는 것입니다

결과

• 이 섹션에는 아키텍처 결정의 전체적인 영향도를 기술합니다
• 아키텍트가 어떤 결정을 하더라도 좋은 영향과 나쁜 영향은 공존하기 마련입니다(트레이드 오프)
• 아키텍처 결정이 어떤 영향을 미치는지 구체적으로 기술함으로써 아키텍트는 결정의 장점보다 그 영향이 더 중요한지 되돌아보게 됩니다

컴플라이언스(Optional)

• 아키텍트가 아키텍처 결정을 어떻게 측정/관리하는 게 좋을지 생각하게 만듭니다
• e.g. 테스트 코드는 언제 어떻게 실행되어야 하는지

노트(Optional)

• 다음과 같은 메타 데이터가 포함됩니다
  • 원저자
  • 승인일
  • 승인자
  • 대체일
  • 최종 수정일
  • 수정자
  • 최종 수정 내역

ADR 문서 예시

ADR 저장

• 이렇게 작성한 ADR은 어딘가 저장을 해야 합니다
• 깃 리포지터리는 액세스 권한이 없는 사용자도 있을 수 있기 때문에 위키로 저장하는 것이 좋습니다

결론

• 아키텍처 결정을 문서화하는 방법으로 ADR을 소개했습니다
• 하지만 아키텍처 결정 뿐만 아니라 어떠한 결정이라도 위와 같은 양식을 적용할 수 있을 것입니다
• 이러한 결정들을 문서화하면 이전 결정들에 대한 맥락을 알 수 있고 같은 실수를 반복하지 않을 수 있습니다.
• 또한 트레이드 오프로 기술부채로 남겨두었던 것들을 기록하는 좋은 방법입니다.

참고

• 책 소프트웨어 아키텍처 101
• https://adr.github.io/