아키텍처 의사 결정 기록을 작성해야 하는 이유

안녕하세요. 주간SaaS 입니다. 오늘은 Spotify에서 ADR(Architecture Decision Record)를 사용하는 이유가 담긴 글을 소개 합니다.

ADR은 한글로 하면 아키텍처 결정 레코드 라고 할수 있는데요, 일종의 인프라 아키텍처 또는 소프트웨어 아키텍처에서 특정 디자인 패턴, 라이브러리 등 그것을 선택한 이유를 담고있는 기록물 입니다.

아키텍처는 생물과 같아서 끊임 없이 성장하고 진화하는데, 이 과정을 기록해 팀 모두가 정렬(Alignment)되어 있다면 서비스 품질 유지, 생산성, 장애 예방등 여러 장점을 채택할 수 있을것 같습니다. 특히나 고객 피드백, 시장 상황, 세일즈 상황에 따라 유연하고 민첩하게 변화하는 SaaS 아키텍처에도 도움이 될거라 생각 됩니다.

오늘 소개하는 Spotify 블로그 외에도, ADR에 관한 좋은 설명과 예시는 많이 노출되어 있는데요 구글클라우드 에서 정리한 다음 글도 한글로 쉽게 정리 되어 있습니다.

뿐만 아니라 아래의 UK에서 AWS 기반의 Gov Cloud를 만드는 과정에서 만든 ADR도 시간이 허락한다면 살펴 보셔도 좋을것 같습니다.

그럼 좋은 하루 되세요!

요약: 엔지니어가 소프트웨어를 작성하는 방식에 영향을 미치는 중요한 결정을 내리셨나요? ADR을 작성하세요!

아키텍처 의사 결정 기록(Architecture Decision Record, ADR)은 의사 결정이 이루어진 맥락과 의사 결정 채택의 결과를 포함한 의사 결정 과정을 기록하는 문서입니다. Spotify에서는 소수의 팀에서 ADR을 사용하여 의사 결정을 문서화합니다. ADR을 사용하는 팀 중 하나인 크리에이터 팀은, 크리에이터가 Spotify에서 자신을 표현하고 콘텐츠에 대한 데이터에 액세스할 수 있는 도구를 제공하는 팀 입니다. 크리에이터 팀은 시스템 설계 및 엔지니어링 모범 사례와 관련된 의사 결정을 문서화하기 위해 ADR을 활용합니다. 일반적으로 의견 요청(Request for Comments, RFC) 또는 엔지니어링 회의에서 논의를 통해 이러한 결정에 도달합니다.

어떤 이점이 있나요?

ADR을 도입한 후 저희 팀은 다음과 같은 여러 가지 이점을 발견했습니다:

온보딩

미래의 팀원들은 의사 결정 내역을 읽고 의사 결정의 과정과 이유, 그리고 그 결정의 영향에 대해 빠르게 파악할 수 있습니다. 예를 들어, 2019년에 크리에이터 웹 엔지니어들은 React Hook을 도입 하기로 결정했습니다. 격주로 열리는 웹 엔지니어링 회의 중 하나에서 애플리케이션의 작은 부분에서 작은 실험을 실행한 후 이 결정을 내렸습니다. 이 결정의 결과는? 새로운 클래스 컴포넌트 생성을 중단하고 함수 컴포넌트를 사용하기로 했습니다.

소유권 이양

Spotify에서는 빠른 학습을 목표로 하는 애자일 환경에서 일합니다. 이러한 환경에서 우리는 진화하는 사용자의 요구를 충족하기 위해 주저하지 않고 조직의 변화를 구현합니다. 조직이 변화하면 시스템의 소유권을 한 팀에서 다른 팀으로 옮겨야 할 때도 있습니다. 과거에는 이 서비스 시스템의 오너가 변경되는 과정에서 많은 컨텍스트와 관련 지식이 사라져 생산성이 저하되는 경우가 많았습니다. ADR을 도입하면서 이 문제는 덜 심각해졌습니다. 시스템의 새로운 소유자는 ADR을 읽는 것만으로도 시스템 아키텍처가 어떤 방식으로 진화했는지, 왜 그런 방식으로 진화했는지 빠르게 파악할 수 있습니다.

정렬(Alignment)

ADR을 통해 팀은 Spotify 전반의 모범 사례에 더 잘 따르는 의사 결정을 만들수 있었습니다. 정렬은 중복 작업을 없애고, 프로젝트 전반에서 코드를 재 사용할 수 있게 하며, 중앙 팀이 지원해야 하는 솔루션의 다양성을 줄이는 이점이 있습니다. 예를 들어 스톡홀름 지사의 팀들은 뉴욕에 있는 크리에이터 웹 엔지니어가 작성한 "React Hook"을 읽고 참조하여 채택할 수 있었습니다.

알았어요! 하지만 언제 작성해야 할까요?

"ADR은 멋지네요! 우리 팀이 의사 결정을 원활하게 하는 동시에 미래의 팀원들과 우리 자신을 위해 의사 결정에 대한 기록을 남기는 데 꼭 필요한 것이죠! 하지만 언제 작성해야 하나요?"

ADR은 중대한 영향을 미치는 결정을 내릴 때마다 작성해야 하며, 무엇이 중대한 영향을 미치는지에 대한 정의는 각 팀에 달려 있습니다. 시작하기 위해 ADR 작성 시기를 결정하기 위한 몇 가지 시나리오와 저의 멘탈 모델을 소개합니다:

결정에 대한 추가 정보 채우기

때로는 결정이 내려졌거나 암묵적인 기준이 저절로 형성되지만 문서화되지 않았기 때문에 모든 사람(특히 신입사원)이 이러한 결정이 존재한다는 사실을 명확히 알지 못하는 경우가 있습니다. 어떤 결정이 내려졌지만 기록되지 않았다면 그것이 표준이 될 수 있을까요? 문서화되지 않은 결정을 식별하는 한 가지 방법은 동료 검토입니다. 다른 코드 패턴이나 라이브러리를 도입하는 과정에서 검토자가 문서화되지 않은 결정을 발견할 수 있습니다. 아래는 아키텍처 결정을 언제 다시 작성해야 하는지에 대한 저의 의사 결정 모델입니다:

큰 변경 사항 제안

시스템의 수명 주기 동안 시스템의 설계, 유지 관리, 확장 등에 큰 영향을 미치는 결정을 내려야 할 때가 있습니다. 요구사항이 진화함에 따라 API에 획기적인 변경을 도입해야 할 수도 있으며, 이 경우 소비자의 마이그레이션이 필요할 수 있습니다. 저희는 접근 방식이나 구현 방식에 대한 팀 내 합의를 빠르게 하기 위해 시스템 설계 검토, 아키텍처 검토, RFC 과정을 거칩니다. 이러한 프로세스가 진행될 때 내린 결정을 어떻게 기록해야 할까요? 아래는 이러한 큰 변화를 문서화하는 방법에 대한 저의 의사 결정 모델입니다:

작은 변경 사항/변경 사항 없음 제안

우리는 일상에서 작은 결정들을 많이 내리는데, 이러한 결정들은 대부분 큰 영향을 미치지 않습니다. 하지만 문서화되지 않은 결정들의 비용을 측정 하기는 어렵고, 보통 이러한 결정들은 중복된 노력(다른 엔지니어들이 같은 문제를 해결하려고 시도하는 것)이나 경쟁적인 해결책(동일한 기능을 수행하는 두 개의 서드파티 라이브러리를 사용하는 것)과 같은 문제를 야기합니다. 이런 작은 결정들이 축적되어 나중에는 큰 프로세스나 많은 노력을 필요로 하는 문제(예: 마이그레이션)로 발전할 수 있습니다. 이러한 결정들을 문서화하는 것은 많은 비용이 들지 않습니다. 아키텍처 결정 기록(ADR)은 가볍게 만들 수 있습니다. 아래는 이러한 상황을 처리하기 위한 제가 사용하는 의사 결정 과정입니다.

다이어그램으로 정리해 봅시다!

아키텍처 결정 기록은 언제 작성해야 하나요? 거의 항상!

주간 SaaS 에 대한 피드백(익명)을 남길 수 있어요