2nd/10_Wiki/Topics/ADR (Architecture Decision Records).md

---
id: P-REINFORCE-WIKI-ADE8D6B9
category: Unified
confidence_score: 0.95
tags: ['adr-(architecture-decision-records)', 'atam-(architecture-trade-offs-analysis-method)', 'iso/iec-25010-(품질-모델)', '프로토타이핑-및-개념-증명(poc)', '의사결정-매트릭스(decision-matrix)', 'process-methodology']
last_reinforced: 2026-05-02
---

# [[ADR (Architecture Decision Records)]]

## 📌 Brief Summary
ADR(Architecture Decision Records)은 아키텍처 결정 사항과 그 근거를 이해하기 쉽고 검증 가능하게 문서화하는 도구입니다 [1-3]. 시스템의 맥락, 결정 내용, 합리적 근거, 고려된 대안, 그리고 단/장기적 위험과 결과를 기록함으로써 시간이 지나도 과거의 결정 배경을 추적할 수 있게 합니다 [3, 4]. 이를 통해 새로운 팀원, 감사자, 기타 이해관계자들이 시스템을 깊이 이해하고 진화시키는 데 필요한 핵심 자산으로 활용됩니다 [3, 4].

## 📖 Core Content
* **문서화의 전략적 가치:** 소프트웨어 아키텍처 결정은 한 번 내려지면 되돌리기 어렵고, 시간이 흐를수록 그 배경과 맥락이 쉽게 잊혀집니다 [3]. 따라서 어떤 기술적 배경에서 결정이 이루어졌는지 체계적인 이력 관리를 하기 위해 ADR의 작성이 필수적으로 요구됩니다 [3].
* **ADR의 핵심 구성 요소:** ADR은 객관적인 결정을 담보하기 위해 보통 다음과 같은 구체적인 항목들을 포함하여 작성됩니다 [3, 4].
  * **맥락(Context):** 결정이 내려지게 된 초기 상황과 기술적 배경은 무엇인가?
  * **결정(Decision):** 구체적으로 무엇을 선택하고 결정했는가?
  * **근거(Reason/Justification):** 이 선택을 하게 된 객관적이고 합리적인 이유는 무엇인가?
  * **대안(Alternatives):** 어떠한 대안들을 검토했으며, 해당 대안들은 왜 거절되었는가?
  * **위험 및 결과(Risks and consequences):** 이 결정이 단기 및 장기적으로 어떤 결과와 기술적 위험을 초래할 수 있는가?
* **아키텍처 진화의 이력 관리:** 훌륭한 아키텍처는 고정된 것이 아니라, 트래픽(부하)의 변화나 새로운 통합 요구사항, 팀의 스킬셋 변화 등 운영 컨텍스트가 변화함에 따라 지속적으로 진화해야 합니다 [3, 5]. 컨텍스트가 변화하여 아키텍처를 수정할 때마다 ADR을 정기적으로 검토하고 함께 업데이트함으로써, 시스템이 거쳐온 진화의 궤적을 명확하게 문서화합니다 [5].

## ⚖️ Trade-offs & Caveats
**소스에 ADR 도입 자체에 대한 구체적인 부작용이나 제약 사항에 관한 정보는 부족합니다.** 

다만, 주어진 소스는 **"완벽한 아키텍처란 없으며 모든 결정은 타협(Trade-off)의 결과"**라고 강조합니다 [6]. 따라서 ADR은 특정 아키텍처를 선택하는 과정에서 발생하는 트레이드오프(예: 고도의 보안성을 얻기 위해 성능(대기 시간)을 희생하거나, 일관성을 양보하여 가용성을 높이는 등의 결정)를 식별하고, 이로 인한 제약 사항 및 타협 지점(Trade-off Points)을 투명하게 기록하는 수단으로 기능합니다 [3, 6, 7]. 즉, 기술적 선택의 반대 급부를 관리하고, 이를 시스템의 위험 요소로 명확히 인지하기 위해 ADR이 사용됩니다 [3, 4, 7].

## 🔗 Knowledge Connections

### Related Concepts

#### [관계 유형 A: 아키텍처 평가 및 분석 방법론]
- [[ATAM (Architecture Trade-offs Analysis Method)]]
  - 연결 이유: ATAM은 특정 아키텍처가 비즈니스 목표를 얼마나 잘 지원하는지 평가하고 시스템의 트레이드오프를 식별하는 '골드 스탠다드' 방법론입니다 [6, 7]. 이 과정을 통해 도출된 아키텍처의 한계와 타협점들이 ADR에 문서화됩니다 [3, 8].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 추상적인 성능 논의가 아닌, "사용자가 10분 내에 2배로 증가할 때"와 같은 구체적인 '시나리오'를 바탕으로 아키텍처의 리스크와 트레이드오프를 체계적으로 분석하는 과정을 이해할 수 있습니다 [6, 7].

#### [관계 유형 B: 소프트웨어 품질 및 요구사항 기준]
- [[ISO/IEC 25010 (품질 모델)]]
  - 연결 이유: 아키텍처 대안을 비교하고 평가할 때 객관적인 척도와 기준점을 제공하는 국제 표준 품질 모델입니다 [9].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: ADR의 '근거(Reason)' 항목을 작성할 때 기능 적합성, 성능 효율성, 호환성 등 어떤 품질 속성에 가중치(우선순위)를 두어 결정을 내렸는지 객관적으로 파악하는 기준을 세울 수 있습니다 [9, 10].

### Deeper Research Questions
- ADR을 실무에 도입할 때, 빠르고 반복적인 배포가 이루어지는 애자일(Agile) 환경에서 발생할 수 있는 문서화 유지보수의 오버헤드는 어떻게 극복할 수 있는가?
- 비즈니스 요구사항이나 시스템 사용 패턴의 변화로 인해 초기 결정 맥락이 완전히 바뀌었을 때, 기존의 ADR 문서는 어떤 방식으로 업데이트되고 버전 관리가 이루어지는가?
- ATAM과 같은 시나리오 기반 분석을 통해 발견된 치명적인 한계점(Sensitivity points)은 ADR의 '위험 및 결과(Risks and consequences)' 섹션에 어떤 형식으로 정량화되어 기술되는가?
- 마이크로서비스(MSA)와 모듈형 모놀리스 사이에서 고민할 때, ADR의 대안(Alternatives) 섹션에서 가장 핵심적으로 비교되어야 할 기준은 무엇인가?
- 대규모 팀에서 새로운 구성원이 합류하거나 외부 감사가 이루어질 때, 방대한 ADR 이력을 효과적으로 탐색하고 시스템을 파악하게 만드는 베스트 프랙티스는 무엇인가?

### Practical Application Contexts
- **Implementation:** 개발자가 시스템을 구현할 때, 특정한 아키텍처 패턴이 왜 선택되었는지 ADR을 통해 이해함으로써 일관성 있는 코드와 솔루션을 작성하는 가이드라인으로 활용됩니다 [3, 11].
- **System Design:** 초기 아키텍처 설계 단계에서 직관이나 유행(트렌드)에 의존하지 않고, 식별된 요구사항과 프로토타입 검증 결과를 기반으로 내린 구조적 결정을 문서로 남겨 설계의 객관성을 확보합니다 [8, 12, 13].
- **Operation / Maintenance:** 운영 중 트래픽의 급증이나 새로운 시스템과의 통합 등 환경 변화가 발생했을 때, 기존 ADR을 리뷰하여 당시 아키텍처가 가진 한계와 제약사항을 파악하고 안전하게 시스템을 진화시킵니다 [3-5].
- **Learning Path:** 프로젝트에 새로 온보딩하는 구성원들이 시스템이 현재의 복잡한 구조를 갖게 된 역사적 맥락과 진화 과정을 단계별로 학습하는 훌륭한 교보재 역할을 합니다 [3, 4].
- **My Project Relevance:** 나의 프로젝트에서 기술 스택을 변경하거나 새로운 아키텍처 패턴을 도입할 때, 구두 합의나 휘발성 높은 이메일 대신 ADR 포맷에 맞춰 논의 과정을 명확히 남김으로써 미래의 기술 부채를 방지할 수 있습니다 [2, 3].

### Adjacent Topics
- [[프로토타이핑 및 개념 증명(PoC)]]
  - 확장 방향: 아키텍처 결정을 확정하고 ADR을 작성하기 전, 성능이나 기술적 실행 가능성 등 핵심 리스크를 조기에 실험하여 불확실성을 최소화하는 실무적 검증 기법으로 확장이 가능합니다 [14].
- [[의사결정 매트릭스(Decision Matrix)]]
  - 확장 방향: 여러 아키텍처 후보군을 정의된 품질 요구사항을 바탕으로 정량적 비교 및 평가하여, ADR 내 결정 근거(Reason)의 논리를 더욱 탄탄하게 뒷받침하는 방법론으로 연계할 수 있습니다 [15].

---
*Last updated: 2026-05-02*