의사결정 문서가 이걸 해결합니다. 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을 쓰는 시점에 대한 글

B2B SaaS를 하다 보면 언젠가는 반드시 테넌시 문제에 부딪힙니다. 보통은 큰 잠재 고객이 “우리 데이터를 다른 회사와 분리해서 둘 수 있나요?“라고 묻는 날이죠. 저도 이 논의를 여러 번 가까이서 지켜봤습니다. 답은 기본적으로 둘 중 하나입니다. 고객마다 전용 인스턴스를 주거나(싱글 테넌트, 멀티 인스턴스), 모두를 하나의 공유 인스턴스에서 운영하거나(멀티 테넌트, 싱글 인스턴스). 어느 쪽이 정답인 건 아닙니다. 그저 망가지는 방식이 다를 뿐입니다.

인프라 설계

#

싱글 테넌트, 멀티 인스턴스

#

이 방식의 매력은 결국 격리입니다. 장점 대부분이 여기서 나옵니다. 고객 데이터가 각자 독립된 환경에 있으니 보안 리뷰와 컴플라이언스 이야기가 훨씬 수월해집니다. 배포 사고나 무거운 워크로드가 터져도 전체가 아니라 고객 한 곳만 영향을 받습니다. 인스턴스별로 독립적으로 확장하고 튜닝하고 커스터마이징할 수 있고, 리소스가 전용이라 옆 테넌트가 뭘 하든 내 성능이 흔들리지 않습니다. 유지보수도 고객 단위로 잡을 수 있어서 다운타임이 작고 국소적입니다. 가격 설계만 잘하면 인프라 비용을 테넌트별 실제 사용량에 맞출 수도 있습니다.

대가는 모든 걸 N벌씩 운영하게 된다는 점입니다. 리소스 오버헤드가 쌓이고, 인스턴스 간 설정이 조금씩 어긋나고, 전체 플릿의 버전과 데이터를 맞추는 일 자체가 하나의 프로젝트가 됩니다. 확장, 격리, 비용 관리 문제는 사라지는 게 아니라 늘어납니다.

멀티 테넌트, 싱글 인스턴스

#

이게 기본값인 데는 이유가 있습니다. 배포도 하나, 백업할 데이터베이스도 하나, 프로덕션 버전도 하나. 리소스 효율이 좋고 운영이 단순하며, 업데이트와 보안 패치가 모든 고객에게 동시에 적용됩니다.

어려운 부분은 공유의 이면입니다. 한 테넌트가 무겁게 쓰면 모두의 성능이 끌려 내려가고, 고객별 커스터마이징에는 한계가 있습니다. 그리고 데이터 격리가 인프라가 아니라 애플리케이션 코드의 책임이 되기 때문에, 버그 하나가 테넌트 간 데이터 유출로 이어질 수 있습니다. 확장성 병목은 모든 고객에게 동시에 오고, “이 고객만"이라는 영향 범위가 없어지는 만큼 유지보수에도 더 신경을 써야 합니다.

SaaS 솔루션에 대한 자세한 정보 - 멀티 인스턴스 vs. 멀티 테넌트 아키텍처

멀티 테넌트 vs 멀티 인스턴스

#

같은 선택을 ‘멀티 테넌트 vs 멀티 인스턴스’라고 부르는 경우도 많은데, 같은 것을 반대편에서 본 것뿐입니다. ‘테넌트’는 고객 이야기로, 소프트웨어 한 벌을 몇 고객이 함께 쓰느냐입니다. ‘인스턴스’는 배포 이야기로, 소프트웨어를 몇 벌 돌리느냐입니다. 싱글 테넌트 제품은 고객마다 한 벌씩 돌리는 멀티 인스턴스 배포이고, 멀티 테넌트 제품은 보통 모두가 함께 쓰는 싱글 인스턴스입니다. 그러니 누군가 멀티 인스턴스를 원한다고 하면, 싱글 테넌트를 원한다는 뜻입니다.

실제로는 두 칸짜리 선택이라기보다 스펙트럼에 가깝고, 진짜 결정은 대부분 데이터베이스에서 내려집니다. 가장 많이 공유하는 쪽은 모든 고객의 행을 같은 테이블에 넣고 tenant_id 컬럼을 둔 다음, 모든 쿼리에서 그걸로 거르는 방식입니다. 운영 비용은 가장 싸고, 실수하기도 가장 쉽습니다. 한 단계 나아가면 공유 데이터베이스 안에 고객마다 스키마를 따로 두는 방식입니다. 분리가 깔끔해지고 고객 단위 백업도 가능하지만, 마이그레이션을 스키마 수만큼 돌려야 합니다. 더 나아가면 애플리케이션은 공유하고 데이터베이스만 고객마다 따로 두는 방식이 있습니다. 고객마다 스택 전체를 돌리지 않고도 데이터를 확실히 분리할 수 있어서 많이 쓰이는 절충안이죠. 반대쪽 끝이 완전한 싱글 테넌트로, 애플리케이션과 데이터베이스 모두 전용입니다. AWS의 SaaS 가이드에서는 양쪽 끝을 사일로(silo)와 풀(pool), 둘을 섞은 것을 브리지(bridge)라고 부르는데, 고객사 보안팀에 구성을 설명할 때 쓰기 좋은 말입니다.

싱글 테넌트 vs 멀티 테넌트 한눈에 비교

#

언제 무엇을 쓸까

#

특별한 이유가 없다면 멀티 테넌트로 가세요. 적은 금액을 내는 고객이 많을 때, 사용자가 직접 가입할 때, 그리고 환경 서른 개를 떠안으면 팀이 버티지 못할 만큼 작을 때 멀티 테넌트가 맞는 기본값입니다.

싱글 테넌트가 그 수고만큼의 값을 하는 건 몇 가지 경우입니다. 의료, 금융, 공공 분야 고객은 데이터를 물리적으로 분리하거나 특정 국가에 두라고 요구하는 경우가 많은데, 보안 리뷰에서 거기에 정직하게 답하는 가장 간단한 방법이 전용 인스턴스입니다. 엔터프라이즈 계약을 맺은 대형 고객 몇 곳이라면 전용 스택 비용을 감당할 수 있고, 애초에 그걸 기대하는 경우도 많습니다. 그리고 고객마다 릴리스 일정을 따로 가져가거나, 버전을 고정하거나, 깊게 커스터마이징해야 한다면, 인스턴스를 나누는 건 오버헤드가 아니라 파는 제품의 일부가 됩니다.

결국 대부분의 팀은 둘 다 하게 됩니다. 거의 모든 고객에게는 멀티 테넌트 제품을, 필요하고 비용도 낼 일부 고객에게는 엔터프라이즈 요금제로 전용 인스턴스를요. 멀티 테넌트 버전에서 처음부터 모든 곳에 테넌트 ID를 달아 두면, 나중에 고객 하나를 전용 데이터베이스로 옮기는 일은 재작성이 아니라 마이그레이션으로 끝납니다.

멀티 테넌트 격리를 쉽게 깨지지 않게 하기

#

멀티 테넌트에서 가장 무서운 버그는 테넌트 필터를 빠뜨린 쿼리입니다. 실패하지도 않습니다. 다른 고객의 데이터를 조용히 돌려줄 뿐이고, 코드 리뷰가 이걸 전부 잡아내지도 못합니다. Postgres를 쓴다면 행 수준 보안(RLS)으로 이 확인을 데이터베이스로 옮길 수 있습니다. 필터를 빠뜨린 쿼리라도 현재 고객의 행만 보이게 되죠.

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON invoices
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

그다음 각 요청이 트랜잭션 안에서 SET LOCAL app.tenant_id = '…'로 테넌트를 지정합니다. 이렇게 하면 커넥션 풀의 연결이 앞 고객의 ID를 다음 요청으로 넘기지 않고, 지정을 깜빡한 요청은 행 대신 오류를 받습니다. 주의할 점은 두 가지입니다. 앱은 테이블 소유자가 아닌 역할로 접속해야 합니다. 소유자는 FORCE ROW LEVEL SECURITY를 추가하지 않는 한 이 정책을 건너뛰거든요. 그리고 슈퍼유저로는 절대 접속하지 마세요. 슈퍼유저는 무조건 건너뜁니다.

싱글 테넌트, 어디서부터 시작할까

#

싱글 테넌트로 간다면, 이게 “관리 가능한 일"이 될지 “슬로모션 재난"이 될지는 도구가 결정합니다. 서른 개의 환경을 손으로 돌볼 수는 없으니까요.

핵심은 컨테이너와 Infrastructure as Code입니다. Docker로 모든 테넌트에 동일한 형태로 앱을 패키징하고, Kubernetes로 그 많은 인스턴스의 배포와 확장을 처리합니다. Terraform, Pulumi, AWS CloudFormation으로 테넌트 스택 전체를 코드로 정의해 두면, 31번째 고객 셋업이 주말을 갈아 넣는 일이 아니라 풀 리퀘스트 하나가 됩니다. VM 세계에 더 가깝다면 Ansible, Chef, Puppet 같은 구성 관리 도구가 같은 역할을 해줍니다. CI/CD 파이프라인(Jenkins, GitLab CI/CD)은 평소보다 훨씬 중요해집니다. 모든 릴리스를 일일이 붙어 있지 않고도 전체 인스턴스에 배포해야 하거든요.

그다음부터는 제품의 형태에 달렸습니다. 일부 워크로드는 서버리스(AWS Lambda, Azure Functions)로 서버 계층 자체를 없앨 수 있습니다. Amazon RDS나 Azure SQL Database 같은 관리형 데이터베이스는 테넌트마다 DB를 손으로 관리하는 고행에서 구해줍니다. 모니터링(Prometheus, Grafana, New Relic)은 플릿이 생기는 순간부터 선택이 아닙니다. 어느 인스턴스가 아픈지는 고객이 말해주기 전에 알아야 하니까요. 인증은 Auth0나 Okta 같은 IAM 서비스에 맡기면 테넌트마다 새로 만들 필요가 없습니다. 어떤 언어를 쓰든 이런 배관 작업을 덜어주는 SaaS 지향 프레임워크나 라이브러리가 있을 것이고, 호스팅은 AWS, Azure, Google Cloud Platform 같은 대형 클라우드 어디든 무리 없이 받아줍니다.

첫날부터 이 목록을 전부 살 필요는 없습니다. 컨테이너와 IaC로 시작해서, 테넌트가 쌓이는 만큼 모니터링과 IAM을 더하고, 나머지는 실제로 아픈 순서대로 고르면 됩니다.

짧게 정리하면

#

싱글 테넌트, 즉 멀티 인스턴스는 고객마다 애플리케이션과 데이터베이스를 따로 두는 방식입니다. 강한 격리와 고객별 제어를 얻는 대신 운영할 플릿이 생깁니다. 멀티 테넌트는 하나를 모두가 함께 쓰는 방식으로, 저렴하고 단순하지만 격리는 코드로 보장합니다. 대부분의 제품은 멀티 테넌트로 시작해서, 모든 곳에 테넌트 ID를 두고 데이터베이스가 그걸 강제하게 한 뒤, 필요하고 비용도 낼 일부 고객에게만 전용 인스턴스를 주는 게 좋습니다. 싱글 테넌트로 운영한다면 관리 가능한 상태를 지켜주는 건 컨테이너와 Infrastructure as Code입니다.