ADR 이란?
Architecture Decision Records (ADR) 는 소프트웨어 아키텍처와 관련된 중요한 결정 사항을 문서화하고 추적하는 방법으로 사용되는 기록 형식이다. ADR 에는 아키텍처의 주요 측면에 대한 의사 결정과 그 배경, 그리고 결정을 했던 이들의 이유 등을 문서화하여 기록한다.
개발 전 ADR 을 작성하면, 프로젝트 초기에 팀원들 간의 공통된 이해를 형성하고 효과적인 아키텍처 결정을 내릴 수 있게 된다. 이는 향후의 개발 과정에서 일관성을 유지하고 더 나은 솔루션을 발전시킬 수 있도록 도움을 준다.
ADR 작성은 당신을 위한 것이 아니라, 미래의 당신을 위한 것
ADR 은 내가 내린 결정에 대한 반성 과정이 아니라, 지금부터 6~12개월 후에 이 아키텍처를 결정했을 때의 마인드셋을 기억하는데 도움이 된다.
ADR 은 결정이 내려지는 시점을 포착하여 회의, 줌, 미팅, Slack, 코드에서 다뤄진 PoC 까지를 모두 포함한다.
1. 의사 결정 투명성 강화
ADR 은 팀원들에게 아키텍처 결정에 대한 투명성을 제공한다. 팀원들은 왜 특정 아키텍처 결정을 내렸는지, 어떤 대안이 고려되었는지에 대한 이해를 갖게 되어 협업과 의사소통을 강화할 수 있다.
2. 향후 변경에 대한 준비
ADR 은 향후에 시스템을 변경하거나 확장해야 할 때 유용하다. 왜 특정 아키텍처 선택이 이루어졌는지 문서로 남겨두면, 새로운 팀원이나 현재 팀원이 프로젝트에 참여하는동안 이전 결정을 이해하고 적절한 조치를 취할 수 있다.
3. 학습과 지식 공유
ADR 은 팀원 간 지식을 공유하고 향상시키는데 도움이 된다. 팀이 결정의 이유를 명확하게 이해하고 있으면, 팀원들은 더 나은 솔루션을 찾고 적용하는 방법에 대해 학습하게 된다.
4. 의사결정 기록
ADR 은 프로젝트의 아키텍처 결정에 대한 기록을 남긴다. 프로젝트의 발전과 함께 ADR 을 통해 어떤 결정이 있었는지 추적할 수 있다. 이는 향후 프로젝트에서의 비슷한 결정에 대한 참고 자료로 활용될 수 있다.
5. 토론과 검토를 촉진
ADR 작성은 아키텍처 결정에 대한 토론과 검토를 유도할 수 있다. 팀원들간 의견을 모으고 각자의 관점을 제시하면서 더 나은 결정을 내릴 수 있도록 돕는다.
ADR Template
ADR 형식은 정하기 나름이지만, 일반적으로 아래 항목들을 기재한다.
1. 제목(Title)
2. 상태(Status): 제안(Proposed), 채택됨(Accepted), 거부됨(Rejected), 대체됨(Superseded)
3. 컨텍스트(Context): 해결하고자 하는 문제를 정의한다.
4. 결정(Decision): 제안하고자 하는 내용 및 해당 결정의 이유에 대해 설명한다.
5. 결과(Consequences): 결정을 통해 사용자가 받는 영향에 대해 정의한다.
Sample
- https://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/architectural-decision-records/appendix.html
- https://github.com/alphagov/govuk-aws/tree/main/docs/architecture/decisions
좀 더 자세하게 작성해보기
0. 요약
저자 (Author)
- 구성원 1
리뷰어 (Reviewer)
- 구성원 1
- 구성원 2
요약
⚠️ 세 줄 요약
1. 문제 정의 (Problem Statement / As-Is)
배경 (Background)
⚠️ 현재 상황을 설명하고 개발자로써 어떻게 해결할 것인가?
필수 조건 (Requirements)
⚠️ 개발한 시스템의 성공 조건
목표 (Goals)
- 목표1
- 목표2
목표가 아닌 것 (Non-Golas)
⚠️ 독자가 목표를 헷갈려 하는 경우를 대비해 목표가 아닌 것을 명시
평가 (Measurement)
⚠️ 시스템의 성공과 실패를 어떻게 평가할 것인가?
실험 지표(Metrics) 일 수도 있고, 개발완료/실패 혹은 일정 내 수행 등 Binary 일 수도 있다.
예상 트래픽 (Expected Traffic)
⚠️ 해당 기능의 타겟 유저수나 예상되는 인입 트래픽 기술
2. 해결 방안 (Proposed Solution / To-Be)
설계 (Architecture)
⚠️
- 이 프로젝트가 구현되는 전반적인 설계를 설명
- 세부 설계가 설명되어야 하며, 설계가 여러 프론트/백엔드 혹은 high/low 레벨로 나뉠 수 있다면 섹션을 나누고 명확하게 설명 (독자가 문서만 보고 온전히 이해할 수 있어야 함)
- 비쥬얼 다이어그램 첨부 필수
구현 (Implementation)
스택 (Tech Stack Choices)
⚠️ 어떤 언어, 오픈소스, 솔루션을 어느 코드베이스에서 사용할지, 왜 그렇게 선택했는지 간략하게 설명
테스트 (Testing)
- Integration Tests
- Unit Tests
- Manual QA Tests
서버 간 호출 flow (API Call flow)
⚠️ 해당 기능을 호출하는 다른 서비스들의 API Endpoint 와 서버 간 다이어그램을 그리고 첨부
코드리뷰 (Reviews)
⚠️ 누가 이 프로젝트의 코드를 리뷰할 것인가?
서비스 수준 협약 (SLA)
⚠️ 이 시스템/서비스의 SLA 가 무엇인가?
- 응답시간 혹은 가용시간 으로 측정 가능
- uptime 99.99%
- latency avg: 500ms, p95 - 2000ms
경보/모니터링 (Alerts/Monitoring)
⚠️ 시스템/서비스가 fail 했을 경우 어떻게 알람을 받고, 어떻게 대응할 것인가?
슬랙 모니터링 채널의 exception 이름 혹은 grafana pannel alert 등 어떤 알람인지 구체적으로 구분 가능하도록 작성
보안 (Security)
⚠️
- 유저의 개인정보를 노출하는가?
- API 가 FQDN 이 아닌 외부 도메인을 통해 호출 가능한가?
- 리소스 자원의 소유권 검사가 적절하게 이뤄졌는가?
3. 런치 (Rollout)
계획 (Plan)
⚠️
- 어떻게 이 시스템/서비스를 적용할 것인가?
- 배포시 즉시 적용되는가?
- 어떤 실험/마이그레이션/테스팅이 필요한가?
- Feature 들을 단계적으로 배포하는가?
- 실험 혹은 Feature Flag 가 지정되어 있는가?
- 실험 혹은 Feature Flag 이름은 무엇인가?
배포 (Deploy)
⚠️ 어떻게 배포할 것인가?
온콜 (Runbooks/Oncall)
⚠️ 온콜 엔지니어는 누구인가?
- 상황 발생시 문의/대응 하는 인력을 의미
- 온콜 시 대응 가능한 방안이 있다면 구체적으로 함께 기술
4. 타임라인 (Timeline)
로드맵 (Roadmap/Milestones)
⚠️ 단계적 마일스톤을 항목으로 표기
5. 대안 (Alternatives Considered)
⚠️ 구현을 위해 생각했던 대안 명시
6. 참조 (Additional Context)
⚠️ 참조한 자료들, 동료와의 대화들 등 기재
References
'기타' 카테고리의 다른 글
| 네이버 검색에서 티스토리 노출하기 (2) | 2023.11.19 |
|---|---|
| [Copilot] 이제 코딩도 AI (0) | 2021.07.20 |
| [서비스] Airbyte 도입기 (0) | 2021.04.22 |
