ADR 라이터은(는) 무엇을 하나요?
명확한 맥락, 대안 및 결과와 함께 아키텍처 결정을 문서화합니다. 영어로 작성하세요.
ADR 템플릿
# ADR-[번호]: [짧은 결정 제목]
**상태:** [제안됨 | 수락됨 | 폐기됨 | ADR-XXX로 대체됨]
**날짜:** [YYYY-MM-DD]
**작성자:** [이름/핸들]
## 1. 맥락
어떤 문제를 해결하고 있습니까? 어떤 요소가 영향을 미칩니까 (비즈니스 목표, 기술 부채, 예산)?
**제약 사항:**
- [제약 사항 1]
- [제약 사항 2]
## 2. 결정
결정에 대한 간단한 설명. 주요 논점.
## 3. 기술 세부 사항 및 메커니즘
_자유 형식 섹션. 구현 세부 사항, 데이터 구조, 프로토콜 세부 사항 또는 주요 프레임워크 기능을 설명합니다._
- [목록, API 설명, 데이터 스키마]
- [복잡한 상호 작용의 경우 Mermaid 시각화 (권장)]
## 4. 고려된 대안
### 4.1. [대안 1]
- **장점:** ...
- **단점:** ...
- **결정:** [거부됨/고려됨] (간단한 이유).
## 5. 결과 및 위험
### 긍정적 (장점)
- 이것이 시스템/팀에 어떻게 도움이 됩니까?
### 부정적 / 위험 (단점/위험)
- 어떤 단점을 감수합니까? 위협은 무엇입니까?
- **완화:** 위험을 어떻게 처리할 것입니까?
## 6. 변경 이력
- **[날짜]**: [변경 설명] ([작성자])
- **[날짜]**: [예: 상태가 수락됨으로 변경됨] ([작성자])
ADR 번호 매기기
ADR-001: 초기 시스템 아키텍처
ADR-002: 분석을 위한 데이터베이스 선택
ADR-003: 인증 전략
...
상태 워크플로우
제안됨 → 수락됨 → 구현됨
↓
거부됨
수락됨 → 폐기됨 → ADR-XXX로 대체됨
모범 사례
- 중요한 결정에 대해 ADR 작성: 모든 선택에 ADR이 필요한 것은 아닙니다.
- 대안 문서화: 옵션을 고려했음을 보여줍니다.
- 트레이드오프에 대해 솔직하게: 모든 결정에는 단점이 있습니다.
- 간결하게 유지: 최대 1-2페이지.
- 상태 업데이트: 폐기됨/대체됨 ADR을 표시합니다.
- 관련 ADR 연결: 결정 추적을 생성합니다.
- 후속 조치 포함: 소유자가 있는 작업 항목.
- 시각화: Mermaid 다이어그램을 사용하여 아키텍처와 흐름을 보여줍니다.
- 미래의 독자를 위해 작성 현재 맥락이 부족한 독자를 고려하세요.
- 트레이드오프에 대해 솔직하세요 (모든 선택에는 단점이 있습니다).
일반적인 패턴
기술 선택의 경우:
- 요구 사항 대 기술적 기능에 초점을 맞춥니다.
- 가능한 경우 성능 벤치마크를 포함합니다.
- 팀 전문성 수준을 문서화합니다.
- 운영 복잡성을 고려합니다.
아키텍처 변경의 경우:
- 결과에 마이그레이션 전략을 포함합니다.
- 이전 버전과의 호환성 영향을 문서화합니다.
- 전환 중 팀 속도 영향을 고려합니다.
- 모니터링 및 롤백 계획을 기록합니다.
표준 및 규칙의 경우:
- 실제 표준의 예를 포함합니다.
- 예외 또는 탈출구를 문서화합니다.
- 시행 메커니즘을 고려합니다.
- 교육/온보딩 영향을 기록합니다.
폐기의 경우:
- 상태를 "폐기됨" 또는 "대체됨"으로 설정합니다.
- 대체 ADR에 연결합니다.
- 서비스 종료 타임라인을 문서화합니다.
- 마이그레이션 가이드를 포함합니다.
안티 패턴
❌ 너무 자세함: 아무도 읽지 않는 10페이지짜리 ADR. ❌ 대안 없음: 결정이 미리 정해진 것처럼 보입니다. ❌ 결과 누락: 단점을 무시합니다. ❌ 소유자 없음: 책임자가 없습니다. ❌ 상태 업데이트 안 됨: 오래된 ADR이 "제안됨"으로 표시됨.
검토 체크리스트
- 맥락에 명확한 문제 설명이 있습니다.
- 결정이 명시적으로 설명되었습니다.
- 2개 이상의 대안이 고려되었습니다.
- 트레이드오프가 정직하게 평가되었습니다.
- 결과 (긍정적 및 부정적)가 문서화되었습니다.
- 완화 조치와 함께 위험이 식별되었습니다.
- 결정 소유자가 지정되었습니다.
- 마감일이 있는 후속 조치가 있습니다.
- 상태가 최신입니다.
출력 체크리스트
- ADR 문서가 생성되었습니다.
- 맥락이 문제를 설명합니다.
- 결정이 명확하게 설명되었습니다.
- 2-3개의 대안이 문서화되었습니다.
- 트레이드오프 섹션이 채워졌습니다.
- 결과 (긍정적 및 부정적)가 나열되었습니다.
- 완화 조치와 함께 위험이 식별되었습니다.
- 결정 날짜 및 소유자가 있습니다.
- 후속 조치가 할당되었습니다.
- 상태가 설정되었습니다.