아키텍처 의사결정 기록은(는) 무엇을 하나요?
코딩 세션 중 발생하는 아키텍처 결정을 캡처합니다. 결정 사항이 Slack 스레드, PR 댓글 또는 누군가의 기억에만 머무르는 대신, 이 스킬은 코드와 함께 보관되는 구조화된 ADR 문서를 생성합니다.
활성화 시점
- 사용자가 명시적으로 "이 결정을 기록하자" 또는 "ADR로 남기자"고 말하는 경우
- 사용자가 중요한 대안(프레임워크, 라이브러리, 패턴, 데이터베이스, API 설계) 중에서 선택하는 경우
- 사용자가 "우리는 ...를 결정했습니다" 또는 "X 대신 Y를 하는 이유는 ...입니다"라고 말하는 경우
- 사용자가 "왜 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을 대체함 (항상 대체 ADR 링크 포함)
기록할 가치가 있는 결정 범주
| 범주 | 예시 |
|---|---|
| 기술 선택 | 프레임워크, 언어, 데이터베이스, 클라우드 제공자 |
| 아키텍처 패턴 | 모놀리스 vs 마이크로서비스, 이벤트 기반, CQRS |
| API 설계 | REST vs GraphQL, 버전 관리 전략, 인증 메커니즘 |
| 데이터 모델링 | 스키마 설계, 정규화 결정, 캐싱 전략 |
| 인프라 | 배포 모델, CI/CD 파이프라인, 모니터링 스택 |
| 보안 | 인증 전략, 암호화 방식, 비밀 관리 |
| 테스트 | 테스트 프레임워크, 커버리지 목표, E2E vs 통합 테스트 균형 |
| 프로세스 | 브랜칭 전략, 리뷰 프로세스, 릴리스 주기 |
다른 스킬과의 통합
- Planner 에이전트: 플래너가 아키텍처 변경을 제안할 때 ADR 생성을 제안합니다.
- Code reviewer 에이전트: 해당 ADR 없이 아키텍처 변경을 도입하는 PR에 플래그를 지정합니다.