[SWE] Architecture Decision Record(ADR)이란?

Architecture Decision Record(ADR)

소프트웨어 시스템을 설계하거나 개발할 때 발생하는 중요한 아키텍처 결정을 기록하는 문서로, 단순한 기록을 넘어 어떤 문제 상황에서, 어떤 대안을 고려하였고, 왜 특정 선택을 했는지를 명확히 남기는 것이 목적이다.

 

ADR을 작성하는 이유는 다음과 같다:

• 과거의 결정을 이해하고 추적할 수 있도록 돕는다.
• 새롭게 합류한 팀원들이 왜 그런 구조가 되었는지 빠르게 이해할 수 있다.
• 시스템이 변화하거나 성장할 때 이전 결정을 참고하거나 수정할 수 있게 한다.
• "그때 왜 이렇게 했지?"를 방지하여 팀의 지식 자산을 구축한다.

---

ADR 기본 구성

항목	설명
Title	결정의 간단한 제목
Status	현재 상태 (예: Proposed, Accepted, Deprecated)
Context	결정을 내리게 된 배경, 상황 설명
Decision	실제로 선택한 대안과 이유
Consequences	이 결정이 초래할 결과, 이점과 부작용

 

추가적으로 Alternatives (고려하였지만 채택하지 않은 대안들), Pros/Cons를 서술하는 경우도 많다.

---

ADR 작성 예시

예시 ①: API 설계 관련 ADR

항목	설명
Title	API 통식 방식 결정: REST API vs `gRPC`
Status	Accepted (승인됨)
Context	마이크로서비스 간 통신이 필요하며, 실시간 응답성과 이식성을 모두 고려해야 한다. REST는 광범위한 호환성을 가지지만, gRPC는 빠른 속도와 효율적인 통신을 제공한다.
Decision	REST API르 사용하기로 결정. 외부 시스템 연동, 개발자 경험(DevEx), 디버깅 용이성을 고려할 때 초기에는 REST가 적합하다 판단함. gRPC는 추후 내부 통신 최적화가 필요할 때 도입 가능성을 열어둔다.
Consequences	초기 개발 및 확장에 유리하지만, 고성능 통신이 필요한 경우 나중에 gRPC 전환 또는 병행 운영이 필요할 수 있다.

예시 ②: 인프라 선택 관련 ADR

항목	설명
Title	서버 인프라 선택: 온프레미스 vs 클라우드
Status	Accepted (승인됨)
Context	초기 투자 비용, 운영 부담, 확장성, 가용성 모두 고려해야 한다. 온프레미스는 초기 비용이 크고 운영 부담이 있으나, 장기적으로 비용 절감 가능성이 있다. 클라우드는 초기 비용은 낮지만, 장기적으로 사용료 누적 가능성이 있다.
Decision	AWS 클라우드 인프라를 선택. 초기 릴리즈와 빠른 서비스 확장을 고려할 때, 가용성과 민첩성이 높은 클라우드가 유리하다고 판단. 장기적으로는 비용 최적화를 위해 리소스 관리 방안을 마련할 계획.
Consequences	빠른 초기 출시가 가능하지만, 장기적인 비용 최적화 전략(Auto-Scaling, Reserved Instance 구매 등)을 반드시 수립해야 한다.

---

ADR 템플릿

실제로 현업에서 주로 사용하는 표준 ADR 템플릿으로 Markdown 형식으로 작성하는 경우가 많다.

# Title: (간단한 제목)

## Status (결정 상태: Proposed / Accepted / Deprecated / Superseded 등)

## Context (결정을 내리게 된 배경 설명. 문제 상황, 고려해야 할 요구사항, 제약 조건 등)

## Decision (최종적으로 선택한 대안과 그 이유 설명)

## Alternatives Considered (고려했던 다른 대안들과 각각의 장단점 간단히 기술)

## Consequences (이 결정이 가져올 긍정적/부정적 결과를 모두 기술)

## References (참고한 문서, 토론 링크, 외부 자료 등)

 

여러 버전 관리를 원한다면, 다음과 같이 관리가 이루어진다:

• `0001-use-rest-api.md`
• `0002-select-aws-cloud.md`
• `0003-introduce-ci-cd-pipeline.md`

-> 번호를 붙여 순서와 히스트리를 남긴다.

---

좋은 ADR 작성 팁

1. 한 문서에는 하나의 결정만 기록하기

• 하나의 ADR은 하나의 아키텍처 결정에만 집중합니다.
• 복잡하게 여러 결정을 섞지 않고, 결정을 분리해서 관리합니다.

2. 배경(Context)을 충분히 설명하기

• 당시 어떤 문제 상황과 요구사항이 있었는지 상세히 적습니다.
• "왜 이 결정을 고민하게 되었는가?"를 이해할 수 있어야 합니다.

3. 대안(Alternatives)도 반드시 적기

• 단순히 "A를 선택했다"가 아니라,
• "B, C 대안도 고려했지만 이런 이유로 A를 선택했다"고 기록해야 설득력이 높습니다.

4. 부정적인 영향(Consequence)도 숨기지 않기

• 선택한 결정이 가져올 단점, 리스크도 정직하게 기록합니다.
• 그래야 미래에 리스크를 인지하고 대처할 수 있습니다.

5. 짧고 명확하게 작성하기

• 너무 장황하게 적지 않고, 핵심 문장 위주로 명확하게 작성합니다.
• "누구든 5분 안에 읽고 이해할 수 있을 것"을 목표로 합니다.

6. Status 관리 철저히 하기

• `Proposed`, `Accepted`, `Deprecated`, `Superseded` 등 상태를 정확히 기록합니다.
• 나중에 "이거 아직 유효한가?"를 헷갈리지 않게 합니다.

---

ADR 도입 시 주의할 점

1. 무조건 처음부터 모든 결정을 ADR로 기록하려고 하지 말기

• 초기에는 "진짜 중요한 결정" 위주로만 ADR을 작성합니다.
• 너무 사소한 것까지 남기려 하면 지치고 번거롭게 느껴질 수 있습니다.

2. 문서화를 '목적'이 아니라 '수단'으로 생각하기

• ADR 자체를 쓰는 것이 목표가 아닙니다.
• "왜 이런 결정을 했는지 남기자"는 팀 커뮤니케이션 도구로 활용해야 합니다.

3. 팀원 모두가 쉽게 접근할 수 있도록 관리하기

• Git 저장소에 `docs/adr/` 폴더를 만들어 함께 관리하거나, 위키(Wiki)나 Notion 같은 협업 도구에 정리합니다.
• 버전 관리를 통해 언제든 추적 가능해야 합니다.

4. 정기적으로 리뷰 및 업데이트하기

• 오래된 ADR이 현재 시스템과 다르면 의미가 없습니다.
• 시스템이 바뀌면 ADR도 갱신하거나 Deprecated 상태로 표시합니다.

5. 강제 규칙이 아니라 팀 문화로 자리 잡게 하기

• "ADR을 안 쓰면 혼난다"가 아니라, "ADR을 쓰면 우리가 다 같이 더 좋은 개발할 수 있다"는 문화를 만들어야 합니다.

---

마지막으로

✨ ADR은 '결정'을 남기는 기록입니다. 시스템을 개발하는 것도 중요하지만, "왜 이렇게 되었는가"를 남기는 일은 미래의 자신과 동료에게 큰 선물이 됩니다.

 

 

관련 URL

• https://en.wikipedia.org/wiki/Architectural_decision

Architectural decision - Wikipedia

• https://github.com/joelparkerhenderson/architecture-decision-record

GitHub - joelparkerhenderson/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT