TL;DR
- ADR(Architectural Decision Record)은 중요한 아키텍처 결정 하나의 맥락, 선택, 결과를 보존하는 문서다.
- 현재 시스템의 동작 방식은 코드와 설계 문서가 보여주고, ADR은 결정 당시 그 선택을 한 이유를 남긴다.
- AWS 방식에서는 수용된 ADR을 수정하지 않는다. 결정이 바뀌면 새 ADR을 만들고 기존 ADR을
Superseded로 연결해 결정의 역사를 보존한다.
Architecture Decision Record (ADR)
ADR의 정의
ADR은 팀이 내린 아키텍처 선택 가운데 중요한 것을 결정 시점의 맥락과 함께 기록하는 짧은 문서다. ADR 한 건에는 주요 결정 하나만 담는다.
기록의 뼈대는 결정이 필요했던 맥락(Context), 선택한 내용(Decision), 그 선택으로 얻는 것과 감수할 것(Consequences) 세 가지다. 구현 방법의 상세보다 결정의 이유를 남기는 데 무게를 둔다. 코드와 현행 설계 문서는 시스템이 지금 어떤 상태인지 보여주지만, 왜 그 상태가 되었는지는 남기지 못할 때가 많다. ADR은 그 이유를 보존한다.
| 구분 | 주로 답하는 질문 | 변경 원칙 |
|---|---|---|
| 현행 설계 문서 | 지금 시스템은 어떻게 구성·동작하는가? | 시스템 변경에 맞춰 갱신 |
| ADR | 결정 시점에 왜 이 선택을 했는가? | 결정 이력을 훼손하지 않도록 변경 관계를 보존 |
작성 대상
모든 코드 선택을 ADR로 남기지는 않는다. 시스템의 구조, 품질 속성, 장기 종속성, 공개 계약, 개발 방식에 영향을 주는 결정이 주요 대상이다.
- 아키텍처 패턴과 시스템 분할 방식
- 보안, 고가용성, 내결함성 같은 비기능 요구사항
- 컴포넌트 사이의 종속성과 결합 방식
- API와 외부에 공개되는 계약
- 라이브러리, 프레임워크, 도구, 주요 개발 프로세스
출처가 정한 기준은 아니지만, 실무에서는 되돌리기 비싸거나, 여러 팀·컴포넌트에 영향을 주거나, 나중에 "왜?"라는 질문이 반복될 선택을 ADR 후보로 삼을 만하다. 정확한 임계값은 팀이 합의해야 한다.
최소 구조
| 항목 | 기록할 내용 |
|---|---|
| Title | 한 눈에 식별할 수 있는 결정 제목 |
| Status | Proposed, Accepted, Rejected, Superseded 등 현재 상태 |
| Context | 문제, 요구사항, 제약, 관련 이해관계자 |
| Decision | 선택한 방향과 필요한 경우 핵심 근거 |
| Consequences | 긍정적 결과, 비용, 위험, 새로운 제약 |
| Alternatives considered | 검토했지만 선택하지 않은 대안과 이유 |
| Links | 대체하거나 대체된 ADR, 관련 이슈·PR·설계 문서 |
AWS가 제시하는 필수 핵심은 Context, Decision, Consequences다. Alternatives considered와 연결 링크는 판단 과정과 변경 추적을 강화하는 추가 항목이다.
상태와 결정 이력 보존
| 상태 | 의미 | 수정 정책 |
|---|---|---|
Proposed | 리뷰 중인 제안 | 보완 가능 |
Accepted | 팀이 채택한 결정 | AWS 방식에서 불변 |
Rejected | 이유를 남기고 채택하지 않은 제안 | AWS 방식에서 불변 |
Superseded | 새 ADR이 대체한 이전 결정 | 대체 ADR 링크를 보존 |
AWS 가이드는 Accepted와 Rejected ADR을 불변 문서로 취급한다. 수용된 결정이 바뀌면 새 ADR을 제안·리뷰·수용하고 기존 ADR을 Superseded로 연결한다.1 [[Michael Nygard의 2011년 원문]]도 번복된 결정을 삭제하지 않고 새 ADR을 참조하도록 제안한다.
변경 정책에는 날짜를 붙인 사후 정보를 기존 ADR에 덧붙이는 living document 방식도 있다. ADR 커뮤니티의 예제 저장소가 이 방식을 제안한다.2 두 방식 모두 과거의 맥락과 결정을 현재 관점으로 조용히 덮어쓰지 않는다는 원칙을 공유하고, 이렇게 쌓인 ADR 묶음이 결정 로그(decision log)가 된다. 조직은 엄격한 불변 방식과 날짜부 추가 방식 중 하나를 명시해야 한다.
운영 원칙
코드·설계 리뷰에서 ADR을 참조하는 원칙은 AWS 가이드에서 왔고, 나머지는 운영 경험에 기댄 권고다.
- 작성 자체보다 검토·승인·대체 흐름을 함께 정의한다.
- 코드 및 설계 리뷰에서 관련 ADR을 참조해 구현이 합의를 준수하는지 확인한다.
- 결정의 소유자와 이해관계자를 명시한다.
- ADR을 쉽게 검색할 수 있는 한 장소에 모아 결정 로그로 관리한다.
- 문서를 길게 만드는 것보다 제약과 트레이드오프를 누락하지 않는 것을 우선한다.
Connections
- 하네스 엔지니어링은 모델 바깥의 실행 환경을 설계하는 일이다 — ADR은 사람과 코딩 에이전트가 결정 맥락을 공유하게 하는 외부화된 하네스 산출물이다.
- 2026-06-01 - Matt Pocock - Skills For Real Engineers — ADR을 agent workflow가 참조하는 repo 문서의 한 종류로 다룬다.
Conflicts
- 확정 ADR의 변경 정책: AWS는 수용·거절된 ADR을 엄격히 불변으로 다룬다. ADR 커뮤니티 예제 저장소는 과거 기록을 덮어쓰지 않는 조건에서 날짜부 사후 정보 추가를 제안한다. 이 노트는 불변성을 결정 이력 보존을 구현하는 운영 정책 중 하나로 보고, ADR의 정의에는 넣지 않는다.
Open Questions
- 작성 오버헤드를 줄이면서 중요한 결정을 놓치지 않게 하는 ADR 작성 임계값은 어떻게 정할지?
- 코드 저장소와 위키 중 어느 쪽이 팀의 리뷰·검색·동기화 흐름에 맞는지?
Discussion
Comments
댓글은 승인 후 공개됩니다.