ADR-0001: ADR로 아키텍처 결정을 기록한다
이후 변경
- 2026-10-25: ADR 목록이
atelier/README.md의 한 절에서adr/폴더의 첫 페이지로 옮겨 갔다(DR 목록과 세션 기록 목록도 각자의 폴더로). 아래 줄들의 옛 절 링크는 지금은 ADR 목록과 DR 목록이다.- 2026-10-17: ADR에는 아키텍처 결정만 두기로 했다. 아키텍처가 아닌 결정(개발 순서, 조작과 모습, 이름 · 로고 · 라이선스) 열 개는 결정 기록 DR(
atelier/decisions/)로 옮기고 새 번호를 매겼다. 옮긴 ADR의 번호는 다시 쓰지 않는다 → DR-0001, DR 목록- 2026-10-12: ADR 폴더가
docs/03-adr/에서atelier/adr/로 바뀌었고(같은 날plan/폴더의 이름이atelier/가 되었다), 목록도atelier/README.md로 옮겼다(지금은 ADR 목록).docs/에는 최종 모습(요구사항, 설계, 명세)만 두고, 거기에 이르는 결정의 기록은 일하는 과정의 기록과 함께 두기로 했기 때문이다. 파일 이름과 번호는 그대로여서[[0001-…]]링크는 바뀌지 않는다.- 2026-10-10: 제안됨 상태의 ADR은 자유롭게 고친다. 승인된 ADR도 본문은 그대로 두되, 관련 내용이 달라지면 제목 바로 아래 “이후 변경” 콜아웃에 날짜·설명·링크를 덧붙인다 (이 콜아웃이 그 첫 예) → 템플릿
- 2026-10-09: ADR 폴더가
docs/adr/에서docs/03-adr/로 바뀌었다.
배경
요구사항 문서에 “결정이 필요한 사항” 목록으로 결정을 관리해 왔다. 결정이 늘어나면서 근거와 검토한 대안이 요구사항 문서를 채우게 되었고, 나중에 “왜 이렇게 했지?”를 추적하기 어려워졌다.
결정 기준
- 결정의 근거와 대안을 나중에도 찾을 수 있어야 한다.
- 요구사항 문서는 “무엇을”에만 집중해야 한다.
- Obsidian에서 읽고 편집하기 편해야 한다.
검토한 대안
요구사항 문서 안에 결정 섹션 유지
- 장점: 문서 하나로 끝남
- 단점: 문서가 커지고, 결정이 바뀌면 이전 근거가 사라짐
ADR (결정 1건 = 파일 1개)
- 장점: 결정마다 배경·대안·결과가 남음, 대체 이력 추적 가능
- 단점: 파일 수가 늘어남
결정
docs/adr/에 ADR을 MADR 형식을 줄인 템플릿으로 기록한다.
- 파일 이름:
NNNN-영어-슬러그.md, 본문은 한국어 - 상태: 제안됨 → 승인 → 대체됨 / 폐기
- 승인된 ADR은 고치지 않는다. 결정이 바뀌면 새 ADR을 쓰고
supersedes/superseded-by로 잇는다. - 목록은 ADR 목록에서 관리한다.
결과
- 좋아지는 점: 요구사항 문서가 간결해지고, 결정 이력이 남는다.
- 감수하는 점: 새 결정마다 파일을 만들고 목록을 갱신해야 한다.