ADR 기술 의사결정 문서 생성기

ADR 기술 의사결정 문서 생성기 사용 가이드

기술 선택을 할 때 '왜 이렇게 했는지'를 남겨 두지 않으면 몇 달 뒤 같은 논의를 반복하게 됩니다. ADR(Architecture Decision Record)은 결정 하나를 짧은 문서 하나로 남기는 방식이고, 이 생성기는 그 문서를 일정한 형식으로 만들어 줍니다.

'내용' 칸에 '배경: …', '결정: …', '대안: …', '결과: …'처럼 절 이름을 붙여 한 줄씩 적으면 해당 절로 들어갑니다. 영어 Context·Decision·Alternatives·Consequences도 알아보고, 대안과 결과는 여러 줄이면 목록이 됩니다. '상태: 승인됨'처럼 적으면 상태 값이 바뀌고, 적지 않으면 '제안됨'입니다.

절 이름 없이 적은 줄은 '배경'으로 들어가고, 내용이 없는 절에는 '무엇을 하기로 했는지 한 문장으로 적으세요' 같은 안내 주석이 남습니다. 날짜는 작성한 날로 들어갑니다.

사용 방법

1. 1'결정 제목'과 'ADR 번호 (예: ADR-0042)'를 적습니다.
2. 2'내용' 칸에 '배경: …', '결정: …', '대안: …', '결과: …', '상태: …'를 아는 만큼 한 줄씩 적습니다.
3. 3'실행' 후 결과를 docs/adr/0042-제목.md 같은 파일로 저장하고 남은 안내 주석을 채웁니다.

결정 제목: 도구별 청크 분리
ADR 번호: ADR-0042
내용:
배경: 페이지마다 엔진 전체를 내려받음
결정: 도구별 청크 제공
대안: 큰 번들 유지
대안: 지연 로딩
상태: 승인됨

# ADR-0042: 도구별 청크 분리

- 상태: 승인됨
- 날짜: 2026-10-01

## 배경

페이지마다 엔진 전체를 내려받음

## 결정

도구별 청크 제공

## 검토한 대안

- 큰 번들 유지
- 지연 로딩

## 결과

<!-- 좋아지는 점과 감수할 비용을 적으세요 -->

이럴 때 쓰면 좋아요

• 라이브러리·데이터베이스 선택 이유를 기록할 때
• 아키텍처 회의 결론을 문서로 남길 때
• 새 팀원에게 과거 결정의 배경을 설명할 때
• 결정을 번복할 때 이전 ADR을 '대체됨'으로 정리할 때

문제가 생겼을 때

활용 팁

• ADR은 한 문서에 결정 하나만 담고, 짧게 쓰는 것이 핵심입니다. 긴 분석은 별도 문서로 두고 링크하세요.
• 결정을 바꿀 때는 기존 ADR을 지우지 말고 상태를 '대체됨 (ADR-0051)'으로 바꿔 이력을 남기세요.

자주 묻는 질문