🏛️ ADR(Architecture Decision Record) 작성 가이드

“6개월 후의 나 또는 새로운 팀원이 ‘왜 이렇게 했지?‘라고 물을 때 답이 되는 문서”

---

💎 ADR의 핵심 가치

1. 지식 보존 & 온보딩

• 문제: 담당자 퇴사 시 “왜 이 기술을 썼는지”에 대한 맥락이 유실됨.
• 해결: 신규 입사자가 “왜 PostgreSQL인가요?”라고 물을 때 “ADR-003을 보세요”라고 답변 가능.
  • ADR-003 예시: 트랜잭션 무결성 필요 + 복잡한 JOIN 쿼리 → PostgreSQL 선택 (라이선스, 성능 고려)

2. 같은 논쟁 반복 방지

• 문제: 1월에 “REST vs GraphQL” 논쟁 후 REST 결정 → 6월에 또 같은 논쟁 반복.
• 해결: “이미 ADR-005에서 결정됨. 상황이 바뀌지 않았다면 재논의 불필요.”

3. 의사결정 품질 향상

• 문서를 작성하며 자연스럽게 **대안(Options)**과 **트레이드오프(Consequences)**를 깊게 고민하게 됨.
• “그냥 좋아서”가 아닌 “근거 있는” 선택을 유도.

4. 책임 분산 & 투명성

• 문제: 장애 발생 시 “누가 이렇게 정했어?”라는 비난 발생.
• 해결: “당시 상황(Context)에서는 이것이 최선이었다”는 기록이 있어 비난 대신 이해와 개선으로 이어짐.

5. 기술 부채 관리

• 예시: “지금은 바쁘니 모놀리스 유지(ADR-007)”
• 효과: 나중에 “왜 기술 부채가 생겼지?”가 아니라, “의도적으로 감수한 부채(Consequences)“임을 인지하고 상환 계획 수립 가능.

---

🚧 예상 병목 (Bottlenecks) & 해결책

1. 작성 비용 & 귀찮음 (🚨 가장 큰 문제)

• 현실: “코드 짜기도 바쁜데 문서까지?”
• 해결책: 5분 컷 경량 템플릿 사용.

  ## 제목: [결정 제목]
  ## 상태: 제안/승인
  ### 배경 (Context)
  - 2-3문장 요약
  ### 결정 (Decision)
  - 1문장 결론
  ### 이유 (Reason)
  - 핵심 이유 1, 2
  ### 영향 (Consequences)
  - 긍정/부정 영향

2. 작성 기준의 모호함

• 현실: “버튼 색상도 ADR 써야 하나요?”
• 해결책: 명확한 기준(Checklist) 수립.
  • ✅ 작성 대상: 되돌리기 어려운 결정, 팀 전체 영향, 비용/시간이 많이 드는 결정, DB/언어/프레임워크 선택.
  • ❌ 작성 불필요: 단순 UI 변경, 개인 코딩 스타일, 당연한 업계 표준.

3. 유지보수 부담 (Outdated)

• 현실: 문서는 “MySQL”인데 실제 코드는 “PostgreSQL”.
• 해결책: 상태(Status) 필드 적극 활용.
  • 제안됨(Proposed) → 승인됨(Accepted)
  • 기술 변경 시 기존 문서를 수정하는 게 아니라, 새 ADR 작성 후 기존 문서를 대체됨(Superseded) 처리.

4. 합의 과정의 오버헤드

• 현실: “리뷰 기다리다 지쳐요.”
• 해결책:
  • 기한 설정 (예: 3일 내 반대 없으면 자동 승인).
  • 최종 결정권자(Tech Lead) 명시.
  • 사소한 결정은 사후 공유(FYI)로 처리.

5. 검색 & 접근성

• 현실: “그 문서 어디 있더라?” (Slack, Notion, Wiki 산재)
• 해결책: 저장소 통일.
  • Notion Database 또는 Git Repository(docs/adr/)에 일원화.
  • 코드와 가까운 곳에 두는 것이 베스트.

---

🚀 실용적 도입 전략 (Phase)

Phase 1: 가볍게 시작

• 템플릿은 최소한으로 (제목, 배경, 결정, 이유).
• 한 달에 1-2개의 중요한 아키텍처 결정만 기록.
• 강제성보다는 권장 사항으로 시작.

Phase 2: 습관화

• PR 리뷰 시 “이 결정에 대한 ADR이 있나요?” 질문 던지기.
• 팀 회고 시간에 좋은 ADR 사례 공유.

Phase 3: 프로세스화

• 아키텍처 변경 PR에는 ADR 링크 필수 첨부.
• 신규 입사자 온보딩 커리큘럼에 “주요 ADR 읽기” 포함.
• 분기별 ADR 상태 리뷰 (폐기/대체 처리).

---

Supported by gemini-3.0-pro preview