ADR 도입기 (1) - ADR 도입에 대한 팀원들의 의견과 피드백

이전 포스트에서 부서 내에 ADR을 도입하려는 계획과 설득을 위한 문서를 작성했었습니다.

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

이 문서를 기반으로 ADR에 대한 필요성을 강조하며 팀원분들과 논의를 했었는데요.

결과적으로는 ADR을 도입해서 작성해보기로 결정되었습니다.

다만, 몇가지 우려사항이 있었고 어느정도 납득 가능할 만한 얘기들이라서 그 부분들은 수용해서 조금은 수정된 방향으로 결정되었습니다.

 

해당 회의에서 나온 의견과 결론은 아래와 같이 정리했습니다.

 

ADR 제안 회의록

ADR 문서화 관련 주요 의견

1. 아키텍처에 대한 변경이 너무 잦아서 문서화가 힘들어 졌다.

• 기존에는 ADR은 없었고 아키텍처 HLD, LLD 문서는 존재했었습니다. (항상 최신 버전은 아니었습니다.)
• 실제로 고객사 대상이 좀 자주 바뀌던 시기가 있었고, 그에따른 요구사항을 매번 엎었다가 뒤집었다가 하는 경우가있었습니다.
• 이런 이유로 문서화를 하더라도 의미가 없었다는 의견이였습니다.
• 어느정도 납득은 됐습니다.
• 다만, 그런 이유에서 라면 문서를 절대 쓰지 말자와 가까운 의견이여서 그 부분은 동의하기 힘들었습니다.

2. 아키텍처 문서도 잘 안쓴다는 의견

• 이것도 동의했습니다.
• 아키텍처도 안쓰면서 ADR을 쓰자는 얘기냐 라는 의견이었습니다.
• 그 부분은 100번 동의를 했고 아키텍처 문서랑 ADR 둘 다 잘 써서 반영해보자는 의견으로 합의되었습니다.

 

ADR에 대한 합의된 의견

1. 단순히 ADR을 작성하는 것보다는 아키텍처 디자인 문서를 작성하고 그것에 더해 ADR을 연결시키는것에는 동의를 한다.

• 위의 ADR 문서화 관련 주요 의견 1,2와 연관되어서 이런 결론이 났습니다.
• ADR이 아키텍처 문서와 완전히 동일하지는 않기에 ADR작성도 필요하고, 아키텍처 문서 작성도 필요했습니다.
• 따라서, 이 두 문서를 조화롭게 잘 써보자는 의견으로 결정되었습니다.

2. 문서를 따로 관리하는것 보다는 소스코드와 함께 관리되는것이 낫다.

• 이 부분은 회의 새로 나온 의견이었습니다.
• 기존 디자인/아키텍처 문서의 유지보수는 컨플루언스를 통해서 이루어졌었습니다.
• 다만, 컨플루언스의 검색성능이 엄청 나빠 검색 경험이 안좋았고, 나중에 필요시에 찾으려고하면 어떤 검색어를 입력해야할지 어디로 찾아 들어가야하는지에 대한 고민부터 있었습니다.
• 이런 문제에 따라서 소스코드의 디렉토리에 각각 필요한 ADR, 아키텍처 문서를 넣는게 어떠냐는 의견이 있었습니다.
• 꽤 납득가능할만한 의견이었고 다 같이 그렇게 하기로 합의를 봤습니다.
• 그래서 작성 방식은 아래와 같이 파일을 만들도록 합의했습니다.
  • internal/database/architecture.md
  • internal/database/adr.md의 파일 제목으로 이름지을것
  • ADR 파일이 변경/업데이트 되어야 하는 경우 히스토리를 파악 할 수 있게 이전의 결정사항들은 문서에 그대로 두고 변경된 결정사항을 위에다가 쓴다 (하나의 파일만 관리하고, 커밋으로 히스토리를 관리하는게 아닌 히스토리를 그대로 적어둔다)
  • 아키텍처 문서 파일 최신 내용만 있으면 되므로, 커밋으로 히스토리를 관리한다.

3. 문서를 강제할 수 있는 수단이 필요하다

• 현재까지 논의했을때는 git hook을 통해서 하면 좋을것 같다는 의견이 있었으나 합의까지는 되지 않았습니다.
• 따라서, 이에 대한 논의가 추가로 필요합니다.
• 기존 문서에 대한 작성은 제가 맡기로 했습니다.
  • 일단은 도입을 제안한 사람이 저고
  • 도입이 잘 됐으면 하는 바람에 팀원들의 부담을 덜어드리는게 도입을 위한 첫걸음이라 생각했습니다.
• 다만,  앞으로 작성될 문서에 대해서는 모두가 각각 쓰는것으로 합의했습니다.

 

일단은 위와 같은 결정 사항에 따라서 코드와 문서들이 작성 되고 있습니다.

다음 포스트에서는 ADR 도입이 잘 되고 있다는 소식을 드릴 수 있으면 좋겠습니다.

 

ADR 템플릿의 경우에는 한번 더 리팩토링을 했는데요.

예시 내용을 쓸데없이 지워야하는 문제가 있어서 렌더링 되는 내용을 제외하면 모두 주석으로 변경했습니다.

아래와 같이 변경했습니다.

# [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) -->