아키텍처 결정 기록(ADR) 작성법과 템플릿

ADR이 필요한 이유

결정의 이유는 몇 달만 지나도 사라집니다. ADR은 “왜 이 기술을 골랐는지”와 “무엇을 포기했는지”를 짧게 남겨, 나중에 같은 논쟁을 반복하지 않게 합니다. 한 번 쓴 ADR은 고치지 않고, 바뀌면 새 ADR로 대체합니다.

배경과 제약을 먼저 쓰기

배경에는 결정이 필요해진 사실과 제약을 적습니다. 예를 들어 결제 처리 흐름을 분리하는 결정이라면 장애가 어디까지 번지는지, 팀이 몇 명이 운영하는지를 적습니다. 기술 이름은 배경에 쓰지 않습니다.

선택지는 다른 회사가 어떻게 했는지로 고르기

선택지를 정할 때 다른 회사가 같은 자리에서 무엇을 골랐는지 확인하면 빠집니다. 스트라이프는 기존 프록시를 자체 데이터 플레인으로 바꾸는 쪽을 택했습니다. 이 사례는 “직접 만든다”가 선택지로 실제 존재한다는 근거가 됩니다.

반대로 도입한 쪽도 있습니다. 우아한형제들은 다국어 번역 시스템을 LLM 기반으로 만들어 서버 배포만으로 해결했습니다. 결정 기록에는 “배포 방식”처럼 선택이 낳은 조건도 함께 적습니다.

메시지 브로커처럼 둘 중 하나를 고르는 결정은 두 기술의 구조 차이를 짧게 정리한 자료를 선택지 근거로 씁니다.

결정과 결과 적기

결정은 “무엇을 하기로 했다”로 시작하는 한 문장으로 씁니다. 결과에는 좋아지는 것만 적지 않고 대가를 함께 적습니다. 대가가 적히지 않은 ADR은 나중에 후회하는 결정이 되기 쉽습니다.

템플릿(복사용)

# ADR-번호: 제목

- 상태: 제안 / 채택 / 대체됨(대체한 ADR 번호)

## 배경

이 결정이 필요한 상황과 제약을 적는다.

## 선택지

- 선택지 A: 장점, 단점
- 선택지 B: 장점, 단점

## 결정

무엇을 하기로 했는지 한 문장, 이유 한두 문장.

## 결과

- 좋아지는 것
- 대가로 생기는 것
- 다시 검토할 조건