의사결정 문서가 이걸 해결합니다. ADR이든 RFC든 결정 로그든 이름은 중요하지 않습니다. 중요한 건 선택하는 그 순간에 배경과 선택지와 근거를 적어두는 일입니다. 올해 개발팀을 맡게 되면서 그 가치를 어느 때보다 실감하고 있습니다. 조직의 기억이 되느냐, 조직의 구전 설화가 되느냐의 갈림길이거든요.

공들일 가치가 있는 이유

#

가장 뻔한 보상은 같은 논쟁을 두 번 하지 않아도 된다는 겁니다. “API 버저닝 전략, 이미 정하지 않았나요?” 무엇을 왜 결정했는지 기록이 명확히 남아 있으면 결론 난 문제는 결론 난 채로 있고, 팀은 왔던 길을 되짚는 대신 실행에 에너지를 씁니다.

더 조용한 보상은 시간이 지나면서 드러납니다. 프로젝트는 몇 달, 몇 년씩 이어지고 사람은 들어오고 나가는데, 끝까지 남는 건 코드입니다. 문제는 코드가 “무엇을” 결정했는지는 알려줘도 “왜"는 절대 말해주지 않는다는 점이죠. 의사결정 문서는 그 추론을 보존합니다. 당시 존재했던 제약, 기각된 대안, 최종 판단을 내린 사람까지요. 새 팀원은 구전 설화 대신 맥락을 얻습니다. 팀을 넘나드는 결정은 결론만이 아니라 저울에 올랐던 요소까지 모두에게 보이니 진짜 동의를 얻기 쉬워집니다. 그리고 의사결정자와 기여자의 이름이 박히면, 후속 실행에도 확실한 주인이 생깁니다.

언제 쓰는가

#

모든 결정에 문서가 필요하진 않습니다. 저는 결정이 다음에 해당할 때 문서를 씁니다.

• 되돌리기 비싼 결정 — 기술 스택 선택(프레임워크, 데이터베이스, 클라우드 제공업체), 아키텍처 패턴(마이크로서비스 vs 모놀리스, 이벤트 기반 vs 요청-응답), 서드파티 벤더 선정, 보안·규정 준수 접근 방식
• 오래 남는 결정 — 외부 시스템이 의존하는 API 계약, 여러 서비스에 걸치는 데이터 모델, 확립된 패턴에 대한 파괴적 변경
• 팀을 가로지르는 결정 — 여러 팀이나 비기술 이해관계자의 동의가 필요한 것, 리소스 배분과 우선순위 판단
• 스파이크의 결론 — 타임박스 조사가 끝났다면, 발견과 결정이 증발하기 전에 문서로 남기기

반대로 쉽게 되돌릴 수 있는 결정, 팀 내부 구현 세부사항, 내 범위 밖에는 거의 영향이 없는 선택이라면 형식을 갖춘 문서는 건너뛰세요. 아무도 필요로 하지 않는 문서는 그냥 숙제일 뿐입니다.

라이프사이클

#

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   초안      │ ──► │   리뷰      │ ──► │   승인      │ ──► │   구현      │
│   제안      │     │  피드백     │     │   수락      │     │   완료      │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   거부/     │
                    │   대체      │
                    └─────────────┘

작성자가 문제와 후보 솔루션을 초안으로 정리하고, 이해관계자들이 리뷰합니다. 이 과정의 본전을 뽑는 곳이 리뷰 단계입니다. 가정을 따져 묻고 맹점이 드러나는 지점이니까요. 그다음 의사결정자(보통 기술 리드, 아키텍트, 프로덕트 오너)가 최종 판단을 내리고, 팀이 구현하며, 구현 중 현실 때문에 바뀐 부분이 있으면 문서도 갱신합니다. 리뷰에서 죽는 문서도 있고, 상황이 변해 나중에 대체되는 문서도 있습니다. 둘 다 분명하게 표시하세요. “승인됨” 상태로 낡아버린 문서는 다음에 그걸 발견할 사람에게 함정이 됩니다.

읽을 만한 문서를 만드는 것들

#

애착이 가는 솔루션이 아니라 문제에서 시작하세요. 무엇을 해결하려는지, 왜 지금 중요한지, 아무것도 안 하면 어떻게 되는지. 문제에 대한 합의가 없는 상태에서 솔루션을 논쟁하는 건 연극일 뿐입니다.

그다음 진짜 선택지를 제시합니다. 강한 선호가 있어도 최소 2~3개의 대안을요. 각 옵션에는 간단한 설명, 장단점, 대략적인 공수 추정(티셔츠 사이즈면 충분합니다: S/M/L/XL), 그리고 리스크와 완화 방안을 답니다. 대안을 기록해 두는 것이야말로 미래의 독자가 “왜 승자가 이겼는지” 이해하는 방법입니다.

트레이드오프는 소리 내어 말하세요. “아키텍처의 순수함보다 시장 출시 속도를 택합니다.” “더 나은 확장성을 위해 운영 복잡도 증가를 감수합니다.” “순수 성능보다 개발자 경험을 우선합니다.” 이런 문장 하나가 분석 몇 페이지보다 미래의 독자에게 더 도움이 됩니다.

논의는 구체적인 것에 붙들어 매세요. 솔루션이 어떻게 구현될지 보여주는 코드 스니펫, 시스템 상호작용 다이어그램, 스파이크에서 만든 개념 증명 링크. 추상적인 논의에서는 추상적인 결정밖에 안 나옵니다.

마지막으로 기한입니다. 언제까지 결정해야 하는지, 누가 언제까지 의견을 내야 하는지, 결정이 미뤄지면 무엇이 막히는지. 기한 없는 결정은 영원히 떠다닙니다.

예시: 아키텍처 결정 기록(ADR)

#

의사결정 문서의 실전 예시입니다:

# ADR-001: API Authentication Strategy

**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team

## Context

Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)

## Decision

We will implement OAuth 2.0 with JWT tokens for API authentication.

## Options Considered

### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens

| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |

**Effort:** Medium (2-3 sprints)

### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies

| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |

**Effort:** Small (1 sprint)

### Option 3: Custom Token System
**Description:** Build our own token-based authentication

| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |

**Effort:** Large (4+ sprints)

## Consequences

- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)

## References

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042

훔쳐 써도 되는 템플릿

#

이걸 출발점으로 삼고 팀에 맞게 덜어내세요.

문제 설명

#

어떤 문제를 해결하려고 하는가? 왜 중요한가? 아무것도 하지 않을 때의 비용은?

배경

#

맥락, 이력, 관련 세부사항을 제공합니다. 관련 문서, 이전 결정, 스파이크 결과에 대한 링크를 포함합니다.

제약사항

#

모든 솔루션이 준수해야 하는 제한이나 요구사항은 무엇인가?

• 예산 제약
• 타임라인 요구사항
• 기술적 제약 (기존 시스템, 스킬셋)
• 규정 준수 또는 보안 요구사항

검토한 솔루션

#

권장사항

#

권장하는 옵션을 명시하고 제약과 트레이드오프를 고려할 때 왜 최선의 선택인지 요약합니다.

결정

#

결정이 내려지면 최종 결정을 문서화합니다. 권장사항과 다르면 이유를 설명합니다.

결과

#

이 결정의 영향은 무엇인가? 필요한 후속 작업은 무엇인가?

액션 아이템

#

참조

#

관련 문서, 외부 리소스, 스파이크 결과, 이전 결정에 대한 링크.

습관으로 정착시키기

#

문서는 일관된 곳에 두세요. 저장소의 전용 폴더든 위키 공간이든 상관없지만, 찾을 수 없는 결정은 존재하지 않는 것과 같습니다. 그리고 가볍게 유지하세요. 쓰는 데 며칠 걸리는 문서는 애초에 쓰이지 않습니다. 코드 주석, 커밋 메시지, 풀 리퀘스트에서 문서를 참조해서 “왜"가 “무엇” 곁에 붙어 있게 하세요. 결정이 대체되면 옛 문서를 지우지 말고 대체됨으로 표시한 뒤 새 결정으로 링크를 겁니다. 역사가 곧 핵심이니까요. 그리고 회고에서 가끔 과거 결정을 돌아보세요. 어떤 결정이 버텨냈고, 어떤 건 지금이라면 다르게 할지.

실패 패턴도 그만큼 예측 가능합니다. 분석 마비에는 기한을 정하고 가진 정보로 결정하는 것이 답입니다. 대부분의 결정은 나중에 다시 볼 수 있으니까요. 의미 있는 비평이 한 번도 안 나오는 도장 찍기 리뷰는 가치 없이 절차만 더합니다. 쓰였는데 실행되지 않는 고아 문서는 문서가 없는 것보다 나쁩니다. 과한 디테일도 조심하세요. 문서가 다룰 것은 “왜"와 “무엇"이지 “어떻게"가 아닙니다. 구현 세부사항은 기술 명세서의 몫입니다. 그리고 이해관계자가 반대하면 그 반대도 기록하세요. 결정은 그대로 갈 수 있지만, 그 반론이야말로 1년 뒤 누군가에게 꼭 필요한 맥락입니다.

다음번 중요한 결정부터 시작해 보세요. 거칠어도 일단 쓰고, 프로세스는 굴리면서 다듬으면 됩니다. 누군가 ADR을 읽는 것만으로 “우리 왜 X를 골랐죠?” 회의가 사라질 때마다, 그만큼의 시간이 팀에게 돌아옵니다.

참고 자료

#

이 사이트의 관련 글:

• 애자일 소프트웨어 개발에서 스파이크 이해하기 - 큰 결정 전에 스파이크로 정보 모으기
• 회고: 피드백 루프의 힘 - 지속적 개선의 일부로 과거 결정 돌아보기
• API 계획 - 의사결정 문서의 사고방식을 API 설계에 적용하기
• 프로젝트 관리를 위한 GitHub - 의사결정 문서를 코드 옆에 두고 관리하기

외부 리소스:

• Documenting Architecture Decisions - Michael Nygard - ADR을 대중화한 원본 글
• ADR GitHub Organization - ADR을 위한 도구, 템플릿, 예시
• Design Docs at Google - Google의 설계 문서 접근법
• RFC Process at Rust - Rust 언어의 잘 정비된 RFC 프로세스
• Spotify’s Decision Record Template - Spotify가 ADR을 쓰는 시점에 대한 글