문서 기록의 힘: Architecture Decision Records (ADRs)
Source: Dev.to
지식 작업—소프트웨어 아키텍처와 엔지니어링—의 궁극적인 산출물은 의사 결정이다.
형태가 어떻든, 핵심 결정 뒤에 있는 사고 과정을 기록하는 것은 다음을 위해 필수적이다:
- 결정이 합의되기 전, 중, 후에 명확성을 유지하기 위해.
- 사후 편향을 방지하기 위해.
- 미래의 자신과 다른 사람들이 결정이 내려진 환경을 이해하도록 돕기 위해.
이 글에서는 **Architecture Decision Records (ADRs)**와 이를 소프트웨어 및 데이터 프로젝트에 적용하는 방법에 대해 제가 배운 내용을 공유하고자 한다.
ADR이란 무엇인가?
Architecture Decision Records는 프로젝트 수명 주기 동안 내린 중요한 아키텍처 결정에 대한 일종의 기록입니다. 앞으로는 간단히 ADRs라고 부르겠습니다.
소프트웨어 및 데이터 엔지니어로서 여러 해 동안 저는 ADRs를 드물게 접했습니다. 제가 참여한 프로젝트에서는 문서화가 다양한 형태를 띠었습니다: 버려진 Notion 페이지, 다이어그램, 간략히 적힌 텍스트 파일, 혹은—때때로—아예 문서가 없기도 했습니다. 결정이 바뀔 때, ADRs는 Proposed, Accepted, Rejected, Superseded와 같은 명시적인 상태를 도입함으로써 이러한 변화를 추적하는 데 도움을 줍니다.
왜 신경 써야 할까요?
아키텍처 결정은 조직이 내리는 가장 비용이 많이 드는 선택 중 하나입니다. 이는 다음에 영향을 미칩니다:
- 새로운 기능을 추가하는 것이 얼마나 쉬운가.
- 변화하는 비즈니스 요구에 직면했을 때 시스템의 회복력과 유연성.
이러한 결정을 엄밀히 검토하고 정당화하는 것이—필요한 시간 내에 수행하는 것이—중요해집니다. 또한 ADR 프레임워크는 다른 많은 분야와 의사결정 프로세스에 적용될 수 있습니다.
어떤 것을 문서화해야 할지 어떻게 알 수 있나요?
모든 결정이 문서화될 필요는 없습니다; 관리 부담이 악몽이 될 수 있습니다. Michael Nygard는 아키텍처적으로 중요한 결정들을 다음에 영향을 미치는 것으로 설명합니다:
- 구조 및 구현 기법.
- 비기능적 특성(예: 확장성, 보안).
- 의존성 및 인터페이스.
스스로에게 물어보세요:
이 결정은 되돌릴 수 있는가, 그리고 되돌리는 비용은 얼마인가?
Olaf Zimmermann은 의사결정 기준에 관한 그의 블로그 게시물에서 이 주제를 자세히 다룹니다.
경량 ADR: 설정하기
문서화 습관을 처음 시작하는 것이 이미 충분히 어려운 관리 오버헤드 문제를 제가 가장 먼저 제기하겠습니다. 경량 ADR은 워크플로우에 큰 영향을 주지 않으면서도 문서화의 이점을 제공하는 형식을 제공합니다. 또한 adr-tools GitHub repo와 같이 ADR을 관리하는 도구도 있습니다.
내 프로젝트에서는 /adr 폴더를 만들고 결정마다 하나의 Markdown 문서를 넣습니다. 예시:
/adr
│ ADR 001 - Postgres for Operational Database.md
│ ADR 002 - Microservice Architecture for Orders Module.md
│ …다이어그램을 폴더에 직접 넣고 모든 것을 소스 컨트롤에 커밋하여 문서 버전이 코드와 일치하도록 합니다. 결정이 바뀔 경우, 기존 ADR을 편집하지 않고 새 ADR를 만들고, 기존 ADR을 Superseded(대체됨)로 표시한 뒤 새 ADR에 링크합니다.
Source:
ADR의 라이프사이클
이 문서들의 라이프사이클은 팀 역학과 이해관계자의 책임에 따라 달라집니다. 언제나 ADR을 전달하고, 게시하며, 유지 관리할 책임이 있는 주요 연락처(개인 또는 팀)가 존재합니다—즉, ADR을 한 상태에서 다음 상태로 이동시키는 역할을 합니다.
전형적인 상태 다이어그램(원본 출처에서 변형):
Proposed → Accepted → Superseded
↘
Rejected- Proposed – 새로운 결정이 초안 단계에 있습니다.
- Accepted – 결정이 승인되어 현재 아키텍처가 됩니다.
- Rejected – 제안이 거부되었으며, ADR은 역사적 맥락을 위해 남겨둡니다.
- Superseded – 이후의 ADR이 이를 대체합니다; 기존 ADR은 보관되지만 여전히 접근 가능합니다.
이 간단한 워크플로우를 따름으로써 팀은 왜 특정 아키텍처 선택을 했는지, 그리고 시간이 지나면서 어떻게 진화했는지에 대한 명확하고 검색 가능한 기록을 유지할 수 있습니다.
문서 작업을 즐기세요!
결론
문서화는 습관이며, 팀이 채택하는 도구와 기술이 끊임없이 변화하는 상황에서 특히 중요합니다. 문서화 프레임워크에 들어가는 많은 조직적 고려 사항이 여기서는 다루어지지 않았지만, ADR을 작성하고 공유하는 데 필요한 엄격함만으로도 부실한 문서화와 의사결정 사일로에서 발생하는 몇몇 함정을 방지하는 데 도움이 될 것입니다.
ADRs가 저장되는 위치는 그것을 작성하는 것만큼 중요합니다; 이는 ADR이 버전 관리되고 유지되는 방식에 영향을 미치며, 제 생각에 이는 기술 documentation과의 가장 큰 전쟁입니다.