아키텍처 의사결정 기록 (Architecture Decision Records)
코딩 세션 중 발생하는 아키텍처 결정을 캡처합니다. 결정이 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/디렉토리가 없으면, 사용자에게 확인을 요청한 후 디렉토리, README.md(아래 ADR 인덱스 형식의 헤더 포함), 수동 사용을 위한 빈template.md를 생성합니다. 명시적 동의 없이는 파일을 생성하지 마십시오. - 결정 식별 — 핵심 아키텍처 선택을 추출합니다.
- 맥락 수집 — 어떤 문제가 이를 촉발했는가? 어떤 제약 조건이 있는가?
- 대안 문서화 — 어떤 다른 옵션이 고려되었는가? 왜 기각되었는가?
- 결과 명시 — 트레이드오프는 무엇인가? 무엇이 더 쉬워지거나 어려워지는가?
- 번호 할당 —
docs/adr/에서 기존 ADR을 스캔하고 번호를 증가시킵니다. - 확인 및 작성 — ADR 초안을 사용자에게 검토용으로 제시합니다. 명시적 승인 후에만
docs/adr/NNNN-결정-제목.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에 플래그를 지정합니다