우리 부서에 맞는 ADR (Architecture Decision Record) 템플릿 작성과 ADR 시스템 도입

현재 우리 부서 상황에 맞는 ADR 템플릿을 작성해 보려고 합니다.

사실은 ADR이 무엇인지, ADR을 써야하는 이유는 무엇인지에 대해서 먼저 쓰고 싶었는데

일단 부서내에서 ADR 사용에 대한 의견 제시를 앞두고 있어서 ADR에 대한 요구 사항을 먼저 정리하고 그 템플릿을 먼저 만들어 보려고 합니다.

 

ADR 자체의 내용에 대한 포스트는 다음 포스트에서 정리 될 예정입니다.

우선은 아주아주 간단하게 ADR이 뭔지 왜 필요할지 적어봅니다.

 

ADR (Architecture Decision Records) 이란?

아키텍처와 관련된 결정을 내렸을때 그 과정을 기록하는 문서입니다.

 

ADR을 쓰는 이유?

회사에서는 팀원들과 의사 결정 및 공유하는 과정이 회의나 미팅을 통해서 진행됩니다.

1. 그곳에서 결정된 모든 사항들이 모든 부서원들에게 전달이 되면 좋겠지만 일이 바쁘면 그게 쉽지 않습니다.

2. 또한, 기존 개발을 맡았던 팀원이 나가고 새로운 팀원이 들어오면서 기억과 구전으로만 전달되는 내용이 많습니다.

 

위의 이유로 레거시의 결정에 대한 히스토리나 근거가 부실해 혼란인 경우가 많고, 예전에 했던 논의들을 반복하는 경우도 발생합니다.

이를 ADR이라고 하는 간단한 문서를 통해서 막으려고하는것입니다.

 

우리 부서의 예시를 들어보겠습니다.

지난 2월 우리의 SW의 upgrade를 담당하는 모듈 개발하셨던 분이 5년간 학술연수를 가게되었습니다.
그런데, 3월에 해당 모듈에 대한 사용법 및 구현 로직이 필요한 부분이 있었는데, 확인해보니 코드가 빨리 확인하기에 복잡하고 정확하게 힘들어 혼선이 빚어졌습니다.
그래서 다른 부서원들에게 사용법에 대한 질문을 던졌습니다.

A 님. upgrade-agent에 직접 API를 쏴야한다는 의견
B 님. 기존 rest api를 통해서 쏴야한다는 의견
C 님. 잘 모르겠다는 의견

 

떠나신지 얼마안된분이라 다행히 카카오톡으로 직접 여쭤봐서 해결했습니다.

정답은 뭐였을까요? A였습니다. (저는 B를 주장했었구요..)

만약, 그분과 친하지 않았고, 연락이 잘 안됐다면 어땠을까요?

확인 과정이 조금 더 오래걸렸을것입니다.

 

이때 생각이 들었습니다. ADR이란게 있었다면 쓸데없이 확인하는 과정없이 문서만 검색해도 됐을텐데!

 

그래서 우리 부서에 맞는 ADR Template은 어떤 형태일지 고민을 해봤습니다.

 

우리 부서의 현황 및 제약사항

일단 부서의 현황 및 제약사항을 먼저 이해해보겠습니다.

 

1. 일이 많아서 문서를 쓸 시간이 많지는 않습니다.
2. 문서 작성 자체를 귀찮아 하는 케이스가 많습니다.
3. 기존에도 Confluence를 통해서 문서화에 대한 많은 노력을 했었습니다. 다만 결국은 실패했습니다. (e.g. 주로 SRS 같은 문서들 + 아키텍처 문서들)
4. ADR에 대한 이해가 높지는 않습니다. ( 결정 문서에 대한 개념은 있었지만, ADR 까지는 도입해보지 않은 상태였습니다.)
5. 리더님과 관련된 얘기를 해봤을때는 Github에 ADR을 관리하는것을 원하셨습니다.
   1. 히스토리를 관리하기 쉽고
   2. Confluence의 경우 검색 성능이 너무 안좋아서 문서를 검색하면 찾는데 시간이 오래걸리는 문제가 있습니다. (검색에 대한 결과가 원하는 타겟이 바로 안나오고 너무 많이 나오는 경향이 있습니다.)
6. ADR이 업로드될 Github Repository와 그 결정사항이 반영된 코드가 올라갈 Github Repository가 다릅니다.  (리더님의 결정이기도 합니다.)

 

이 정도의 상황이 있습니다.

 

위의 조건과 저의 몇가지 의견을 포함하여 ADR 템플릿의 요구사항을 한번 만들어보겠습니다.

 

ADR 템플릿 요구사항

1. 한글로 작성하자.

이 부분은 회사 자체가 해외 연구소랑 업무를 하는 경우가 있어서, 소통을 위해서 영어로 문서 작성을 많이 하는 경향이 있었습니다. (현재도 해외 연구소와 협업하는게 있어서 영어가 필요한 경우가 왕왕 있긴합니다.)

다만, 아키텍처 결정사항의 경우 우리 파트 내부에서 (한국인들밖에 없음) 관리하는 문서임에도 불구하고 영어로 되어 있을 필요는 없는데, 혹시나 하는 마음에 영어로 쓰게 되는 경향이 있는것 같습니다.

그런 경우에는 아래의 문제가 발생할 수 있습니다.

• 쓸때 : 한글로 작성하는것 보다 전달력이 떨어지고 오래걸린다. + 쓰기가 귀찮고 부담이 늘어난다.
• 읽을때 : 한글로 작성하는것 보다 이해력이 떨어지고 오래걸린다.

그래서 우리 부서가 사용하는 문서이니만큼 한글로 작성해야한다고 생각했습니다.

만약에 해외 연구소에 전달이 필요한 내용이라면 바로 번역기로 돌려서 최소한의 전달할 수 있게 하는게 좋은 방법일것 같습니다.

 

2. 문서 작성에 최소한의 노력을 들게하자.

이 부분은 최대한 Template을 사용하기 쉽게 만드는 부분으로 해결해야 할 것같습니다.

1) ADR을 어떻게 써야하는지 모르는 사람이 쓰기쉽게

2) Confluence에 먼저 쓰더라도 복사 붙여넣기로 Github에 바로 업로드 가능한 형태

2번의 경우 대부분 회사에서 문서작업의 시작은 Confluence에서 하므로, Confluence -> Github 변환에 대한 노력을 없애기 위함입니다.

이러한 이유로 ADR 템플릿은 Gtihub에서 바로 호환이 되는 markdown의 형태가 되어야 할 것같습니다.

 

그래서 여러가지 형태를 찾아봤을때 아래와 같은 템플릿이 적당하다고 생각했습니다.

architecture-decision-record/locales/en/templates/decision-record-template-of-the-madr-project at main · joelparkerhenderson/ar

그리고 위의 템플릿을 적절히 한글화 및 수정했습니다

 

# [ADR-] 문제와 해결방법을 포함한 짧은 제목

* 문서 상태: proposed [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
* 결정한 모든 사람들 : 
* 날짜: 

## 컨텍스트와 문제 정의

[아래에 상황과 문제를 정의합니다, 예를 들면, 자유 형식으로 2~3 문장으로 간결하게 설명하면 좋습니다.]

## 결정 근거 

* [근거 1, e.g., Performance & Scalability]
* [근거 2, e.g., Advanced Features, Community & Support, License, etc...]
* … <!-- 결정 근거는 매 결정마다 다를 수 있습니다 -->

## 고려한 옵션들
[어떤 옵션이 있는지만 아래에 리스트로 작성합니다. e.g. * MYSQL, * POSTGRESQL]
* 
*
*
* … <!-- 옵션 수는 매 결정마다 다를 수 있습니다. -->

## 결정 사항

[결정된 옵션과 이유를 서술합니다, 이유의 예시 : 유일한 옵션이거나 | 우리의 요구사항을 만족하거나 | 결과가 가장 좋거나 ]


### Consequences <!-- optional -->
[결정으로 인해 좋아지는 점과 나빠지는 점]

* [e.g. 러닝 커브 필요, Migration 필요함]


## 옵션들의 장점과 단점 <!-- optional -->

[장점 및 단점을 먼저 서술하고, 근거를 적는것을 권장합니다. e.g. * 장점, a덕분이다.]

### [옵션 1]

[예시 | 설명 | …] <!-- optional -->

* 
*
*

### [옵션 2]

[예시 | 설명 | …] <!-- optional -->

*
*
*

### [옵션 3]

[예시 | 설명 | …] <!-- optional -->

*
*
*

## 연관 ADR들 <!-- optional -->

* [Link type] [ADR 링크 삽입] <!-- 예시: Refined by [ADR-0005](0005-example.md) -->

 

위를 만들면서 몇가지 적용사항이 있었습니다.

1. 필수 사항이 아닌 부분은 <!-- optional -->로 처리를 해 두었습니다.
2. 그리고 작성시마다 예시로 채워져 있는 텍스트 삭제를 귀찮아 하는 경우를 많이 봤어서 최대한 삭제하지 않아도 되도록 템플릿을 작성했습니다.
   (Github의 PR 템플릿도 자세하게 적혀있지만 대충 PR 템플릿에 익숙해진 시점부터는 오히려 템플릿이 비어있으면 좋겠다는 느낌과 경험을 많이 받았습니다.)
3. JIRA 링크를 거는 부분이 있었으나, 삭제했습니다. (JIRA task를 찾아서 링크걸고 하는게 ADR 작성을 오히려 방해 할 것 같았습니다.)
4. 주석 등으로 각 ADR 항목에 어떤 내용을 써야할지를 보강해서 ADR 작성을 돕도록 했습니다. 또한 이 주석들은 삭제가 필요없습니다.

 

일단은 위와 같은 템플릿을 만들어서 부서내에서 제안하고 적용을 해 볼 예정입니다.

다만, 템플릿만 만든다고 ADR이라는 작성이 모든 사람이 문서를 잘 만들거나 아주 잘 적용되지는 않을것 같습니다.

시스템적으로 ADR의 유지보수가 지속적으로 관리 되도록 해야합니다.

 

ADR을 유지보수하는 시스템

우리 부서에서는 다행히 2주마다 개발 Sprint를 진행하고있습니다.

그 시간에 30분정도 추가로 시간을 내어 해당 Sprint에서 작성된 ADR을 모두 같이 리뷰하여 확인을 하거나 수정을 하면 지속가능한 ADR 문서 작성 및 관리가 가능하지 않을까 생각을 하고 있습니다.

 

목적은 아래와 같습니다.

1. 특정 개발의 결정사항에 대한 부서원들간의 공유 

2. ADR 문서 작성 독려 및 지속적인 유지보수

3. 작성된 ADR을 리뷰를 하고 한번에 Github에 Push (개별적으로 올리지 않고, 문서를 준비했다가 한명이 한번에 올리기)

 

3의 경우는 위의 우리 부서의 제약사항 6번과 연관이 있습니다.

코드를 올릴때 동시에 문서로 작성한 템플릿을 한번에 못올린다는 것입니다.

문서 repo가 코드 repo랑 다르기때문이죠

이게 작은 부분인것 같지만 하나하나가 귀찮은게 사람들에게 큰 영향을 주는것 같습니다.

 

그래서 코드 작성시에 어차피 결정사항을 적어두거나 반영을 해야하니까.

1. ADR Template을 confluence로 작성을 완료해두고

2. 해당 Confluence들을 모아서 Sprint마다 한번에 리뷰하고

3. ADR 리뷰가 끝났을 때 한명이 한번에 ADR들을 업로드 하는 방식

이런 식으로 하면 좋을것 같다는 생각이 들었습니다.

 

리뷰시에 ADR 변경점이 생기면 ADR에 다시 추가 커밋올리는것 만큼 귀찮은게 없으니까요..

그래서 리뷰를 다 하고 Accepted 된 문서만 올리는것이죠. (귀찮음을 최소화!)

 

애초에 ADR 문서를 쓰는게 귀찮은거 아니냐고 할 수 있지만, 안썼을때의 단점이 썼을때보다 큰것 같으니 쓰는게 더 좋다고 저는 그렇게 생각하고 있습니다.

 

여기까지 정리 했으면 아마도 ADR 작성을 부서단위로 시작할 수는 있을것 같습니다.

조금 더 고민 해야할 부분이 있기는 한데, 이 부분은 진행하면서 부서원들간의 컨센서스를 맞춰가면서 결정해도 될것같습니다.

 

고민이 되는 부분

1. ADR 작성의 단위 : 어느 정도까지 결정사항을 적어야하는것인가?

-> 결정이 필요한 모든 단위에 대해 결정 사항을 기록하는것이 좋을것 같습니다.
기준 : 다른 사람과 논의해야하는 내용이거나 어떤 결정이 필요한 내용이면 모두!

 

2. ADR 작성의 크기 : 한 문서에 어느정도 내용이 들어가야하는가?

-> 비슷한 기능에 대한 결정사항은 하나로 합쳐도 되지 않을까 싶습니다. 혹시나 그런 경우가 많이 없어 문서가 너무 많아 지지 않을까 하는 걱정이 있긴한데 리더님께서는 그렇게 많지는 않을것 같다는 의견을 주셨습니다.