개발자의 의사결정 기록법 (Architecture Decision Record, ADR)

운영하는 서비스의 코드 혹은 아키텍처의 설계를 보다 보면 "왜 이렇게 만들었을까?" 하는 정말 순수한 궁금증이 생긴 적이 많았을 것이다. 우리가 현재 운영하는 서비스는 지금의 모습이 되어 열심히 굴러가기까지 수만은 설계의 갈림길에 있었을 것이고 누군가들은 당시 최고의 방향으로 결정하여 서비스를 만들어 나아갔을 것이다.

그러나 이러한 결정은 기록되지 않으면 그 당시 결정을 위한 노력들이 휘발된다. 혹은 실무자의 입에서 입으로 전해오는 구전영하는 서비스의 코드 혹은 아키텍처의 설계를 보다 보면 "왜 이렇게 만들었을까?" 하는 정말 순수한 궁금증이 생긴 적이 많았을 것이다. 우리가 현재 운영하는 서비스는 지금의 모습이 되어 열심히 굴러가기까지 수만은 설계의 갈림길에 있었을 것이고 누군가들은 당시 최고의 방향으로 결정하여 서비스를 만들어 나아갔을 것이다.

그러나 이러한 결정은 기록되지 않으면 그 당시 결정을 위한 노력들이 휘발된다. 혹은 실무자의 입에서 입으로 구전설화처럼 전해 내려오게 된다면 퇴사 앞에서 정보를 보존할 방법은 없다.

소프트웨어 개발에서는 코드는 버전 관리 시스템을 통해 꼼꼼히 기록이 가능하다. 하지만 정작 그 코드가 왜 그런 형태로 작성되었는지, 어떤 맥락에서 그런 결정이 내려졌는지는 사라지기 쉽다. Architecture Decision Record(ADR)는 이 문제를 해결하기 위한 실천법이다.

ADR이란?

소프트웨어 아키텍처와 관련된 중요한 설계 결정을 문서화하는 방법이다. ADR의 핵심은 단순히 "무엇을 결정했는가"를 기록하는 것이 아니다. "왜 그렇게 결정했는가", "어떤 대안들이 있는가", "그 결정으로 인해 어떤 트레이드오프가 발생했는가"를 함께 남기는 것이다. 내가 생각하는 ADR은 "Why"를 정확하게 기록하는 것이라 생각한다. 업무를 위한 업무는 싫다. 어떠한 상황에서 어떤 결정을 "왜" 했는지를 간단명료하게 기록하는 것이라 생각한다.

일반적인 기술 문서와 뭐가 다른가?

ADR을 처음 접하면 "그냥 설계 명세에 쓰면 되는 거 아닌가?"라는 의문이 들 수 있다. 하지만 ADR은 일반적인 기술 문서와 몇 가지 중요한 차이가 있다고 본다.
 

구분	일반 기술 문서	ARD
초점	현재 시스템이 어떻게 동작하는가	왜 이렇게 설계되었는가
시점	현재 상태 스냄샷	결정 시점의 맥락 보존
변경	시스템 변경 시 함께 수정	불변, 새 ADR로 대체
목적	시스템 이해	결정의 근거 추적

 
ADR은 "불변성"을 가진다는 점이 특히 주요하다 생각된다. 한 번 작성된 ADR은 수정하지 않는다. 상황이 바뀌어 결정을 변경해야 한다면, 기존 ADR을 "대체됨(Superseded)" 상태로 바꾸고 새로운 ADR을 작성한다. 이렇게 하면 결정의 히스토리가 온전히 보존된다.

 

 

ADR 작성의 범위

보통 소프트웨어 프로젝트 또는 제품에 영향을 미치는 모든 구조적으로 중요한 결정에 대해 ADR을 작성한다.

 

- 구조  (e.g. 아키텍처 패턴)

- 비기능적 요구 사항  ( e.g.  보안, 고가용성, 내결합성)

- 종속성  ( e.g.  구성 요소 결함)

- 인터페이스  ( e.g.  API 및 게시된 계약)

- 구성 기법  ( e.g.  라이브러리, 프레임워크, 도구, 프로세스)

 

 

ARD의 구조

ARD의 형식은 사실 정하기 나름이다. 조직마다의 차이점은 있지만, 핵심 구성 요소는 대체로 유사한 듯하다. 가장 널리 사용되는 구조는 다음과 같다

 
[ 상태 Status ]

ADR의 현재 상태를 나타낸다. 일반적으로 다음과 같은 상태값을 사용한다:

 

- Proposed: 제안됨. 아직 논의 중이거나 승인 대기 상태
- Accepted: 수용됨. 팀에서 이 결정을 채택함
- Deprecated: 폐기됨. 더 이상 유효하지 않은 결정
- Superseded by ADR-XXX: 대체됨. 새로운 ADR로 대체되었음을 명시
 
상태 관리가 제대로 되지 않으면 ADR의 가치가 크게 떨어진다. 특히 Superseded 상태에서는 반드시 대체하는 ADR 번호를 명시해야 히스토리 추적이 가능하다.

 

[ 문제 정의 Context ]

결정이 필요하게 된 배경을 설명한다. 이 섹션이 ADR에서 가장 중요한 부분 중 하나다. 좋은 Context는 다음을 포함한다:

 

- 현재 시스템의 상태
- 직면한 문제나 요구사항
- 제약 조건 (기술적, 비즈니스적, 조직적)
- 관련된 이해관계자
- 시간적 압박이나 우선순위

 

[ 결정 Decision ]

선택한 방향을 명확하게 기술한다. 모호하지 않게, 구체적으로 작성한다.

 

[ 대안 Alternatives Considered ]

검토했으나 선택하지 않은 옵션들을 기록한다. 이 섹션이 있어야 "왜 다른 방식은 안 되는 거죠?"라는 질문에 답할 수 있다.

 

[ 결과 Consequences ]

이 결정으로 인해 예상되는 영향을 솔직하게 기록한다. 긍정적인 면만 쓰면 안 된다. 트레이드오프를 명확히 인지하고 있음을 보여줘야 한다.
 

작성예시

e.g. 메시지 큐 도입

 
 

어디에 작성하고 저장해야 할까?

종종 ADR 소개 글에서는 Github 혹은 GitLab과 같은 원격 코드 저장소에서 관리하는 것을 추천한다. (프로젝트 소스 등과 함께)
이는 코드의 변화와 밀접한 연결성을 만들기 쉽고 버전 관리, PR리뷰 등 다양한 장점이 있지만 서비스 아키텍처에 걸친 의사결정이나 API 정의와 같은 공개 인터페이스 정의 의사결정의 경우 기록 장소가 모호해질 수 있다.
그래서 나는 팀에서 사용하는 위키/문서 도구를 이용하는 것이 문서 관리 일원화 측면에서 좋을 것 같다는 생각이 든다. 비록 코드와의 동기화가 어긋나기 쉽다지만, 이 부분은 노력의 영역이라 보며 결국 문서의 동기화 및 일원화는 무조건 필요한 부분이라고 본다.

 

 

우리 팀에게 맞는 ADR은 뭘까?

ADR은 결국 근본적인 작성 원리는 있지만 정해져 있는 틀은 없다. 팀마다 문서 작성 시간이 여유 있는지 혹은 문서 관리 문화가 정착되어 있는지 혹은 업무 방식은 어떠한지 등 다르기 때문에, 팀에 맞는 ADR 작성법에 대해 몇 가지 정하고 정의하는 것이 좋다고 생각된다.

 

- 템플릿은 어떤 항목을 포함할지(Context, Decision, Alternatives, Consequences 중 어디까지 쓸 것인가)
- 문량은 어느 정도 작성할 것인지(한 페이지 이내? 제한 없이?)
- 어떤 규모의 결정을 기록할지(되돌리기 어려운 결정만? 팀 전체에 영향을 주는 것만?)
- 저장 위치는 어디로 할지(코드 저장소? 위키?)
- 리뷰 프로세스는 어떻게 가져갈지(PR 리뷰에 포함? 주에 1번 리뷰? 승인은 누가?)

 

등을 논의해서 결정하면 된다. 처음부터 완벽하게 정하려 하지 말고, 간단한 형식으로 시작해서 팀에 맞게 조금씩 다듬어 나가는 게 현실적인 것 같다.

 

우리 팀의 경우 비교적 빠른 개발 주기를 가지고 있다 그러하여 모든 문서를 정성 있게 쓰기에는 현실적으로 쉽지 않다. 문서는 컨플루언스를 메인으로 사용하고 코드와의 동기화 문화가 잘 형성되어 있다. 규모도 크지 않다. 이러한 상황들을 고려해서 우리는 간단하게 ADR을 어떻게 쓸 것인지 다음과 같이 정하였다.

 

- 코드 작성의 결정보다는 아키텍처의 설계 결정, 외부 공개 API 설계에 대한 결정만 작성하자!
- 소통을 통한 결정은 모두 남지가!
- 구성 요소는 배경,  결정 사항, 결과로 하며, 문제의 원인과 결정에 대한 "왜?"를 명확히 작성하자!
- 작성과 리뷰는 실무자 중심으로 유연하게 진행하자!
- 모든 ADR 문서는 컨플루언스 팀 스페이스의 통합 ADR 폴더 하위에 모으자!
- 최초 작성 이후 절대 수정은 없다!

등

 

 

---

 

 

 

ADR의 핵심 가치는 화려하고 있어 보이는 문서가 아니다. 미래에 우리에게 보내는 메시지의 일부라고 생각된다.
6개월 후의 나, 새로 합류한 동료, 이 프로젝트를 인수인계받을 누군가가 "왜 이렇게 되어 있지?"라고 물었을 때, 답을 줄 수 있어야 한다. 그 답이 "당시에는 이런 상황이었고, 이런 이유로 이 선택을 했다"일 수 있도록. ADR을 작성하면서 부담을 느낄 필요는 없을 것 같다. 중요한 건 꾸준한 습관을 만드는 것이다. 간단한 템플릿으로 시작해서, 팀의 필요에 맞게 조금씩 다듬어 나가면 된다. 오늘 내린 결정의 맥락을, 내일의 누군가를 위해 남겨두자.
 

 

 

참고 자료 

Why write ADRs

 

ADR 프로세스 - AWS 권장 가이드