ADR
ADR(Architecture Decision Record, 아키텍처 결정 기록)은 소프트웨어 시스템을 설계하는 과정에서 내려진 중요한 아키텍처 결정과 그 배경, 근거를 짧은 문서로 남기는 기록 방식이다. 결정 하나마다 하나의 문서를 작성하며, 이러한 문서들이 모여 프로젝트의 결정 로그(decision log)를 구성한다.
코드 저장소 내 doc/adr 같은 경로에 마크다운 형식으로 저장하는 것이 일반적이며, 코드와 함께 버전 관리되기 때문에 시간이 지나도 왜 시스템이 지금과 같은 구조로 만들어졌는지 추적할 수 있다는 것이 핵심 가치다.
주요 특징
- 단일 결정 단위 기록: 하나의 ADR은 하나의 아키텍처 결정만을 다룸.
- 맥락·결정·결과 구조: 배경(Context), 결정(Decision), 결과(Consequences)로 구성됨.
- append-only 로그 방식: 기존 기록을 수정하지 않고, 변경 시 새 기록으로 이전 문서를 대체함.
- 코드와 함께 버전 관리: 소스 저장소에 마크다운으로 저장되어 코드 변경 이력과 함께 추적됨.
- 경량 문서 형식: 표준화된 템플릿을 사용해 짧고 빠르게 작성할 수 있음.
장점
- 의사결정 배경 보존: 시간이 지나도 왜 그런 구조를 선택했는지 팀원 모두가 이해할 수 있음.
- 온보딩 효율화: 신규 팀원이 과거 결정의 맥락을 빠르게 파악하는 데 도움을 줌.
- 중복 논의 방지: 이미 검토했던 대안과 그 이유가 기록되어 있어 같은 논쟁의 반복을 줄임.
- 사고의 명료화: 결정을 문서화하는 과정 자체가 팀의 사고를 정리하는 데 기여함.
- 감사·컴플라이언스 대응: 아키텍처 변경 이력을 명확히 추적할 수 있어 규정 준수에 유리함.
관련 용어
- Decision Log: 프로젝트에서 작성된 모든 ADR의 모음.
- 아키텍처 결정(Architectural Decision, AD): 요구사항이나 목표를 충족하기 위해 내려진 소프트웨어 설계상의 선택.
- RFC(Request for Comments): 기술적 제안을 공유하고 논의하기 위한 문서 형식으로, ADR과 함께 활용되기도 함.
- 마크다운(Markdown): ADR 작성에 흔히 사용되는 경량 마크업 언어.
- Well-Architected Framework: 클라우드 아키텍처 설계 원칙을 제공하며 ADR 작성을 권장하는 대표적 프레임워크.
주요 솔루션 및 사용 사례
- 주요 솔루션
- adr-tools: 커맨드라인에서 ADR을 생성하고 관리할 수 있는 오픈소스 도구.
- Log4brains: ADR을 웹사이트 형태로 시각화하고 검색할 수 있게 해주는 도구.
- MADR(Markdown Any Decision Records): 표준화된 마크다운 템플릿을 제공하는 ADR 포맷.
- GitHub / GitLab: 코드 저장소 내에서 ADR 문서를 코드와 함께 버전 관리하는 플랫폼.
- AI 기반 ADR 생성 도구: 코드 변경 사항을 분석해 초안 ADR을 자동 생성하는 신규 도구들.
- 사용 사례
- 마이크로서비스 전환 결정 기록: 모놀리식에서 마이크로서비스로 전환한 이유와 대안을 문서화.
- 클라우드 벤더 선택 근거 정리: 특정 클라우드 제공업체를 선택한 배경과 비교 검토 내용을 기록.
- 신규 팀원 온보딩 자료 활용: 과거 결정 기록을 온보딩 문서로 제공해 학습 곡선을 단축.
- 기술 부채 논의 근거 마련: 과거 결정의 트레이드오프를 재검토해 리팩터링 여부를 판단.
- 감사 대응 문서화: 아키텍처 변경 이력을 감사 요청 시 근거 자료로 제출.
