ADR (Architecture Decision Records)

ADR (Architecture Decision Records)

아키텍처 결정을 문서화하여 "왜 그렇게 했는지"를 기록하는 스킬입니다.

Core Principle

"결정의 '무엇'보다 '왜'가 중요하다." "6개월 후의 나도 알아볼 수 있게 기록한다."

ADR이 필요한 경우

ADR 폴더 구조

docs/
└── adr/
    ├── 0000-adr-template.md
    ├── 0001-use-nextjs-app-router.md
    ├── 0002-choose-postgresql-over-mongodb.md
    ├── 0003-implement-jwt-authentication.md
    └── README.md

ADR 템플릿

docs/​adr/​0000-adr-template.md

# [번호]. [결정 제목]

날짜: YYYY-MM-DD

## 상태

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## 컨텍스트

이 결정이 필요한 배경/문제 상황을 설명합니다.

- 현재 상황은 무엇인가?
- 어떤 문제를 해결하려 하는가?
- 어떤 제약 조건이 있는가?

## 결정

우리는 [X]를 선택했다.

### 고려한 대안들

1. **대안 A**: [설명]
   - 장점: ...
   - 단점: ...

2. **대안 B**: [설명]
   - 장점: ...
   - 단점: ...

3. **선택: 대안 C**: [설명]
   - 장점: ...
   - 단점: ...

## 결과

### 긍정적 영향
- ...

### 부정적 영향
- ...

### 리스크
- ...

## 참고 자료

- [링크1]
- [링크2]

실제 ADR 예시

docs/​adr/​0001-use-nextjs-app-router.md

# 1. Next.js App Router 사용

날짜: 2024-01-15

## 상태

Accepted

## 컨텍스트

새 프로젝트의 프론트엔드 프레임워크를 선택해야 한다.

요구사항:
- SEO 최적화 필요 (마케팅 페이지)
- 빠른 초기 로딩
- 팀의 React 경험 활용
- 서버 사이드 데이터 페칭

## 결정

**Next.js 14 App Router**를 선택한다.

### 고려한 대안들

1. **Next.js Pages Router**
   - 장점: 안정적, 레퍼런스 많음
   - 단점: 레거시화 진행 중, 새 기능 제한적

2. **Remix**
   - 장점: 뛰어난 데이터 로딩, 프로그레시브 향상
   - 단점: 팀 학습 비용, 상대적으로 작은 생태계

3. **선택: Next.js App Router**
   - 장점: React Server Components, 향상된 캐싱, Vercel 최적화
   - 단점: 일부 라이브러리 호환성 이슈, 학습 곡선

## 결과

### 긍정적 영향
- React Server Components로 번들 크기 감소
- 레이아웃 중첩으로 코드 재사용성 향상
- Vercel 배포 최적화

### 부정적 영향
- 일부 클라이언트 전용 라이브러리 사용 시 'use client' 필요
- Pages Router 경험자의 학습 필요

### 리스크
- App Router의 상대적인 신규성 (안정성 확인 필요)
- 일부 third-party 라이브러리 호환성

## 참고 자료

- [Next.js App Router Docs](https://nextjs.org/​docs/​app)
- [Server Components RFC](https://github.com/​reactjs/​rfcs/​pull/​188)

docs/​adr/​0002-choose-postgresql-over-mongodb.md

# 2. PostgreSQL 선택 (MongoDB 대신)

날짜: 2024-01-20

## 상태

Accepted

## 컨텍스트

프로젝트의 주 데이터베이스를 선택해야 한다.

데이터 특성:
- 사용자, 프로젝트, 미디어 간 관계 존재
- 트랜잭션 무결성 필요 (결제 연동 예정)
- 복잡한 쿼리 (필터링, 정렬, 집계)

## 결정

**PostgreSQL**을 선택한다.

### 고려한 대안들

1. **MongoDB**
   - 장점: 스키마 유연성, 수평 확장 용이
   - 단점: 복잡한 JOIN 어려움, 트랜잭션 제한

2. **선택: PostgreSQL**
   - 장점: ACID 보장, 강력한 JOIN, JSON 지원
   - 단점: 수평 확장 복잡, 스키마 변경 마이그레이션 필요

## 결과

### 긍정적 영향
- Prisma와 완벽한 호환
- 복잡한 관계 쿼리 최적화
- 결제 데이터 무결성 보장

### 부정적 영향
- 스키마 변경 시 마이그레이션 필요
- 초기 스키마 설계 중요

### 관련 결정
- Prisma ORM 사용 (ADR-003 예정)
- 마이그레이션 전략 수립 필요

ADR 작성 가이드

번호 체계

0001 ~ 0099: 기초 아키텍처 결정
0100 ~ 0199: 프론트엔드 관련
0200 ~ 0299: 백엔드 관련
0300 ~ 0399: 인프라/​DevOps 관련
0400 ~ 0499: 보안 관련

상태 흐름

Proposed → Accepted → [Deprecated | Superseded]

• Proposed: 검토 중
• Accepted: 승인되어 적용 중
• Deprecated: 더 이상 유효하지 않음
• Superseded by ADR-XXXX: 새 결정으로 대체됨

작성 팁

## 컨텍스트 작성 팁
- 배경 설명은 신규 팀원도 이해할 수 있게
- 제약 조건(시간, 예산, 기술 스택) 명시
- 문제의 긴급성/중요도 언급

## 결정 작성 팁
- 결정 내용을 한 문장으로 요약
- 대안들을 공정하게 비교
- 선택 이유를 명확히

## 결과 작성 팁
- 트레이드오프를 솔직하게
- 예상 리스크와 대응 방안
- 관련된 후속 결정 언급

ADR 도구

adr-tools (CLI)

# macOS
brew install adr-tools

# 초기화
adr init docs/​adr

# 새 ADR 생성
adr new "Use Next.js App Router"

# ADR 목록
adr list

# ADR 생성 (대체)
adr new -s 1 "Switch to Remix"

README.md (ADR 인덱스)

# Architecture Decision Records

| 번호 | 제목 | 상태 | 날짜 |
|------|------|------|------|
| [0001](0001-use-nextjs-app-router.md) | Next.js App Router 사용 | Accepted | 2024-01-15 |
| [0002](0002-choose-postgresql-over-mongodb.md) | PostgreSQL 선택 | Accepted | 2024-01-20 |
| [0003](0003-jwt-authentication.md) | JWT 인증 구현 | Accepted | 2024-01-25 |

Workflow

ADR 작성 시점

1. 기술 선택/변경 논의 시작
2. 대안 검토 및 비교
3. 팀 논의 (PR 또는 미팅)
4. 결정 후 ADR 작성
5. PR로 ADR 추가
6. 리뷰 후 머지

코드 리뷰에서

PR 리뷰어:
"이 라이브러리 선택에 대한 ADR이 있나요?"

작성자:
"ADR-0015에 근거 정리되어 있습니다."
또는
"ADR 추가하겠습니다."

Checklist

프로젝트 설정

• docs/​adr/ 폴더 생성
• ADR 템플릿 파일 추가
• README.md (인덱스) 생성
• 번호 체계 정의

ADR 작성 시

• 컨텍스트가 충분히 설명되었는가?
• 대안들이 공정하게 비교되었는가?
• 결정 이유가 명확한가?
• 트레이드오프가 솔직하게 기록되었는가?
• 관련 ADR/이슈가 링크되었는가?

References

• ADR GitHub
• Documenting Architecture Decisions (Michael Nygard)
• adr-tools