아키텍처 결정 기록 (ADR)
코딩 세션 중에 발생하는 아키텍처 결정을 캡처합니다. 결정이 Slack 스레드, PR 댓글, 또는 누군가의 기억 속에만 남는 대신, 이 스킬은 구조화된 ADR 문서를 생성하여 코드와 함께 보관합니다.
활성화 시점
- 사용자가 명시적으로 "이 결정을 기록해줘" 또는 "ADR 해줘"라고 말할 때
- 사용자가 중요한 대안(프레임워크, 라이브러리, 패턴, 데이터베이스, API 설계) 중에서 선택할 때
- 사용자가 "우리는 ...로 결정했어" 또는 "우리가 Y 대신 X를 하는 이유는 ...이야"라고 말할 때
- 사용자가 "왜 X를 선택했지?"라고 물을 때 (기존 ADR 읽기)
- 계획 단계에서 아키텍처 트레이드오프가 논의될 때
ADR 형식
AI 지원 개발에 맞게 조정된 Michael Nygard가 제안한 가벼운 ADR 형식을 사용합니다:
# ADR-NNNN: [결정 제목]
**날짜**: YYYY-MM-DD
**상태**: 제안됨 | 수락됨 | 폐기됨 | ADR-NNNN으로 대체됨
**결정자**: [참여한 사람]
## 문맥
이 결정 또는 변경을 추진하게 만든 문제는 무엇인가요?
[상황, 제약 조건, 영향을 미치는 힘을 설명하는 2-5문장]
## 결정
우리가 제안하거나 수행하는 변경은 무엇인가요?
[결정을 명확하게 설명하는 1-3문장]
## 고려한 대안
### 대안 1: [이름]
- **장점**: [이점]
- **단점**: [단점]
- **선택하지 않은 이유**: [이 대안이 기각된 구체적인 이유]
### 대안 2: [이름]
- **장점**: [이점]
- **단점**: [단점]
- **선택하지 않은 이유**: [이 대안이 기각된 구체적인 이유]
## 결과
이 변경으로 인해 무엇이 더 쉬워지거나 어려워지나요?
### 긍정적
- [이점 1]
- [이점 2]
### 부정적
- [트레이드오프 1]
- [트레이드오프 2]
### 위험
- [위험 및 완화 방안]
워크플로우
새 ADR 캡처
결정 순간이 감지되면:
- 초기화 (처음 한 번만) —
docs/adr/디렉토리가 존재하지 않으면, 사용자에게 확인을 요청한 후 디렉토리, 아래 ADR 인덱스 형식의 인덱스 테이블 헤더가 포함된README.md, 그리고 수동 사용을 위한 빈template.md를 생성합니다. 명시적인 동의 없이 파일을 생성하지 마십시오. - 결정 식별 — 핵심 아키텍처 선택 사항을 추출합니다.
- 문맥 수집 — 어떤 문제가 이를 촉발했는가? 어떤 제약 조건이 있는가?
- 대안 문서화 — 어떤 다른 옵션이 고려되었는가? 왜 기각되었는가?
- 결과 명시 — 트레이드오프는 무엇인가? 무엇이 더 쉬워지거나 어려워지는가?
- 번호 할당 —
docs/adr/에서 기존 ADR을 스캔하고 번호를 증가시킵니다. - 확인 및 작성 — ADR 초안을 사용자에게 검토하도록 제시합니다. 명시적 승인 후에만
docs/adr/NNNN-decision-title.md에 작성합니다. 사용자가 거절하면 파일을 작성하지 않고 초안을 폐기합니다. - 인덱스 업데이트 —
docs/adr/README.md에 추가합니다.
기존 ADR 읽기
사용자가 "왜 X를 선택했지?"라고 물으면:
docs/adr/디렉토리가 존재하는지 확인합니다. 존재하지 않으면 "이 프로젝트에서 ADR을 찾을 수 없습니다. 아키텍처 결정 기록을 시작하시겠습니까?"라고 응답합니다.- 존재하면
docs/adr/README.md인덱스에서 관련 항목을 스캔합니다. - 일치하는 ADR 파일을 읽고 문맥 및 결정 섹션을 제시합니다.
- 일치하는 항목이 없으면 "해당 결정에 대한 ADR을 찾을 수 없습니다. 지금 기록하시겠습니까?"라고 응답합니다.
ADR 디렉토리 구조
docs/
└── adr/
├── README.md ← 모든 ADR의 인덱스
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← 수동 사용을 위한 빈 템플릿
ADR 인덱스 형식
# 아키텍처 결정 기록
| ADR | 제목 | 상태 | 날짜 |
|-----|------|------|------|
| [0001](0001-use-nextjs.md) | 프론트엔드 프레임워크로 Next.js 사용 | 수락됨 | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | 기본 데이터 저장소로 MongoDB 대신 PostgreSQL | 수락됨 | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | GraphQL 대신 REST API | 수락됨 | 2026-02-01 |
결정 감지 신호
대화에서 아키텍처 결정을 나타내는 다음 패턴을 주시하십시오:
명시적 신호
- "X로 가자"
- "Y 대신 X를 사용해야 해"
- "트레이드오프가 가치 있어 왜냐하면..."
- "이것을 ADR로 기록해줘"
암시적 신호 (ADR 기록을 제안하되 사용자 확인 없이 자동 생성하지는 마십시오)
- 두 프레임워크 또는 라이브러리를 비교하고 결론에 도달하는 경우
- 명시된 근거와 함께 데이터베이스 스키마 설계 선택을 하는 경우
- 아키텍처 패턴(모놀리스 vs 마이크로서비스, REST vs GraphQL) 중에서 선택하는 경우
- 인증/권한 부여 전략을 결정하는 경우
- 대안 평가 후 배포 인프라를 선택하는 경우
좋은 ADR의 조건
해야 할 것
- 구체적으로 작성하라 — "ORM 사용"이 아닌 "Prisma ORM 사용"
- 왜를 기록하라 — 근거가 무엇보다 중요하다
- 기각된 대안을 포함하라 — 미래 개발자는 무엇이 고려되었는지 알아야 한다
- 결과를 정직하게 명시하라 — 모든 결정에는 트레이드오프가 있다
- 짧게 유지하라 — ADR은 2분 안에 읽을 수 있어야 한다
- 현재 시제를 사용하라 — "우리는 X를 사용할 것입니다"가 아닌 "우리는 X를 사용합니다"
하지 말아야 할 것
- 사소한 결정을 기록하지 마라 — 변수 이름 지정이나 포맷팅 선택은 ADR이 필요하지 않다
- 에세이를 쓰지 마라 — 문맥 섹션이 10줄을 초과하면 너무 길다
- 대안을 생략하지 마라 — "그냥 선택했어요"는 유효한 근거가 아니다
- 표시 없이 소급 기록하지 마라 — 과거 결정을 기록하는 경우 원래 날짜를 명시하라
- ADR이 쓸모없어지도록 두지 마라 — 대체된 결정은 대체 ADR을 참조해야 한다
ADR 생애 주기
제안됨 → 수락됨 → [폐기됨 | ADR-NNNN으로 대체됨]
- 제안됨: 결정이 논의 중이며 아직 확정되지 않음
- 수락됨: 결정이 적용 중이며 따르고 있음
- 폐기됨: 결정이 더 이상 관련이 없음 (예: 기능 제거)
- 대체됨: 최신 ADR이 이것을 대체함 (항상 대체 ADR 링크 포함)
기록할 가치가 있는 결정 범주
| 범주 | 예시 |
|---|---|
| 기술 선택 | 프레임워크, 언어, 데이터베이스, 클라우드 제공자 |
| 아키텍처 패턴 | 모놀리스 vs 마이크로서비스, 이벤트 기반, CQRS |
| API 설계 | REST vs GraphQL, 버전 관리 전략, 인증 메커니즘 |
| 데이터 모델링 | 스키마 설계, 정규화 결정, 캐싱 전략 |
| 인프라 | 배포 모델, CI/CD 파이프라인, 모니터링 스택 |
| 보안 | 인증 전략, 암호화 접근 방식, 비밀 관리 |
| 테스트 | 테스트 프레임워크, 커버리지 목표, E2E vs 통합 테스트 균형 |
| 프로세스 | 브랜치 전략, 검토 프로세스, 릴리스 주기 |
다른 스킬과의 통합
- Planner 에이전트: 플래너가 아키텍처 변경을 제안할 때 ADR 생성을 제안하십시오.
- Code Reviewer 에이전트: 해당 ADR 없이 아키텍처 변경을 도입하는 PR에 플래그를 지정하십시오.