CNF 블로그

CNF 블로그에서 최신 정보와 유용한 팁을 만나보세요. 다양한 콘텐츠와 전문 지식을 통해 더 나은 경험을 제공합니다.

아키텍처 의사결정 기록 (Architecture Decision Record, ADR) 작성

ADR (Architecture Decision Record) 는 소프트웨어 아키텍처 결정의 이유와 맥락을 명확히 기록하는 문서입니다.

2025년 07월 07일

아키텍처 의사결정 기록 (Architecture Decision Record, ADR) 작성

아키텍처 결정 기록 (ADR, Architecture Decision Record)

ADR은 소프트웨어 아키텍처에 관한 중요한 결정을 문서화하는 짧은 텍스트 파일입니다. “왜” 특정 기술이나 접근 방식을 선택했는지에 대한 맥락, 결정 내용, 그리고 그로 인한 결과를 기록하여 미래의 팀원들이나 자기 자신이 과거의 의사결정을 쉽게 이해하도록 돕습니다.

ADR의 장점

  • 지식 공유: 팀 전체가 아키텍처 결정의 배경을 이해할 수 있습니다.
  • 신규 팀원 온보딩: 새로운 멤버가 프로젝트의 기술적 역사를 빠르게 파악할 수 있습니다.
  • 논의 반복 방지: 과거에 왜 특정 선택을 했는지 기록이 남아있어 동일한 논의를 반복하지 않아도 됩니다.
  • 책임과 투명성: 결정 과정을 투명하게 만들어 책임 소재를 명확히 합니다.

ADR (Architecture Decision Record) 기본 템플릿

프로젝트 docs/adr 폴더 등에 마크다운(.md) 파일로 저장하는 것이 일반적입니다. 파일명은 ADR-001-결정-요약.md 와 같이 번호와 제목을 포함합니다.

아키텍처 의사결정 기록 (Architecture Decision Record, ADR) 작성하기

# ADR 번호: [제목]

## 상태

[Proposed | Accepted | Deprecated | Superseded by ADR-xxx]

## 컨텍스트
이 결정이 필요한 배경과 관련된 정보를 서술합니다.
현재 시스템 구조나 기술 상황, 외부 제약 조건 등을 기술합니다.

## 결정
어떤 결정을 내렸는지를 명확하게 서술합니다.
선택한 아키텍처나 도구, 패턴, 구조 등과 그 이유를 기술합니다.

## 근거
왜 이 결정을 내렸는지 설명합니다.
다른 대안들과 비교한 장단점, 주요 고려 요소 등을 포함합니다.

## 결과
이 결정이 시스템에 미치는 영향이나, 향후 따라야 할 구현 및 운영 지침을 기술합니다.
추가로 생기는 작업이나 영향 범위 등도 포함됩니다.

## 대안
검토했던 대안들과 선택하지 않은 이유를 요약합니다.

## 작성일자
YYYY-MM-DD

ADR (Architecture Decision Records) 예제

예제 1 – 데이터베이스 선택

# ADR 001: PostgreSQL을 주요 관계형 데이터베이스로 채택

## 상태
Accepted

## 컨텍스트
시스템은 다수의 마이크로서비스가 데이터를 공유하며, 트랜잭션 정합성, JSON 지원, 성능 최적화가 요구됨.
비용 및 클라우드 네이티브 환경과의 호환성도 중요한 고려 요소.

## 결정
PostgreSQL을 기본 RDBMS로 채택한다.

## 근거
– ACID 보장과 트랜잭션 신뢰성 우수
– JSON, GIN 인덱스, 확장성 기능 풍부
– 오픈소스이면서 클라우드 호환성 높음 (AWS RDS, GCP Cloud SQL 등)

## 결과
모든 신규 마이크로서비스는 PostgreSQL을 표준 RDB로 사용하며, 마이그레이션 정책은 별도 문서로 관리.

## 대안
– MySQL: JSON 처리 기능이 부족하고, 레플리케이션 안정성에서 제한이 있음
– CockroachDB: 분산 기능은 강력하지만 운영 복잡도와 비용 증가 요인

## 작성일자
2025-06-29\

예제 2 – 인증 방식 결정

# ADR 002: OAuth 2.1 기반 인증 도입

## 상태
Accepted

## 컨텍스트
서비스는 외부 사용자와 내부 운영자를 대상으로 하는 다양한 API를 제공함.
보안성, 확장성, ID 연동 유연성이 요구됨.

## 결정
OAuth 2.1을 기반으로 한 인증 및 인가 방식을 표준으로 도입함.
내부 서비스 간 통신은 JWT 기반 토큰 인증 구조 사용.

## 근거
– 표준화된 인증 방식으로 보안 이슈 대응 용이
– 인증 서버 분리 가능 → SSO 및 외부 ID 연동에 유리
– JWT 토큰을 활용한 마이크로서비스 간 인증 구조 설계 가능

## 결과
인증 서버는 Keycloak을 기반으로 구축하며, 내부 API Gateway는 JWT 유효성 검증 기능 포함

## 대안
– Basic Auth: 확장성과 보안 측면에서 부적합
– Custom Token 기반 인증: 유지보수 부담과 타 시스템 연동 어려움

## 작성일자
2025-06-29

예제 3 – 메시지 브로커 선택

# ADR 003: Apache Kafka를 이벤트 스트리밍 플랫폼으로 채택

## 상태
Accepted

## 컨텍스트
서비스 간 비동기 이벤트 처리와 로그 수집, 데이터 스트리밍 처리가 필요한 상황.
고성능, 내구성, 메시지 순서 보장이 중요함.

## 결정
Apache Kafka를 메시지 브로커 및 이벤트 스트리밍 플랫폼으로 도입

## 근거
– 높은 처리량과 내구성, 메시지 순서 보장
– 다양한 커넥터 생태계 및 운영 도구 지원
– CNCF 기반의 클라우드 네이티브 서비스와 통합 용이

## 결과
Kafka 클러스터는 내부 전용 네트워크에 배포하며, 서비스는 Kafka Producer/Consumer 패턴으로 통신

## 대안
– RabbitMQ: 큐 기반 메시지 처리에는 적합하나, 대용량 스트리밍에 제약
– NATS: 경량성이 뛰어나지만 메시지 저장과 순서 보장이 약함

## 작성일자
2025-06-29

References & Related Links

이제 나도 MSA 전문가 개념부터 실무까지

Share This Story, Choose Your Platform!

Go to Top