Imported from Yoodaddy0311/artibot (plugins/artibot/skills/adr-format/SKILL.md). Install upstream with npx skills add Yoodaddy0311/artibot --skill adr-format. Copyright stays with the author.

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개 축으로 평가한다.

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

# 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+ 면 Agent(architect)로 trade-off 분석 위임.
4. 7-섹션 채우기: 위 양식대로 빈칸 없이. 모르는 항목은 "조사 필요"라고 명시(거짓 숫자 금지).
5. 추천안 굵게 강조: TL;DR과 Section 5에서 박스/굵게로 부각.
6. 저장 경로 제안: <ADR 디렉터리>/ADR-{NNN}-{slug}.md 형태로 저장 권장. ADR 디렉터리는 lib/planning/artifacts.js#resolveAdrDir 이 정한다 — .artibot/adr/ · docs/adr/ · adr/ 중 이미 계열을 담은 곳, 없으면 .artibot/ 이 있는 프로젝트는 .artibot/adr/, 그 외는 docs/adr/.

비개발자 친화 가이드

• 전문 용어는 한 번 풀어쓰기: "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

See Also

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