[Docs] ADR(Architecture Decision Record), 팀의 기술 의사결정 과정을 기록하는 문서
To infinite curiosity and beyond
어느 날, 당신은 사이드 프로젝트로 ‘하지 말아야 할 일들을 정리하는 애플리케이션’을 만들고 싶다고 가정해봅시다.
프론트엔드 기술만 사용한다고 했을 때, 자연스레 이런 고민이 떠오릅니다.
- 웹으로 만든다면 Vanilla JS로 시작할까, 아니면 React, Vue, Svelte 중 하나를 쓸까?
- 스타일링은 CSS로 직접 작성할까, Tailwind나 styled-components를 도입할까?
- 상태 관리는 또 어떤 라이브러리를 선택해야 할까?
이처럼 우리는 프로젝트를 시작하거나, 진행하면서 마주치는 문제를 해결하기 위해 수많은 기술적 의사결정(Decision) 을 내리게 됩니다.
그런데 시간이 지나면 그 당시 어떤 이유로 그 결정을 내렸는지 잘 기억나지 않을 때가 많습니다.
예를 들어, 혼자 하던 프로젝트가 커져서 이제 둘이서 함께하게 되었다고 해봅시다.
새로 합류한 팀원이 묻습니다.
“왜 React만 쓴 건지 궁금해요. TypeScript도 같이 쓰면 좋지 않았을까요? 프로젝트 시작할 때 TypeScript를 사용하지 않은 이유가 있나요?”
그때, 정작 그 이유를 제대로 설명하지 못할 수도 있습니다. 이런 상황이 와도 당황하지 않도록 도와주는 문서가 있다면 어떨까요?
그게 바로 ADR(Architecture Decision Record) 입니다.
ADR은 프로젝트에서 내린 기술적 의사결정의 배경과 이유, 대안, 결과를 기록하는 문서입니다.
예를 들어,
- 기존 기술을 교체하려는 제안이 있을 때, 과거의 선택 배경을 근거로 토론할 수 있고,
- 새 팀원이 합류했을 때 프로젝트의 기술 선택 이유를 빠르게 이해할 수 있으며,
- 다른 팀(예: 프론트엔드와 백엔드)이 공통 기술을 선택할 때 결정 과정을 투명하게 공유할 수도 있습니다.
이 글은 『한 걸음 앞선 개발자가 지금 꼭 알아야 할 클린 코드』를 읽다가 ADR이라는 용어가 궁금해진 사람이 정리한 글입니다.
What: ADR(Architecture Decision Record)란?
ADR은 Architecture Decision Record 혹은 An Architectural Decision Record의 약자로, ‘프로젝트 내 기술·아키텍처 관련 중요한 의사결정을 기록하는 문서’를 의미합니다.
주로 특정 기술이나 설계를 왜, 어떤 근거로 선택했는지를 기록할 때 작성하며, 프로젝트의 방향성이나 기술 스택이 바뀌더라도 결정의 맥락(Context)을 잃지 않도록 돕습니다.
Michael Nygard가 말하는 애자일 환경에서의 ADR:
“애자일 프로젝트에서는 모든 결정을 한 번에 내리지도, 프로젝트 시작 시 모두 결정되지도 않습니다.
문서화를 반대하는 것이 아니라, 가치 없는 문서를 반대하는 것입니다.
팀이 스스로 활용할 수 있는 문서는 가치가 있으며, 작고 모듈화된 문서라면 업데이트될 가능성이 있습니다.
큰 문서는 절대 최신 상태를 유지하지 못하고, 대부분의 개발자는 읽지조차 않습니다.”
즉, ADR은 작고 독립적인 기록 단위로, 프로젝트 진행 중 언제든 참고할 수 있는 의사결정 맥락과 배경을 담은 문서라는 점에서 의미가 있습니다.
Nygard가 강조한 ADR 핵심 사항:
“프로젝트 진행 중 가장 추적하기 어려운 것은 과거 결정의 동기입니다.
새로운 팀원은 이유를 모른 채 그 결정을 맹목적으로 따르거나,
이해 없이 변경할 수밖에 없습니다. 이런 ‘맹목적 수용’과 ‘맹목적 변경’을 피하는 것이 중요합니다.”
ADR은 바로 이런 결정의 이유와 맥락을 기록하여, 팀이 잘못된 방향으로 움직이는 위험을 줄이고 과거 결정을 이해할 수 있도록 돕는 문서입니다.
Why: 쓰는 이유?
기억 보존
프로젝트에서 기술, 구조, 도구를 채택하거나 변경할 때의 이유를 기록하여, 나중에 왜 그렇게 결정했는지 쉽게 확인할 수 있습니다.
Michael Nygard가 지적했듯, 시간이 지나면 의사결정의 배경을 잊어버리는 것이 가장 큰 문제입니다. 이유를 모른 채 결정을 그대로 따르거나, 이유도 모르고 변경하는 상황을 방지할 수 있습니다.
온보딩 효율화
새로 합류한 팀원이 과거 결정의 맥락을 빠르게 이해하도록 돕습니다.
기록된 ADR을 통해 팀원은 “왜 이 기술을 선택했는가?”를 바로 파악할 수 있어, 혼란이나 반복 질문을 줄일 수 있습니다.
팀 간 소통
외부 팀이나 다른 개발자에게 결정 이유를 문서로 증명할 수 있습니다.
이는 기술 트레이드오프나 구조적 선택을 설명할 때 설득력을 높입니다.
변경 용이성
기술을 교체하거나 구조를 변경할 때, 과거 결정의 배경과 맥락을 참고해 합리적인 판단을 내릴 수 있습니다.
Nygard는 “결정의 이유와 영향을 문서화하면, 무턱대고 받아들이거나 무턱대고 바꾸는 위험을 줄일 수 있다”고 강조합니다.
When: 언제 쓰면 좋을까?
ADR을 모든 결정에 쓸 필요는 없습니다.
하지만 다음과 같은 순간이라면 ADR을 남겨두는 게 좋습니다:
- 새로운 프레임워크나 라이브러리를 도입할 때 (ex. React vs Vue, Redux vs Zustand)
- 아키텍처 구조를 변경할 때 (ex. Monolith → Microservice)
- 기술적 트레이드오프가 존재할 때 (ex. 성능 vs 유지보수성)
- 팀 내에서 “이 결정, 왜 이렇게 됐지?”라는 논의가 길게 이어졌던 결정이 있을 때
How: 어떻게 작성하면 좋을까?
ADR은 복잡할 필요가 없습니다. ‘상황-선택-이유-결과’만 정리해도 충분합니다.
중요한 건 문서 형식보다 “결정의 이유를 남기는 습관” 입니다.
// ADR_Template.md
# Title
## Date
## Context (상황)
## Decision (결정)
## Alternatives (대안)
## Status (현재 상태)
## Consequences (결과)회고: ADR 문서에 대해 공부하고나서
『한 걸음 앞선 개발자가 지금 꼭 알아야 할 클로드 코드』 책을 읽던 중, 프로젝트에 대해 작성하는 문서로 README와 함께 ADR이 소개되어 궁금해져서 개인적으로 알아보고 이렇게 글로 작성하게 되었습니다.
ADR은 새로운 기술을 도입하거나 아키텍처 구조를 변경하는 등, 프로젝트에 큰 변화가 있을 때 그 결정의 과정을 기록하는 문서라고 합니다. 빅테크 기업에서도 많이 사용하는 것으로 보여 흥미로웠습니다.
꼭 팀 프로젝트가 아니더라도 개인 프로젝트에서도 충분히 도움이 될 것 같다는 생각이 들었습니다.
개인적으로 프로젝트를 하다 보면 “내가 이 기술을 왜 선택했지?”라는 질문을 할 때가 종종 있는데, 정작 그 이유를 잘 떠올리지 못할 때가 많았습니다.
이번에 ADR 문서에 대해 알아보면서, 이런 고민을 줄이는 가장 좋은 방법이 ‘기록’이라는 걸 깨달았습니다.
앞으로는 개인 프로젝트라도 중요한 기술 결정을 내릴 때 ADR로 남겨보려 합니다.
APPENDIX
