DR-0001: 아키텍처가 아닌 결정은 ADR과 나눠 결정 기록(DR)으로 적는다
이후 변경
- 2026-10-18: 이때 범위 밖이던
docs/02-ux-design/05-ux-decisions(작은 UX 결정)도atelier/decisions/의 UX 결정 모음으로 옮겼다. 결정의 원본은 모두atelier/에 있다 → DR-0012
배경
2026-10-07부터 결정을 ADR(아키텍처 결정 기록)로 적어 왔다 → ADR-0001. 그런데 28개 가운데 열 개는 아키텍처가 아니었다: 개발 순서, 시각 스타일, 강조 영역의 테두리, Vim 키, 제품 이름, 로고, 라이선스 셋, 저장소 이름.
메인테이너가 inbox에 물었다(2026-10-17): “ADR은 아키텍처 결정을 기록한 것인데, ‘편집 모델과 조작’, ‘모습’, ‘이름 · 로고 · 라이선스’는 아키텍처가 아닌데도 ADR로 작업했습니다. 이게 적절한지 의문스럽습니다. 다른 엔지니어들은 어떻게 하고 있나요?”
다른 프로젝트들도 같은 고민을 했다. 널리 쓰이는 ADR 템플릿 MADR은 3.0판(2022)에서 이름을 “Markdown Any Decision Records”로 넓혔다가, 4.0판(2024)에서 “Architectural”로 되돌렸다. 다른 결정에도 쓸 수 있지만 중심은 아키텍처라는 입장이다.
결정 기준
- ADR 목록만 보고 이 제품의 아키텍처를 알 수 있다
- 아키텍처가 아닌 결정도 까닭과 검토한 대안이 남는다
- 새 결정을 어디에 적을지 망설이지 않는다
검토한 대안
그림은 시안 M21에 있다: https://claude.ai/artifact/6rrnQ2NBf5kWYXkJkrC6kM (저장소의 사본 journal/assets/2026-10-17-decision-records-study.html)
대안 A: ADR 하나에 그대로, 목록만 나눈다
- 장점: 고칠 것이 없다
- 단점: 이름과 내용이 어긋난 채 남는다
대안 B: 결정 기록(DR) 줄을 하나 더 두고, 옮기는 것에 새 번호를 매긴다
- 장점: ADR은 아키텍처만, DR은 그 밖의 결정. 두 줄 모두 번호가 빈틈없이 이어진다
- 단점: 옮기는 열 개를 가리키던 링크와 번호를 고쳐야 한다(스크립트로)
대안 C: 제품 결정과 프로젝트 결정을 다시 나눠 줄을 셋으로
- 단점: 저장소 이름이나 문자 로고처럼 양쪽에 걸친 것의 자리를 정하기 어렵다
대안 D: 번호와 파일 이름을 그대로 두고 폴더만 옮긴다
- 장점: 링크가 끊기지 않는다
- 단점: 두 줄이 한 번호 공간을 나눠 써서 새 번호를 두 폴더에서 찾아야 하고, “ADR-0019”라는 글자가 남는다
결정
대안 B. 메인테이너: “M21: 모두 추천 수용” (2026-10-17).
- ADR(
atelier/adr/)에는 코드의 구조, 모델, 파일 형식, 기술 선택에 관한 결정만 둔다. - 그 밖의 결정은 결정 기록 DR(
atelier/decisions/, 파일 이름dr-NNNN-…)에 ADR과 같은 형식으로 적는다. 상태, “이후 변경”, 대체의 규칙도 같다. - 사용자에게도 보이면서 구조도 정하는 것은 구조를 정한 쪽이 결정의 중심이면 ADR로 둔다. 그래서 0006(확장자)과 0008(연속 범위 선택)은 ADR에 남기고, 0013(시각 스타일)과 0025(Vim 키)는 DR로 옮겼다. 0013의 “색은 표로 렌더러에 넘긴다”와 0025의 “키와 명령의 짝은 표 하나”는 아키텍처 문서(6. 공통 관심사)에 적혀 있다.
- 옮긴 열 개는 옛 번호 순서대로 DR-0002부터 번호를 매긴다. ADR 쪽의 빈 번호는 다시 쓰지 않는다.
| 옛 번호 | 새 번호 | 제목 |
|---|---|---|
| ADR-0011 | DR-0002 | 개발 순서 |
| ADR-0013 | DR-0003 | 기본 시각 스타일 |
| ADR-0015 | DR-0004 | 강조 영역의 테두리 (폐기) |
| ADR-0019 | DR-0005 | 제품 이름 |
| ADR-0020 | DR-0006 | 로고 |
| ADR-0023 | DR-0007 | Apache-2.0 |
| ADR-0024 | DR-0008 | 라이선스의 범위 (대체됨) |
| ADR-0025 | DR-0009 | Vim 키 |
| ADR-0027 | DR-0010 | 시안 페이지는 CC BY 4.0 |
| ADR-0028 | DR-0011 | 저장소 이름 |
결과
- 좋아지는 점: ADR 목록이 아키텍처만 보여 준다. 저장소 방문자가 아키텍처 결정을 찾기 쉽다.
- 감수하는 점: 세션 기록과
journal/, 시안 페이지(HTML)에 글자로 적힌 옛 번호(“ADR-0019”)는 그때의 기록이라 고치지 않았다. 그 기록들의 링크는 새 파일로 이어진다. 옛 번호로 찾으려면 위 표나 각 DR의 “이후 변경”을 본다. - 옮긴 기록의 본문은 고치지 않았다. 번호와 링크만 새 것으로 바꿨다. 남은 ADR의 본문에서도 옮긴 것을 가리키는 번호와 링크만 바꿨다.
- 옮긴 스크립트:
journal/assets/2026-10-17-split-decision-records.py