[AI 활용법 6] ADR — 의사결정을 영속화하는 가장 가벼운 방법

시리즈 6편. 코드 보다 먼저 사라지는 것이 코드를 그렇게 만든 이유 다. ADR은 그 이유를 붙잡아 두는 가장 가벼운 형식이다.

왜 ADR인가

새 팀원, 또는 3개월 뒤의 나, 가 가장 자주 묻는 질문은 “왜 이렇게 했지?”다.

• 왜 Postgres 대신 SQLite?
• 왜 GraphQL을 안 쓰고 REST?
• 왜 커스텀 큐 를 만들었지, RabbitMQ 두고?

코드는 무엇이 있는지 만 보여 준다. 그래서 다른 선택지를 검토했다 는 사실 자체가 사라진다. ADR(Architecture Decision Record)은 이 빈자리를 채우는 형식이다 — Michael Nygard가 2011년에 제안한, 한 페이지짜리 메모.

가장 짧은 ADR 템플릿

# YYYY-MM-DD — <주제>

## Status
Accepted | Superseded by [[…]] | Deprecated

## Context
- 어떤 상황에서 결정해야 했는가?
- 어떤 제약이 있었는가? (시간, 사람, 기술)

## Decision
- 무엇을 선택했는가?
- (선택적) 어떤 대안을 검토했고, 왜 안 골랐는가?

## Consequences
- 좋아진 것
- 잃은 것 / 다음에 다시 봐야 할 것

3~6 문단이면 충분하다. 길어진다는 건 아직 결정이 덜 된 것.

좋은 ADR의 예

# 2026-04-22 — Use SQLite for the local-first dashboard

## Status
Accepted

## Context
The dashboard ships as a single Python file. Adding Postgres
would require users to install and manage a separate process,
breaking the "zero-deps" promise. Data volume is bounded
(~500MB tops, single user).

## Decision
Use SQLite via stdlib (`sqlite3`). Schema lives in a single
`schema.sql`, applied idempotently on first run.

We considered:
- Postgres — too heavy for the install story.
- DuckDB — better for analytics, but writes are slower for our
  high-frequency append pattern.
- Plain JSON files — not transactional; corrupted on crash mid-write.

## Consequences
+ Zero-install. `python3 server.py` still works.
+ Atomic writes via WAL.
- Single-writer ceiling. If we ever go multi-process we revisit.
- No JSONB ergonomics; we hand-roll JSON columns.

이 한 페이지가 6개월 뒤 누군가가 “Postgres로 바꾸자”고 말할 때 가장 큰 가치를 만든다.

ADR을 AI 에게 맡길 때

LLM은 ADR을 잘 쓴다. 단, 맥락이 충분할 때. 다음 4가지를 함께 주면 결과가 안정된다:

1. 결정이 일어난 대화의 핵심 발췌 — “이 라이브러리 너무 무거워” 같은 발화
2. 검토했던 대안 목록 — 하나만 쓰면 단방향처럼 보임
3. 명시한 제약 — 데드라인, 인력, 기존 시스템
4. 합의된 결과

# AI에게 줄 프롬프트 예
다음 대화 발췌와 제약을 바탕으로, 위 ADR 템플릿을 채워서
"decisions/2026-04-22-cache-strategy.md" 한 파일로 작성해 줘.

[발췌]
- "redis까지는 과해 보여…"
- "근데 in-memory만 쓰면 재시작 시 다 날아가잖아"
- "그러면 mtime 키로 디스크에 캐시한 거 다시 읽어 오면 돼"

[제약]
- 단일 프로세스
- 데이터 ~10MB
- pip 의존성 추가 금지

ADR과 커밋의 연결

ADR은 영속, 커밋은 이력. 둘을 명시적으로 연결한다:

feat(cache): introduce mtime-keyed disk cache

See decisions/2026-04-22-cache-strategy.md

PR 본문에서도 ADR 링크를 단다. 이 한 줄이 3개월 뒤의 git blame 을 맥락 있는 탐험 으로 바꾼다.

ADR이 아닌 것

다음은 ADR로 쓰지 않는다 — 다른 형식이 더 잘 맞는다:

• 일일 작업 로그 → logs/YYYY-MM-DD.md
• 트러블슈팅 노트 → issues/<제목>.md
• 사용 가이드 → README / docs
• TODO 목록 → plans/today-queue.md

ADR은 선택과 그 선택의 영구적 결과 를 남기는 자리다. 모든 노트를 ADR로 만들면 ADR이 없는 것 이 된다.

ADR이 죽었을 때

상황이 바뀌어 결정이 더 이상 유효하지 않으면, ADR을 수정하지 않는다. 새 ADR을 만들고, 옛 ADR의 Status를 Superseded by [[…]]로 바꾼다. 이력 자체가 자산이기 때문이다.

# 2026-04-22 — Use SQLite for the local-first dashboard
## Status
Superseded by [[2026-09-10-postgres-migration]]

옛 결정이 왜 옛것이 되었는지 가 더 큰 학습이다.

한 줄 요약

코드는 무엇이 있는지 만 알려 준다. ADR은 왜 그것뿐인지 를 알려 준다.

다음 편: AI 활용법 7 — 모듈화 임계값과 책임 분리 이전 편: AI 활용법 5 — Git 워크플로우