이미 1년 전에 내렸다가 거부한 데이터베이스 선택을 두고 2주간 논쟁했습니다. 그때 ADR을 발견했고, 이후 수많은 시간을 절약할 수 있었습니다.

아키텍처 결정 기록(ADR) 모범 사례

회의는 이미 두 시간째였습니다. 새 서비스에 PostgreSQL을 사용할지 MongoDB를 사용할지 논쟁하고 있었습니다. 관계형 무결성, 유연한 스키마, 팀 친숙도, 운영 복잡성에 대한 의견이 오갔습니다.

그때 누군가가 말했습니다: "작년에 사용자 서비스에서 정확히 같은 논의를 하지 않았나요?"

침묵. 맞았습니다. 1년 전 같은 질문에 비슷한 시간을 들여 논의하고 결국 PostgreSQL을 선택했습니다. 하지만 아무도 그 이유를 기억하지 못했습니다. 그 논의를 이끌었던 엔지니어는 회사를 떠났습니다. 그래서 우리는 처음부터 정확히 같은 논쟁을 하고 있었습니다.

그때 아키텍처 결정 기록(ADR)을 발견했고, 이미 해결된 논쟁을 되풀이하는 데 드는 수많은 시간을 절약할 수 있었습니다.

ADR이란?

ADR은 하나의 아키텍처 결정을 캡처하는 짧은 문서입니다. 시스템에 대한 모든 것을 다루는 설계 문서가 아니라, 단 하나의 결정입니다:

무엇을 결정했는가
왜 결정했는가
어떤 대안을 고려했는가
결과는 무엇인가

형식은 의도적으로 가볍습니다. ADR은 한 페이지에 맞아야 합니다. 더 길다면 아마 하나 이상의 결정을 문서화하고 있는 것입니다.

좋은 ADR의 구조

수십 개의 ADR을 작성하고 수백 개를 더 읽은 후, 최고의 ADR은 일관된 구조를 따른다는 것을 알았습니다:

제목과 번호

모든 ADR은 순차 번호와 간결한 제목을 받습니다:

ADR-0042: 주문 서비스에 PostgreSQL 사용

번호가 중요합니다. 결정의 타임라인을 만들고 논의에서 ADR을 쉽게 참조할 수 있게 합니다: "ADR-42에서 결정한 대로..."

상태

ADR에는 라이프사이클 상태가 있습니다:

제안됨: 아직 논의 중
수락됨: 결정 완료, 이것을 따르고 있음
폐기됨: 더 이상 관련 없음 (새 ADR이 대체)
거부됨: 고려했지만 반대로 결정

거부 상태는 특히 가치 있습니다. 때로는 왜 무언가를 하지 않았는지 캡처하고 싶을 때가 있어, 미래 팀이 같은 것을 제안하지 않도록 합니다.

컨텍스트

결정을 촉발한 상황을 설명합니다. 어떤 문제를 해결하고 있나요? 어떤 제약이 있나요? 누가 영향을 받나요?

## 컨텍스트

주문 서비스는 주문 데이터를 위한 영구 저장소가 필요합니다.
초기에 하루 50,000건의 주문을 처리하고 2년 내에 500,000건으로
성장할 것으로 예상합니다. 주문은 잘 정의된 구조를 가지지만
시간이 지나면서 추가 메타데이터 필드가 필요할 수 있습니다.
팀은 관계형 데이터베이스와 문서 데이터베이스 모두 경험이 있습니다.

제약에 대해 구체적으로 작성하세요. "ACID 준수가 필요합니다"가 "신뢰성이 필요합니다"보다 훨씬 유용합니다.

결정

결정을 명확하게 서술합니다. "고려할 수 있다" 또는 "탐색해야 한다"가 아니라 — 실제로 무엇을 결정했는지.

## 결정

주문 서비스의 기본 데이터베이스로 PostgreSQL 15를 사용합니다.

PostgreSQL을 선택한 이유:

- 금융 주문 데이터에 ACID 준수가 필요
- JSON 컬럼이 메타데이터에 대한 스키마 유연성 제공
- 인프라 팀이 PostgreSQL 운영 경험 보유
- 쿼리 패턴이 관계형 모델링에 적합

고려된 대안

가장 과소평가된 섹션입니다. 선택하지 않은 것을 문서화하는 것은 선택한 것을 문서화하는 것만큼 가치 있는 경우가 많습니다.

## 고려된 대안

### MongoDB

장점:

- 네이티브 JSON 저장
- 더 간단한 수평 확장
- 유연한 스키마 진화

단점:

- 약한 일관성 보장
- 팀의 운영 경험 부족
- 트랜잭션을 위한 추가 도구 필요

### DynamoDB

장점:

- 완전 관리형, 최소한의 운영
- 우수한 확장성 특성

단점:

- AWS에 대한 벤더 종속
- 파티션/정렬 키 접근으로 제한된 쿼리 패턴
- 고규모에서 예측 불가능한 비용

결과

모든 결정에는 트레이드오프가 있습니다. 솔직하게 작성하세요.

## 결과

### 긍정적

- 강력한 데이터 무결성 보장
- 팀이 기존 PostgreSQL 전문성 활용 가능
- 잘 이해된 운영 특성

### 부정적

- 스키마 마이그레이션이 문서 저장소보다 더 많은 계획 필요
- 단일 노드 용량 초과 시 수평 확장이 더 복잡
- 규모 제한 도달 시 애플리케이션 수준 샤딩 구현 필요

### 리스크

- 주문량이 하루 100만 건을 초과하면 재검토 필요 가능
- JSON 컬럼 쿼리가 네이티브 문서 저장소보다 덜 효율적

ADR을 언제 작성할 것인가

모든 기술적 선택에 ADR이 필요한 것은 아닙니다. 판단을 사용하되, 다음과 같은 지침이 있습니다:

ADR을 작성해야 할 때...

결정이 여러 팀이나 서비스에 영향을 미칠 때
결정을 되돌리는 데 비용이 클 때
여러 실행 가능한 옵션 중에서 선택할 때
미래 팀원이 선택에 의문을 가질 수 있을 때
결정이 중요한 기술적 논쟁을 해결할 때

ADR을 작성하지 않아도 될 때...

선택이 명백하고 논쟁의 여지가 없을 때
결정이 한 사람이나 한 파일에만 영향을 미칠 때
큰 비용 없이 쉽게 되돌릴 수 있을 때
팀이 항상 따르는 표준 패턴일 때

내가 저지른 흔한 실수들

실수 1: 사후에 ADR 작성

ADR을 작성하기 가장 좋은 시기는 결정 과정 중이지, 몇 주 후가 아닙니다. 나중에 쓰면 뉘앙스, 고려한 대안, 특정 제약을 잊어버립니다.

이제 우리는 의사 결정 과정의 일부로 ADR 초안을 작성합니다. 논의는 사라지는 Slack 스레드가 아닌 ADR 문서에서 이루어집니다.

실수 2: 너무 길게 만들기

ADR이 한 페이지를 넘으면, 아마도:

여러 결정을 문서화하고 있음 (여러 ADR로 분할)
구현 세부사항을 포함하고 있음 (설계 문서로 보관)
명백한 맥락을 과도하게 설명하고 있음

간결함의 규율이 명확성을 강제합니다.

실수 3: 관련 ADR을 연결하지 않기

결정은 고립되어 존재하는 경우가 드뭅니다. 이벤트 기반 통신을 위해 Kafka를 선택했을 때(ADR-0007), 이것은 최종 일관성을 수용할 수 있었기 때문에 데이터베이스 선택(ADR-0042)에 영향을 미쳤습니다.

실수 4: 실천을 포기하기

ADR은 시간이 지남에 따라 가치를 제공합니다. 1-2개의 ADR은 큰 도움이 되지 않습니다. 수년에 걸쳐 축적된 50개 이상의 ADR 모음은 엄청나게 가치 있게 됩니다. 아키텍처 진화의 검색 가능한 역사입니다.

바쁠 때 작성을 중단하고 싶은 유혹이 있습니다. 저항하세요. ADR 작성에 10분을 투자하면 나중에 몇 시간의 회의를 절약할 수 있습니다.

ADR을 워크플로우의 일부로 만들기

가장 어려운 부분은 ADR을 작성하는 것이 아니라 습관으로 만드는 것입니다. 효과가 있는 방법은 다음과 같습니다:

코드와 함께 저장

ADR을 저장소에 넣으세요, 일반적으로 docs/adr/ 또는 docs/decisions/에. 이렇게 하면:

설명하는 코드와 함께 버전 관리됨
코드 리뷰에 나타남
어딘가의 위키에서 고아가 될 수 없음

템플릿 만들기

모두가 사용하는 마크다운 템플릿을 만드세요. 이것은 마찰을 줄이고 일관성을 보장합니다.

분기별 ADR 검토

분기마다 ADR을 검토하는 리마인더를 설정하세요:

더 이상 관련 없는 결정이 있는가?
우리의 가정을 무효화하는 상황 변화가 있었는가?
캡처해야 할 문서화되지 않은 결정이 있는가?

ADR을 아키텍처 다이어그램에 연결

이것은 Archyl과 같은 도구가 빛나는 곳입니다. C4 다이어그램의 특정 컴포넌트에 ADR을 연결하면, 해당 컴포넌트를 보는 누구나 이를 형성한 결정을 즉시 볼 수 있습니다.

"왜 이 서비스가 데이터베이스 대신 Kafka와 통신하지?" 연결된 ADR을 클릭하면 알 수 있습니다.

결론

아키텍처 결정 기록은 필요할 때까지 오버헤드처럼 느껴지는 관행 중 하나입니다. 그때는 매우 소중해집니다.

PostgreSQL vs MongoDB에 대한 2시간짜리 회의? 누군가가 원래 ADR을 찾은 후 10분 만에 끝냈습니다. 모든 맥락이 거기에 있었습니다 — 제약, 대안, 이유. 원래 결정이 여전히 적용된다는 것을 빠르게 확인하고 다음으로 넘어갔습니다.

작게 시작하세요. 다음에 아키텍처 결정을 내릴 때 15분을 들여 ADR을 작성하세요. 저장소에 넣으세요. 6개월 후 누군가가 "왜 그렇게 했지?"라고 물으면 답을 가지고 있을 것입니다.

아키텍처 문서에 대해 더 알아보기: C4 모델 소개 | 왜 문서화가 중요한가 | 사용자 플로우 문서화

아키텍처 결정 기록(ADR) 모범 사례 - Archyl Blog