문서 흔적의 힘: Architecture Decision Records (ADRs)
Source: Dev.to
지식 작업—소프트웨어 아키텍처와 엔지니어링—의 궁극적인 결과물은 의사 결정입니다.
형태에 관계없이, 핵심 결정 뒤의 사고 과정을 기록하는 것은 다음을 위해 필수적입니다:
- 결정이 합의되기 전, 중, 후에 명확성을 유지하기.
- 사후 편견을 방지하기.
- 미래의 자신과 다른 사람들이 결정이 내려진 환경을 이해하도록 돕기.
이 글에서는 제가 **Architecture Decision Records (ADRs)**에 대해 배우고 있는 내용과 이를 소프트웨어 및 데이터 프로젝트에 적용하는 방법을 공유하겠습니다.
ADR이란 무엇인가?
Architecture Decision Records는 프로젝트 수명 주기 동안 이루어지는 중요한 아키텍처 결정에 대한 일종의 기록입니다. 앞으로는 이를 간단히 ADRs라고 부르겠습니다.
소프트웨어 및 데이터 엔지니어로 일하면서 드물게 ADR을 접해봤습니다. 제가 참여한 프로젝트에서는 문서화가 다양한 형태를 띠었습니다: 방치된 Notion 페이지, 다이어그램, 내용이 거의 없는 텍스트 파일, 혹은—때때로—전혀 문서가 없는 경우도 있었습니다. 결정이 바뀔 때, ADR은 Proposed, Accepted, Rejected, Superseded와 같은 명시적인 상태를 도입함으로써 이러한 변화를 추적하는 데 도움을 줍니다.
왜 신경 써야 할까요?
아키텍처 결정은 조직이 내리는 가장 비용이 많이 드는 선택 중 하나입니다. 이는 다음에 영향을 미칩니다:
- 새로운 기능을 추가하는 것이 얼마나 쉬운지.
- 변화하는 비즈니스 요구에 직면했을 때 시스템의 회복력과 유연성.
이러한 결정을 엄격하게 검토하고 정당화하며—필요한 시간 내에 수행하는 것이—중요해집니다. 또한, ADR 프레임워크는 다른 많은 분야와 의사결정 프로세스에 적용될 수 있습니다.
Source: …
어떻게 문서화할 내용을 정하나요?
모든 결정이 문서화될 필요는 없습니다; 관리 비용이 악몽이 될 수 있기 때문입니다. Michael Nygard는 아키텍처적으로 중요한 결정을 다음과 같은 영향을 미치는 것으로 설명합니다:
- 구조와 구축 기술.
- 비기능적 특성(예: 확장성, 보안).
- 의존성 및 인터페이스.
스스로에게 물어보세요:
이 결정은 되돌릴 수 있는가? 그리고 되돌리는 비용은 얼마인가?
Olaf Zimmermann은 그의 블로그 게시물에서 의사결정 기준에 대해 자세히 다룹니다.
가벼운 ADRs: 설정하기
저는 관리 오버헤드 문제를 가장 먼저 제기하겠습니다—문서화 습관을 처음 시작하는 데 속도를 내는 것 자체가 이미 어렵습니다. 가벼운 ADRs는 워크플로우에 크게 영향을 주지 않으면서 문서화의 이점을 제공하는 형식을 제공합니다. 또한 adr-tools GitHub repo와 같이 ADR을 관리하는 도구도 있습니다.
내 프로젝트에서는 각 결정마다 하나의 Markdown 문서를 포함하는 /adr 폴더를 간단히 추가합니다, 예시:
/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은 보관되지만 여전히 접근 가능합니다.
이 간단한 워크플로우를 따름으로써 팀은 왜 특정 아키텍처 선택을 했는지, 그리고 시간이 지나면서 어떻게 진화했는지를 명확하고 검색 가능한 기록으로 유지할 수 있습니다.
문서화 즐겁게 하세요!
Conclusions
Documentation is a habit, and it’s especially important given the constantly changing landscape of tools and technologies that teams adopt. Although many organizational considerations that go into documentation frameworks haven’t been covered here, the rigor required to fill in and socialize ADRs alone should help stave off some of the pitfalls that come with insufficient documentation and decision silos.
Where ADRs live is just as important as writing them; it affects how they are versioned and maintained, which is, in my opinion, the biggest battle with technical documentation.
결론
문서화는 습관이며, 팀이 채택하는 도구와 기술이 끊임없이 변화하는 환경을 고려할 때 특히 중요합니다. 여기서는 문서화 프레임워크에 들어가는 많은 조직적 고려사항들을 다루지 않았지만, ADR을 채우고 공유하는 데 필요한 엄격함만으로도 불충분한 문서화와 의사결정 사일로에서 오는 몇몇 함정을 방지하는 데 도움이 될 것입니다.
ADR이 위치하는 곳은 작성하는 것만큼 중요합니다; 이는 ADR이 버전 관리되고 유지되는 방식에 영향을 미치며, 제 생각에 기술 문서화와의 가장 큰 전투입니다.