Skip to content
cover-develop

개발자가 의사결정을 기록하는 방법 (feat. ADR)

  • Develop

📅 December 04, 2021

⏱️2 min read

개발자들에게는 항상 다양한 선택지 중에 하나를 골라야 하는 상황이 주어집니다.
가장 간단한 예시로는 어떤 언어/프레임워크를 사용할지, 어느 버전을 사용할지에 대한 결정입니다.
오늘은 위와 같은 의사결정을 기록하기 위한 ADR에 대해 소개하려고 합니다.


ADR이란?

ADR은 Architectural Decision Records의 약자로 아키텍쳐와 관련된 결정을 내렸을 때 그 과정을 기록해 두는 문서를 말합니다. 아마 ADR이라는 단어를 몰라도 큰 규모의 오픈소스를 사용하다보면 많이 접해보셨을거라 생각합니다. 예를 들어 Kubernetes 프로젝트에서는 개선 과제를 제안할 때 KEP 템플릿을 사용하여 문서를 작성하도록 가이드하고 있습니다.

ADR은 간단한 양식을 통해 마크다운 형식으로 작성되며 문제 정의, 결정에 영향을 주는 기본 요구사항, 설계 결정 등의 내용이 포함되어 있습니다. GitHub, Spotify, Google 등 다양한 tech 기업들이 ADR형식을 사용하고 있습니다.


ADR이 필요한 이유

우리는 어떤 방식으로든 팀원들과 함께 의사결정하고 공유하게 됩니다. 그런데 새로운 팀원이 들어오고 히스토리에 대해 묻는다면 기억을 더듬어 당시에 왜 그렇게 했는지 설명합니다. 이러한 과정을 반복하며 시간을 낭비하고 있다면 ADR을 통해 해결할 수 있습니다. 많은 사람들이 말하는 ADR 도입의 장점은 아래와 같습니다.

명확하고 합리적인 의사결정을 내릴 수 있습니다
정의된 ADR 템플릿에 따라 문서화하면 일관된 방식으로 의사결정할 수 있습니다. 저자는 문서를 작성하는 과정에서 더 합리적인 결론을 도출해낼 수 있으며 독자는 문제에 대해 쉽게 이해할 수 있습니다.

새로운 팀원이 적응하는데 많은 도움이 됩니다
새로운 팀원이 들어오면 새로운 개발환경, 아키텍쳐를 이해하기까지 많은 시간을 할애합니다. 만약 ADR을 통해 과거 의사결정 과정까지 알게 된다면 더 쉽게 이해할 수 있습니다.


ADR template

ADR 형식은 정하기 나름이지만 이 글에서는 가장 알려진 템플릿을 기준으로 설명하겠습니다. architecture-decision-record GitHub에서 더 다양한 템플릿과 예시 문서를 확인할 수 있습니다.

1. Status
adr-state

먼저 status는 위와 같은 상태 다이어그램으로 표현되며 현재 문서의 상태를 나타냅니다.

2. Context
Context는 해결하고자 하는 문제를 정의하는 목차입니다.

3. Decision
adr-table

Decision에서는 제안하고자 하는 내용 및 해당 결정의 이유에 대해 설명합니다.
의사결정 과정에서 고려했던 대안들과 장단점에 대한 내용도 포함됩니다.
위와 같이 간단히 비교하는 표를 추가한다면 읽는 사람들이 더 쉽게 이해할 수 있습니다.

4. Consequences
Consequences에서는 결정을 통해 사용자가 받는 영향에 대해 정의합니다. 예를 들어 이 결정이 도입된다면 어떤 효과가 나타날 수 있는지, 마이그레이션 과제라면 다운타임이 발생하는지, 사용자들의 코드 변경이 필요한지 등을 작성합니다.


새로 도입할 때는 ADR이 부담스러운 업무가 되지 않도록 가능한 가볍게 유지할 수 있어야 합니다.
ADR은 나를 위한 것이 아니라 현재 그리고 미래의 팀원들을 위한 것이라고 합니다.
그 동안 문서로 작성 안했다면 아주 간단하게 시작해보는건 어떨까요?


참고 자료

← PrevNext →
  • Powered by Contentful
  • COPYRIGHT © 2020 by @swalloow