---
context: fork
name: adr-format
description: |
  ADR(Architecture Decision Record) 작성 스킬. 두 개 이상의 기술 선택지를 비교하고
  추천안과 그 근거, 숨겨진 비용, 확장성, 2년 뒤 기술 부채까지 입체적으로 평가한다.
  비개발자도 이해할 수 있도록 한국어 위주 설명 + 추천안 강조.
  자동 트리거: "A vs B", "X와 Y 중 뭐가 좋아", "어떤 라이브러리 써야 해",
  "기술 선택", "스택 결정", "아키텍처 결정", "DB 뭐 쓰지", "프레임워크 고민",
  "이거 쓸까 저거 쓸까", "should I use", "which is better", "compare options",
  "tech choice", "library decision", "framework comparison", "architecture decision".
lang: [en, ko]
platforms: [claude-code, gemini-cli, codex-cli, cursor]
level: 2
progressive_disclosure:
  enabled: true
  level1_tokens: 120
  level2_tokens: 3500
triggers:
  - "A vs B"
  - "X와 Y 중"
  - "어떤 라이브러리"
  - "어떤 프레임워크"
  - "어떤 DB"
  - "기술 선택"
  - "스택 결정"
  - "아키텍처 결정"
  - "ADR"
  - "should I use"
  - "which is better"
  - "compare options"
  - "tech choice"
  - "library decision"
  - "framework comparison"
  - "architecture decision"
  - "뭐가 좋아"
  - "뭐 쓰지"
  - "고민"
agent: Plan
allowed-tools: [Read, Grep, Glob, Task]
agents:
  - "architect"
  - "planner"
argument-hint: "[선택지 A] vs [선택지 B] e.g. PostgreSQL vs MongoDB, React Query vs SWR"
tokens: "~3K"
category: "decision"
source_hash: adrfmt01
whenNotToUse: "단일 선택지에 대한 단순 설명(→ /explain), 이미 결정된 사항의 구현 계획(→ /plan), 코드 리뷰(→ /code-review), 버그 수정(→ /troubleshoot). 또한 비교 대상이 1개뿐이거나 trivial한 선택(예: 변수명, 들여쓰기)에는 사용하지 않는다."
---

# ADR Format: 기술 선택 의사결정 기록

`$ARGUMENTS`로 비교할 선택지를 받는다. 예: "PostgreSQL vs MongoDB", "React Query vs SWR vs RTK Query".

## 언제 이 스킬을 쓰는가

- 2개 이상 기술/라이브러리/접근법 중 하나를 골라야 할 때
- 결정이 되돌리기 어렵거나(DB, 인증 방식, 메시징 큐) 팀 전체에 영향을 줄 때
- 비개발자 PM/디자이너/창업자에게 기술 선택 근거를 설명해야 할 때
- 사내에 의사결정 흔적(ADR)을 남겨두고 6개월 뒤에 "왜 그랬더라" 막아야 할 때
- 트래픽/데이터/사용자가 10배 늘었을 때 무너지는지 미리 점검하고 싶을 때

## 핵심 원칙 (비개발자도 이해 가능하게)

1. **추천안을 가장 위에** — 결론부터 본다. 근거는 뒤에 따라온다.
2. **숨은 비용을 드러낸다** — 라이선스, 학습 곡선, 채용 난이도, 운영 인력, 마이그레이션 공수 등 "공식 문서엔 안 나오는" 비용.
3. **2년 뒤 관점** — 지금은 편해도 2년 뒤 기술 부채가 되는 선택을 경고.
4. **숫자보다 시나리오** — "10배 트래픽 시 어떤 일이 벌어지나" 같은 구체적 그림.
5. **어려운 용어는 풀어쓴다** — "샤딩"이라 쓰면 "데이터를 여러 서버에 쪼개 저장하는 방식(샤딩)"으로.

## 7-섹션 평가 프레임워크

매 선택지마다 다음 7개 축으로 평가한다.

| # | 섹션 | 무엇을 보는가 |
|---|------|--------------|
| 1 | 컨텍스트와 제약사항 | 현재 팀 규모, 기술 스택, 예산, 마감, 기존 시스템 호환성 |
| 2 | 각 접근의 trade-off | 장점과 단점을 짝으로 (장점만 나열 금지) |
| 3 | 확장성 관점 | 사용자 100명 → 10만 명까지 동일 구조로 갈 수 있나 |
| 4 | 10× 트래픽/데이터 증가 시 문제 | 구체적 시나리오: "DB 커넥션 풀 고갈", "캐시 미스 폭증" 등 |
| 5 | 숨겨진 비용 | 라이선스, 학습 곡선, 채용 풀, 운영 인력, 마이그레이션 |
| 6 | 추천안과 그 이유 | **굵게 강조**. 왜 다른 것 말고 이것인가 |
| 7 | 2년 뒤 기술 부채 예상 | 이 결정이 가져올 미래 부채 포인트 |

## 출력 양식 (실제 엔지니어링 조직 ADR)

```markdown
# ADR-{auto-increment}: {결정 제목 — 예: "주 DB로 PostgreSQL 채택"}

## 추천 결론 (TL;DR)
> **{선택지 X}를 추천한다.** 이유는 {핵심 한 줄}. {반대 선택지}는 {결정적 단점} 때문에 보류.

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-{n}

작성일: {YYYY-MM-DD}
작성자: {이름 또는 팀}

---

## 1. Context (컨텍스트와 제약사항)

**현재 상황**: {배경 — 왜 지금 이 결정이 필요한가}

**제약사항**:
- 팀 규모: {N명}, 기술 스택: {스택}
- 예산: {월 운영비 한도}
- 마감: {언제까지 결정/구현 필요}
- 호환성: {기존 시스템과의 관계}

**이 결정이 영향을 주는 범위**: {모듈/서비스/팀}

---

## 2. Alternatives Considered (검토한 선택지)

### 선택지 A: {이름}
- **장점**: {2~4개, 사실 기반}
- **단점**: {2~4개, 사실 기반}
- **적합한 경우**: {어떤 상황에 이 선택이 옳은가}

### 선택지 B: {이름}
- **장점**: ...
- **단점**: ...
- **적합한 경우**: ...

### (선택지 C가 있다면) ...

### 비교 표

| 기준 | 선택지 A | 선택지 B | 비중 |
|------|---------|---------|------|
| 학습 곡선 (낮을수록 ★많음) | ★★★★ | ★★ | 15% |
| 확장성 (10× 트래픽) | ★★★ | ★★★★★ | 25% |
| 운영 비용 (낮을수록 ★많음) | ★★★★ | ★★★ | 20% |
| 생태계/커뮤니티 | ★★★★★ | ★★★ | 15% |
| 채용 난이도 (쉬울수록 ★많음) | ★★★★ | ★★ | 15% |
| 장기 유지보수 | ★★★ | ★★★★ | 10% |
| **가중 합계** | **3.65** | **3.25** | 100% |

---

## 3. 확장성 관점 평가

**현재 규모에서 (1×)**:
- 선택지 A: {동작 양상}
- 선택지 B: {동작 양상}

**3× 성장 시**:
- 선택지 A: {여전히 OK / 튜닝 필요 / 한계 보임}
- 선택지 B: ...

**10× 성장 시 (시나리오 분석)**:

| 시나리오 | 선택지 A | 선택지 B |
|---------|---------|---------|
| 동시 사용자 10만 | {예: 커넥션 풀 고갈, 샤딩 필요} | {예: 자동 분산되어 무난} |
| 일일 데이터 1TB | {예: 인덱스 재구축 시간 폭증} | {예: 자연 분산} |
| 응답 시간 P99 | {예상 ms} | {예상 ms} |
| 운영 인력 추가 필요 | {N명} | {N명} |

---

## 4. 숨겨진 비용 (사람들이 자주 놓치는 부분)

| 비용 항목 | 선택지 A | 선택지 B | 설명 |
|----------|---------|---------|------|
| 라이선스 | {예: 무료 / 상용 $X/년} | ... | {핵심 조항} |
| 학습 곡선 | {신규 입사자 N주} | ... | {왜 그런가} |
| 채용 가능 인력 풀 | {국내 N명 수준} | ... | {LinkedIn 기준 등} |
| 마이그레이션 공수 | {추후 변경 시 N개월} | ... | {되돌리기 어려움 정도} |
| 운영 모니터링 도구 | {추가 비용 $X/월} | ... | {필수 vs 옵션} |
| 보안 패치 대응 | {커뮤니티 / 벤더 SLA} | ... | {대응 속도} |
| 백업/복구 도구 | {기본 제공 / 별도 구매} | ... | ... |

---

## 5. Decision (추천안)

> ## ✓ **추천: 선택지 {X}**

**선택 근거**:
1. {가장 중요한 이유 — 제약사항/시나리오와 연결}
2. {두 번째 이유}
3. {세 번째 이유 — 보통 "숨은 비용 회피"}

**선택하지 않은 이유**:
- 선택지 {Y}: {결정적 단점 1~2개}
- 선택지 {Z}: {결정적 단점 1~2개}

**가정과 전제 조건**:
- {이 결정이 유효한 전제 — 예: "월 활성 사용자 100만 이하 유지 시"}
- {바뀌면 재검토 트리거가 될 조건}

---

## 6. Consequences (의사결정의 결과)

**좋아지는 점**:
- {긍정적 결과 1~3개}

**나빠지는 점 / 새로 떠안는 부담**:
- {부정적 결과 1~3개 — 솔직하게}

**필수 후속 작업**:
- [ ] {작업 1 — 예: 팀 학습 세션}
- [ ] {작업 2 — 예: 백업 정책 수립}
- [ ] {작업 3 — 예: 모니터링 대시보드 구성}

**되돌리기 비용 (Reversibility)**: ☐ 쉬움 / ☐ 비쌈 / ☑ 거의 불가능

---

## 7. 2년 뒤 기술 부채 예상 포인트

지금 이 선택을 하면, 2년 뒤 다음과 같은 부채가 쌓일 가능성이 있다.

| 부채 항목 | 발생 확률 | 영향도 | 완화 전략 |
|----------|---------|-------|---------|
| {예: 스키마 마이그레이션 점점 어려워짐} | 높음 | 중 | {예: 분기별 스키마 정리 회의} |
| {예: 신규 입사자 적응 기간 길어짐} | 중 | 낮음 | {예: 온보딩 문서 + 페어 프로그래밍} |
| {예: 벤더 락인} | 낮음 | 높음 | {예: 추상화 레이어 사전 구축} |

**재검토 시점**: {예: 2027-XX 또는 MAU 100만 돌파 시}

---

## References

- 관련 ADR: {ADR-NNN ...}
- 외부 자료: {링크}
- 내부 논의: {Slack 스레드, PR 등}
```

## 작성 프로세스

1. **선택지 파싱**: `$ARGUMENTS`에서 "A vs B vs ..." 추출. 자연어("PostgreSQL이랑 MongoDB 중 뭐가 나아?")도 받아서 정규화.
2. **컨텍스트 수집**: `Read`/`Grep`/`Glob`으로 현재 프로젝트의 스택, 규모, 제약을 파악. `package.json`, `requirements.txt`, 기존 ADR 폴더 등.
3. **architect 에이전트 위임**: 복잡도 medium+ 면 `Task(architect)`로 trade-off 분석 위임.
4. **7-섹션 채우기**: 위 양식대로 빈칸 없이. 모르는 항목은 "조사 필요"라고 명시(거짓 숫자 금지).
5. **추천안 굵게 강조**: TL;DR과 Section 5에서 박스/굵게로 부각.
6. **저장 경로 제안**: `docs/adr/ADR-{NNN}-{slug}.md` 형태로 저장 권장.

## 비개발자 친화 가이드

- **전문 용어는 한 번 풀어쓰기**: "ORM(객체-관계 매퍼, 코드에서 DB를 객체처럼 다루게 해주는 도구)"
- **돈 단위로 비교 가능하게**: "월 운영비 약 $X 추가" 식으로
- **시간 단위로 비교 가능하게**: "팀원 신규 학습 약 2주" 식으로
- **이모지/별점 활용**: ★ 점수, ✓ 추천, ⚠ 위험. 단, 본문은 텍스트로
- **결론 먼저, 근거는 뒤**: PM/창업자는 첫 줄만 읽고 결정할 수 있어야

## Constraints

- **선택지는 최소 2개, 최대 4개** — 5개 이상은 비교 피로. 먼저 2~4개로 줄이고 ADR 시작.
- **추천안은 반드시 1개** — "둘 다 좋아요"는 ADR이 아님. 제약 조건을 명확히 해서 한쪽으로 기울이게.
- **"조사 필요"는 명시** — 모르는 수치를 추정으로 채우지 말 것.
- **2년 뒤 부채 섹션은 필수** — 단기 편의만 보면 ADR의 가치가 없음.
- **한국어 위주 + 영어 기술 용어 병기** — `PostgreSQL`, `connection pool` 같은 고유명사는 영어 유지.

## Red Flags (작성 중 멈추고 재검토)

- 추천안이 비교 표의 가중 합계와 다른데 근거 설명이 없음
- 모든 선택지의 장단점 개수가 똑같음 (실제로는 균형이 깨져 있음)
- 숨겨진 비용 섹션이 비어있거나 "특별히 없음"으로 채워짐
- 10× 시나리오가 두루뭉술하게 "잘 됨/안 됨"으로만 표기됨
- 2년 뒤 부채 예상이 "딱히 없음"으로 끝남 (모든 선택에는 부채가 있다)
- 비개발자가 TL;DR만 읽고 결정 못 함

## Rationalizations

| Excuse | Rebuttal |
|--------|----------|
| "선택은 명확하니까 ADR은 형식적이야" | 명확해 보이는 선택의 70%는 1년 뒤 "그때 다른 거 했어야"로 끝남. ADR은 그 70%를 거르는 장치. |
| "숨은 비용까지 다 조사하긴 시간 없어" | 결정 1시간 vs 잘못된 선택의 마이그레이션 3개월. 시간 못 쓰면 "조사 필요"로 명시. |
| "추천은 못 하겠고 둘 다 장단점 있다" | "결정 회피" = "결정을 다른 사람한테 떠넘김". 제약을 좁혀서 1개로 수렴시켜야 ADR. |
| "10× 트래픽 시나리오는 우리에겐 안 와" | 안 와서 다행이지, 오면 ADR이 살린다. 보험을 안 들 이유는 아님. |
| "2년 뒤는 너무 멀어, 그때 그때 대응하면 돼" | 그때 그때 대응이 누적된 게 기술 부채. ADR의 핵심 가치는 "지금 결정의 미래 비용"을 미리 보는 것. |

## See Also

- [persona-architect](../persona-architect/SKILL.md) — 시스템 설계 결정 프레임워크 (이 스킬과 함께 쓰면 강력)
- [decision-framework](../persona-architect/references/decision-framework.md) — 가중 스코어링 ADR 템플릿
- [clarify](../clarify/SKILL.md) — 선택지가 모호할 때 먼저 명확히 (vague → ADR 가능 형태로)
- [plan](../../commands/plan.md) — ADR로 결정한 안을 실행 계획으로