LOTS-OResearch Notes
같은 주제#Software-Architecture 2

2026-07-19 - AWS - Architectural decision record process

읽기 노트2026.07.19↻ 09.2410 min

2026-07-19 - AWS - Architectural decision record process

Source

TL;DR

  • ADR은 소프트웨어 아키텍처의 중요한 선택 하나와 그 맥락·결과를 기록하는 문서이고, ADR이 쌓이면 프로젝트의 결정 로그가 된다.
  • 최소 항목은 Context, Decision, Consequences 세 가지이며, 구현 방법보다 결정의 이유에 초점을 둔다.
  • ADR은 Proposed에서 팀 리뷰를 거쳐 Accepted나 Rejected가 되고, 이후에는 불변 문서로 다룬다.
  • 결정을 바꾸려면 새 ADR을 같은 절차로 승인받고 기존 ADR을 Superseded로 바꾼다.
  • 어떤 결정이 "architecturally significant"한지, 저장소와 승인 권한을 어떻게 정할지는 팀이 따로 정해야 한다.

ADR과 결정 로그

ADR(Architectural Decision Record)은 팀이 만들려는 소프트웨어 아키텍처의 중요한 측면에 관해 내린 선택을 기록한다. ADR 한 건은 결정, 맥락, 결과를 담고, 상태를 가지므로 생명주기를 따른다.

ADR 프로세스의 산출물은 ADR 묶음이고, 이 묶음이 결정 로그(decision log)가 된다. 프로젝트 구성원은 각 ADR의 제목만 훑어 프로젝트 맥락을 파악하고, 구현과 설계 선택을 깊이 이해해야 할 때 본문을 읽는다.

작성 범위

프로젝트나 제품에 영향을 주는 아키텍처상 중요한 결정마다 ADR을 만든다. AWS는 Richards and Ford(2020)의 분류를 인용한다.

범주예
구조마이크로서비스 같은 아키텍처 패턴
비기능 요구사항보안, 고가용성, 내결함성
종속성컴포넌트 간 결합
인터페이스API와 공개된 계약
구축 기법라이브러리, 프레임워크, 도구, 프로세스

ADR 프로세스에 가장 흔히 들어오는 입력은 기능·비기능 요구사항이다.

ADR에 담을 내용

ADR이 필요하다고 판단되면 팀원 한 명이 프로젝트 공통 템플릿으로 작성을 시작한다. 템플릿 예시는 ADR GitHub organization에 있다. 템플릿을 쓰면 작성이 쉬워지고 필요한 정보가 빠지지 않는다.

최소한 결정의 맥락, 결정 자체, 프로젝트와 산출물에 미치는 결과를 적는다. AWS는 ADR 구조의 강점으로 구현 방식보다 결정 이유에 집중한다는 점을 꼽는다. 이유를 알면 다른 팀원이 결정을 받아들이기 쉽고, 결정 과정에 참여하지 않은 아키텍트가 나중에 결정을 뒤집는 일도 줄어든다.

수용 절차

모든 팀원이 ADR을 만들 수 있지만, 팀은 ADR 소유권을 정해야 한다. 작성자가 소유자(ADR owner)가 되어 내용을 유지하고 공유한다. 다른 팀원도 기여할 수 있으며, 수용 전에 내용이 바뀌면 소유자가 승인한다.

ADR creation, ownership, and adoption process

결정 식별부터 Accepted·Rejected 도달까지의 흐름도. 보완 과제가 나오면 담당자 배정과 수정을 거쳐 리뷰 회의로 되돌아가는 루프가 있다.

  1. 아키텍처 결정과 ADR 초안 소유자를 식별한다.
  2. 소유자가 Proposed 상태의 ADR을 작성한다. Proposed는 리뷰할 준비가 된 상태다.
  3. 소유자가 팀 리뷰 회의를 연다. 회의는 문서를 읽는 시간으로 시작하며 평균 10~15분이면 충분하다. 각자 읽으면서 불명확한 부분에 댓글과 질문을 남기고, 이후 소유자가 댓글을 하나씩 읽으며 팀과 논의한다.
  4. 보완 과제가 나오면 상태는 Proposed로 유지된다. 소유자가 과제를 정리하고 팀과 함께 담당자를 배정하며, 리뷰 일정을 다시 잡는 것도 소유자 책임이다.
  5. 거절하면 소유자가 같은 논의가 반복되지 않도록 거절 사유를 적고 Rejected로 바꾼다.
  6. 승인하면 소유자가 타임스탬프, 버전, 이해관계자 목록을 추가하고 Accepted로 바꾼다.

리뷰에서 ADR 활용

ADR과 결정 로그는 팀이 내린 모든 결정의 이력이다. 팀은 가능하면 코드 리뷰와 아키텍처 리뷰에서 ADR을 참조하고, 설계·구현 작업과 제품의 전략적 결정에서도 ADR을 확인한다.

Using an ADR to validate software component changes

변경이 구현되면 팀이 리뷰하고, ADR을 위반하면 ADR 링크를 단 댓글로 수정을 요청하며, 위반이 없으면 승인하는 흐름도.

모든 변경은 동료 리뷰를 거쳐 최소 한 명의 승인을 받는 것이 좋다. 리뷰어가 ADR을 위반하는 변경을 찾으면 작성자에게 ADR 링크와 함께 수정을 요청하고, 수정된 코드가 승인되면 메인 코드베이스에 병합된다.

변경 절차

팀은 수용하거나 거절한 ADR을 불변 문서로 다룬다. 기존 ADR을 바꾸려면 새 ADR을 만들어 같은 리뷰 절차로 승인받는다. 새 ADR이 승인되면 소유자가 기존 ADR의 상태를 Superseded로 바꾼다.

ADR update process

수용 절차와 같은 루프를 새 ADR에 적용하는 흐름도. 새 ADR이 Accepted가 되는 시점에 기존 ADR이 Superseded로 바뀌고, 새 ADR이 거절되면 기존 ADR은 그대로 남는다.

Relevance

ADR은 설계 결과만 남고 판단 근거가 사라지는 문제를 줄인다. 새로 합류한 사람과 코딩 에이전트는 ADR에서 현재 구조의 이유, 당시 제약, 감수한 트레이드오프를 복원할 수 있다. 다만 ADR이 현재 코드와 따로 놀면 기준으로서 힘을 잃으므로, 리뷰 흐름에서 참조되도록 운영해야 한다. 이 가이드가 코드 리뷰 흐름도까지 제시하는 이유도 여기에 있다.

Open Questions

  • 문서는 ADR 대상의 범주를 제시하지만, 어떤 조건을 만족해야 "architecturally significant"한 결정으로 볼지, 결정의 영향을 무엇으로 재서 작성 임계값을 정할지는 다루지 않는다.
  • ADR을 코드 저장소와 위키 중 어디에 둘지, 프로젝트 폴더 안에 둘지 별도 결정 로그로 모을지, 구현 변경과 어떻게 동기화할지는 조직 맥락에 달려 있다.
  • 코딩 에이전트가 구현 전에 ADR을 반드시 찾아보게 만드는 최소 하네스는 무엇인가?

Connections

Discussion

Comments

댓글은 승인 후 공개됩니다.

연결 그래프

백링크

1