| name | adr |
| description | Use when making architectural decisions, choosing between frameworks/libraries/databases, deciding on data models, or recording any decision that would be expensive to reverse. Do NOT use for code documentation (comments belong in code), daily notes (use obsidian-note), or TIL (use til). |
Architecture Decision Records (ADR)
결정의 이유를 기록. 코드는 무엇을 했는지 보여주지만 ADR은 왜 그렇게 했는지와 어떤 대안을 버렸는지를 보존한다. 이 맥락은 미래의 엔지니어와 에이전트가 재논쟁하지 않도록 한다.
Quick Start
CRITICAL Rules
- ALWAYS record Context, Decision, Alternatives, Consequences — 4가지 모두 필수. 하나라도 빠지면 ADR이 아니라 메모.
- NEVER delete old ADRs — 결정이 바뀌면 새 ADR을 작성해 이전 ADR을
Superseded by ADR-NNN으로 표시. 과거 맥락을 삭제하지 말 것.
- ALWAYS list alternatives considered — "왜 이걸 안 골랐는가"가 "왜 이걸 골랐는가"만큼 중요.
- NEVER write ADR for trivial decisions — "함수 이름을 camelCase로 한다" 같은 건 ADR 아님. 되돌리기 비싼 결정에만.
- ALWAYS date the ADR — 결정 시점의 제약·맥락이 시간에 따라 바뀐다.
- PREFER short ADRs — 1~2페이지. 장황한 ADR은 읽히지 않는다.
When to Write
ADR을 작성해야 할 때
- 프레임워크·라이브러리·주요 의존성 선택 (React vs Vue, Prisma vs TypeORM)
- 데이터 모델이나 DB 스키마 설계
- 인증 전략 선택 (JWT vs Session, OAuth 제공자 선택)
- API 아키텍처 결정 (REST vs GraphQL vs tRPC)
- 빌드 도구·호스팅 플랫폼·인프라 선택
- 되돌리기 비싼 결정이라면 무엇이든
ADR을 작성하지 말아야 할 때
- 변수명·함수명 같은 일상 코딩 결정
- 쉽게 되돌릴 수 있는 수정
- 이미 코드에서 명확한 "무엇" 설명 — 그건 주석의 영역
- 프로토타입의 일회성 결정
ADR Template
docs/decisions/ADR-NNN-짧은-제목.md:
# ADR-001: Primary DB로 PostgreSQL 사용
## Status
Accepted | Superseded by ADR-NNN | Deprecated
## Date
2026-04-16
## Context
태스크 관리 애플리케이션의 primary DB가 필요하다. 주요 요구사항:
- 관계형 데이터 모델 (users, tasks, teams 관계)
- 태스크 상태 변경을 위한 ACID 트랜잭션
- 태스크 내용에 대한 full-text search
- 관리형 호스팅 (소규모 팀, 운영 역량 제한)
## Decision
PostgreSQL + Prisma ORM 사용.
## Alternatives Considered
### MongoDB
- **Pros:** 유연한 스키마, 시작 용이
- **Cons:** 우리 데이터는 본질적으로 관계형. 관계를 수동 관리해야 함
- **Rejected:** 문서 저장소의 관계형 데이터는 복잡한 join 또는 데이터 중복을 초래
### SQLite
- **Pros:** 설정 없음, 임베디드, 읽기 빠름
- **Cons:** 동시 쓰기 제한, 프로덕션 관리형 호스팅 없음
- **Rejected:** 멀티유저 웹 프로덕션에 부적합
### MySQL
- **Pros:** 성숙하고 널리 지원
- **Cons:** PostgreSQL이 JSON·full-text search·ecosystem 툴링에서 우위
- **Rejected:** 우리 기능 요구에 PostgreSQL이 더 적합
## Consequences
### Positive
- Prisma가 타입 안전 DB 접근 + migration 제공
- PostgreSQL의 full-text search로 Elasticsearch 추가 회피
- 관리형 서비스 (Supabase, Neon, RDS)에서 호스팅 가능
### Negative
- 팀이 PostgreSQL 지식 필요 (표준 스킬이라 리스크 낮음)
- Prisma 학습 곡선 (MongoDB 쓴 경험과 다름)
### Neutral
- 마이그레이션이 버전 관리됨 — 롤백 전략 필요
ADR Lifecycle
PROPOSED → ACCEPTED → (SUPERSEDED | DEPRECATED)
| Status | 의미 |
|---|
| Proposed | 검토 중, 아직 결정 안 됨 |
| Accepted | 결정됨, 구현됨 |
| Superseded | 새 ADR이 이 결정을 대체 — 본문에 Superseded by ADR-NNN 명시 |
| Deprecated | 더 이상 유효하지 않지만 대체가 없음 — 역사적 참조용 |
결정이 바뀔 때
ADR-007이 ADR-001을 대체한다면:
- 새 ADR-007을 쓴다 (Context에 "ADR-001을 대체하는 이유" 포함)
- ADR-001의 Status를
Superseded by ADR-007로 업데이트
- ADR-001을 삭제하지 않는다 — 과거 맥락을 보존
"왜 이렇게 했지?"를 3년 뒤 누군가 물을 때, 원본 ADR의 Context가 답이다.
Storage & Numbering
- 위치:
docs/decisions/ 또는 docs/adr/ (프로젝트 관습 따름)
- 네이밍:
ADR-NNN-kebab-case-title.md (예: ADR-003-use-postgres.md)
- 순차 번호 — 절대 재사용 금지
- 새 리포 만들 때
docs/decisions/README.md에 ADR 목록 유지 (선택)
Agent-Specific Notes
AI 에이전트가 코드베이스에서 작업할 때 ADR은 특히 가치가 크다:
- 에이전트가 이미 결정된 것을 재논쟁하지 않도록 함
- CLAUDE.md에서
docs/decisions/를 읽으라고 지시 가능
- 새 기능 구현 전 관련 ADR 확인으로 일관성 유지
Common Rationalizations
| 변명 | 반박 |
|---|
| "코드가 스스로 문서화된다" | 코드는 무엇을 보여준다. 왜 그렇게 했는지, 어떤 대안을 버렸는지, 어떤 제약이 있었는지는 안 보여준다. |
| "API가 안정화되면 문서화할게요" | API는 문서화할 때 더 빨리 안정화된다. 문서는 설계의 첫 테스트다. |
| "아무도 문서 안 읽어요" | 에이전트는 읽는다. 미래 엔지니어도 읽는다. 3개월 뒤의 당신도 읽는다. |
| "ADR은 오버헤드예요" | 10분짜리 ADR이 6개월 뒤 같은 결정에 대한 2시간 논쟁을 예방한다. |
| "되돌리면 되잖아요" | 되돌릴 수 있으면 ADR이 필요 없다. 되돌리기 어렵기 때문에 기록한다. |
Red Flags
- 서면 근거 없는 아키텍처 결정
- 중요 아키텍처 선택이 있는데 ADR이 없는 프로젝트
- "팀이 결정했다"만 있고 이유가 없는 ADR
- Alternatives Considered 섹션이 없는 ADR
- 삭제된 옛 ADR (git 히스토리에만 존재)
- 1년 넘게
Proposed 상태로 방치된 ADR
Verification
ADR 작성 후:
Cross-References
| Topic | Skill |
|---|
| 개인 지식 노트 | obsidian-note |
| TIL (일일 학습) | til |
| 프로젝트 작업 로그 | devlog |
| 세션 맥락 전달 | session-handoff |
| 코드 리뷰 | code-review |
References
