ADR (Architecture Decision Record)

📌 Brief Summary

ADR(Architecture Decision Record)은 소프트웨어 프로젝트에서 내려진 아키텍처 결정과 그에 대한 기술적 및 비즈니스적 근거를 기록하는 단일 문서입니다 [1]. 이 문서는 시스템과 팀이 진화함에 따라 과거의 결정 배경이 잊혀지거나 오해받는 것을 방지합니다 [1, 2]. 접근 가능한 저장소에 관리되는 ADR은 의사결정의 이력을 투명하게 유지하여 아키텍처가 이해 가능하고 검증 가능하며 미래의 변화에 대비할 수 있도록 하는 핵심 자산입니다 [3, 4].

📖 Core 소스 Content

ADR의 목적과 가치 아키텍처 결정은 한 번 내려지면 되돌리기 어렵고, 시간이 흐를수록 그 배경과 이유가 잊혀지기 쉽습니다 [2]. 결정을 문서화하지 않으면 동일한 논의가 해결 없이 반복되는 안티패턴(anti-pattern)이 발생할 수 있습니다 [1]. ADR은 이러한 지식 증발을 막고, 새로운 팀원, 감사자, 이해관계자 및 미래 시스템의 진화를 위해 이해하기 쉬운 근거와 맥락을 제공하는 중요한 역할을 수행합니다 [2, 3].
표준 구성 요소 ADR은 결정을 내린 과정을 포괄적으로 담고 있으며 일반적으로 다음 항목들로 구성됩니다 [2, 3]:
- Context (맥락): 결정이 내려지게 된 초기 상황 및 기술적 배경.
- Decision (결정): 실제로 무엇이 결정되고 선택되었는가.
- Reason/Justification (이유/근거): 이 선택을 한 기술적 및 비즈니스적(비용, 출시 시간, 사용자 만족도 등) 이유 [1, 3].
- Alternatives (대안): 검토 후 거절된 옵션들과 그 거절 사유.
- Risks and consequences (위험과 결과): 이 결정이 단기 및 장기적으로 시스템에 미치는 의미와 위험 요소.
유지 및 관리 프로세스 ADR은 분산된 이메일 소통을 피하고, 위키(wiki)와 같이 중앙 집중화된 접근 가능한 저장소에 유지되어 단일 진실 공급원(single source of truth) 역할을 해야 합니다 [1]. 또한, 아키텍처는 고정된 것이 아니라 사용자 행동, 트래픽 부하, 팀 구조 등 컨텍스트가 변화함에 따라 함께 적응해야 합니다 [3, 5]. 이러한 변화가 발생할 때마다 아키텍처를 검토하고 그 경로를 단계별로 ADR에 갱신하거나 새롭게 기록해야 합니다 [3, 6].

⚖️ Trade-offs & Caveats

소스에 ADR 자체의 구조적인 제약 사항이나 부작용에 대한 상세한 정보가 부족합니다. 다만, 소스에서 확인되는 의사결정 및 문서화 과정에서의 한계와 관리적 책임(Trade-off)은 다음과 같습니다.

지속적인 유지보수 책임: 아키텍처와 ADR은 한 번 작성되고 끝나는 것이 아닙니다. 요구사항, 부하, 팀의 운영 현실 등 컨텍스트가 변경되면 아키텍처 역시 변경되어야 하며, 이에 맞춰 ADR 문서도 반드시 지속적으로 업데이트되어야 하는 관리 비용이 발생합니다 [5, 6].
비즈니스 가치 불일치 위험: ADR에 기록된 아키텍처 결정이 가시적인 비즈니스 가치를 제공하지 못하거나, 이해관계자의 비즈니스 목표와 어긋난 채로 확정되어 문서화될 경우, 시스템 구현에 악영향을 미치므로 해당 결정을 다시 전면적으로 재고해야 하는 리스크가 있습니다 [1].

🔗 Knowledge Connections

[의사결정 및 평가 방법론]

ATAM (Architecture Tradeoff Analysis Method)
- 연결 이유: 특정 아키텍처가 비즈니스 목표를 얼마나 잘 지원하는지 평가하고 트레이드오프와 위험 요소를 식별하는 방법론으로, 이 분석의 최종 선택 결과가 ADR에 문서화됩니다 [2, 7, 8].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 아키텍처 결정 과정에서 추상적인 목표 대신 구체적인 시나리오를 바탕으로 어떻게 타협점(Trade-off)을 찾고, 그 근거를 ADR의 '대안' 및 '위험' 항목에 객관적으로 채워 넣는지 이해할 수 있습니다.
Architecture Anti-patterns
- 연결 이유: 아키텍처 결정을 미루거나 문서화하지 않아 반복적인 논의만 발생하는 현상으로, ADR의 도입이 이 안티패턴을 해결하는 핵심 해결책입니다 [1].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 의사결정 기록의 부재가 프로젝트 개발 속도를 늦추고 분석 마비(analysis paralysis)를 일으키는 과정을 이해할 수 있습니다.

[시스템 유지보수 및 진화]

Software Architecture Erosion (소프트웨어 아키텍처 침식)
- 연결 이유: 시스템이 노후화되고 지식 증발(knowledge vaporization)이 발생하여 의도한 아키텍처와 실제 구현 사이에 격차가 생기는 현상이며, ADR은 이를 예방하는 수단이 됩니다 [2, 9, 10].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 문서화 누락이 장기적으로 시스템 성능 저하와 기술 부채(technical debt) 축적으로 이어지는 공학적 원리를 배울 수 있습니다.

Deeper Research Questions

컨텍스트(사용자 부하, 비즈니스 요구사항 등)가 변경되어 시스템 아키텍처를 수정해야 할 때, 기존 ADR을 폐기하고 새로 작성해야 하는가, 아니면 기존 ADR을 버전 관리하여 업데이트해야 하는가?
ATAM을 통한 시나리오 기반 분석 결과는 ADR의 '대안(Alternatives)' 및 '위험(Risks)' 섹션에 정량적으로 어떻게 기술되어야 하는가?
단순한 소프트웨어 설계(Design) 결정과 아키텍처(Architecture) 결정을 구분하여 ADR에 필수적으로 기록해야 하는 기준점이나 규모는 어떻게 정해지는가?
애자일(Agile) 환경에서 "마지막 책임 순간(last responsible moment)"에 결정을 내리는 전략과 ADR의 즉각적인 문서화 프로세스를 어떻게 마찰 없이 통합할 수 있는가?
분산된 마이크로서비스 아키텍처 환경에서 여러 팀이 각기 다른 서비스의 ADR을 작성할 때, 전체 시스템 관점에서의 무결성을 어떻게 유지할 수 있는가?

Practical Application Contexts

Implementation: 이메일이나 파편화된 메신저가 아닌 위키(Wiki) 등 중앙 집중화된 접근 가능한 저장소에 단일 진실 공급원(Single source of truth)으로 문서를 구축하고 관리해야 합니다 [1].
System Design: 품질 요구사항(확장성, 성능 등)에 기반하여 여러 아키텍처 패턴을 비교 평가한 뒤, 최종적으로 선택한 패턴의 근거와 감수한 타협점(Trade-off)을 ADR에 명시하여 설계의 타당성을 조직 내에 입증합니다 [2, 8, 11].
Operation / Maintenance: 시스템 운영 중 특정 장애에 대처하거나 리팩토링을 진행할 때, 과거에 특정 기술이나 제약 사항을 왜 수용했는지 감사자(Auditors)와 운영팀이 쉽게 추적하고 이해할 수 있도록 돕습니다 [3].
Learning Path: 팀에 새로 합류한 인원(New team members)이 시스템 구조가 현재와 같이 발전하게 된 역사적 맥락과 과거의 결정들을 빠르게 학습하기 위한 필수 온보딩 자료로 활용됩니다 [2, 3].
My Project Relevance: 프로젝트 중 유행하는 기술(Hype)이나 개인적 선호가 아닌, 측정 가능한 우선순위에 입각해 기술 결정을 내리도록 강제하고, 끝없는 논쟁을 방지하기 위한 핵심 규칙으로 적용할 수 있습니다 [1, 2, 12].

Adjacent Topics

Software Architecture Knowledge Management (소프트웨어 아키텍처 지식 관리)
- 확장 방향: 아키텍처 설계 과정에서 이해관계자의 머릿속에만 머물기 쉬운 암묵적 지식(tacit knowledge)을 발굴하고 소통하며 체계적으로 보존하는 포괄적인 관리 체계를 연구합니다 [13].
Agile Software Development (애자일 소프트웨어 개발)
- 확장 방향: 아키텍처의 초기 선행 설계(Big design up front)를 지양하면서도, 지속적으로 변화하는 요구사항 속에서 필수적인 기반 구조를 마련하고 의사결정을 적응시키는 방법을 탐구합니다 [14].

Last updated: 2026-05-02

8.8 KiB Raw Blame History