05. 설계 문서 작성 템플릿 상세

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

• 설계 문서가 단순 설명이 아니라 결정 기록이 되려면 무엇을 포함해야 하는가?
• 대안, trade-off, 지표, rollback을 어떻게 한 문서에 남기는가?
• 문서 템플릿이 운영 복잡도를 줄이려면 어떤 질문을 강제해야 하는가?

템플릿의 목적

설계 문서 템플릿은 빈칸 채우기 양식이 아니다.

나중에 장애가 나거나 요구사항이 바뀌었을 때 왜 그 결정을 했는지 되짚기 위한 기록이다.

좋은 문서는 Redis 사용이라고 쓰지 않는다.

읽기 p95를 낮추기 위해 상품 요약에 Redis cache를 도입하고, 가격과 재고는 결제 직전 DB 기준으로 재검증한다처럼 선택, 범위, 포기한 것을 함께 적는다.

이 템플릿은 성능, 정합성, 장애 격리, 운영 복잡도를 문서 안에서 강제로 드러내게 한다.

• 성능: 어떤 지표를 얼마나 바꾸려는지 적는다.
• 정합성: 어떤 값을 즉시 맞춰야 하고 어떤 값은 늦어도 되는지 적는다.
• 장애 격리: 어떤 실패를 핵심 경로에서 떼어내는지 적는다.
• 운영 복잡도: owner, alert, rollback, migration, replay 절차를 적는다.

최소 문서 구조

설계 문서는 다음 순서를 따른다.

## 배경과 문제
## 목표와 비목표
## 사용자/API 계약
## 현재 제약과 가정
## 선택지 비교
## 결정
## 바뀌는 설계 축
## 실패 모드와 완화
## 지표와 알림
## 배포, migration, rollback
## 미해결 질문

이 순서는 왜 하는지, 무엇을 하지 않을지, 어떤 선택지가 있었는지 확인한 뒤 결정을 보게 만든다.

배경과 문제

배경에는 구현하고 싶은 기능이 아니라 지금의 실패나 한계를 쓴다.

나쁜 예는 상품 상세 성능 개선을 위해 캐시를 도입한다이다.

좋은 예는 이벤트 시간대 상품 상세 p95가 1.8초까지 올라 주문 전환이 떨어지고, DB read CPU가 85%를 넘는다이다.

문제는 관측 가능한 증거로 적고, 증거가 없으면 실험이나 측정 계획을 먼저 문서화한다.

목표와 비목표

목표는 성공 기준을 가진다.

빠르게 만든다가 아니라 상품 상세 p95를 이벤트 피크에서 500ms 이하로 유지한다가 목표다.

비목표는 범위를 닫는다. 예를 들어 이번 설계에서 결제 금액 정합성은 바꾸지 않는다, 검색 색인 구조는 바꾸지 않는다처럼 적는다.

사용자/API 계약

API 계약은 성공 응답만 쓰지 않는다.

실패, pending, retry 가능, 중복 요청, 권한 거절을 포함한다.

POST /orders
Idempotency-Key: userId:cartId:requestId

{
  "status": "PENDING_PAYMENT",
  "orderId": "ord_123",
  "retryAfterSeconds": 10
}

사용자가 어떤 상태를 볼 수 있는지 정해져야 retry, timeout, queue, polling을 설계할 수 있다.

제약과 가정

가정은 숨기지 않는다.

다음처럼 숫자와 불확실성을 함께 적는다.

항목	가정	검증 방법
피크 트래픽	이벤트 첫 1분 5,000 RPS	부하 테스트와 이전 이벤트 로그
데이터 크기	상품 100만 개, hot item 1,000개	DB 통계와 access log
외부 의존성	결제 API p95 700ms	provider SLA와 synthetic check
허용 지연	알림은 5분 지연 허용	CS 정책 확인

가정은 틀릴 수 있지만, 어디가 틀렸는지 나중에 확인할 수 있어야 한다.

선택지 비교

선택지는 최소 세 개를 둔다.

현재 구조 유지, 작은 변경, 큰 변경이 기본 축이다.

선택지	장점	비용	탈락 이유 또는 조건
DB 튜닝만 수행	운영 복잡도 증가가 작다.	burst 흡수 한계가 남는다.	hot read가 계속 DB에 집중된다.
Redis cache 도입	읽기 p95를 낮춘다.	stale, invalidation 운영이 생긴다.	가격과 재고는 cache 대상에서 제외한다.
CQRS read model	조회와 쓰기 부하를 분리한다.	동기화, 지연, migration 비용이 크다.	현재 규모에서는 과하다.

비교표는 선택한 기술을 합리화하는 곳이 아니므로 포기한 선택의 장점도 적어야 한다.

결정 기록

결정은 한 문장으로 읽혀야 한다.

예시는 다음과 같다.

결정: 상품 요약 조회에는 Redis cache를 도입한다.
범위: 제목, 이미지, 리뷰 요약, 판매 상태 표시만 cache한다.
제외: 결제 금액, 최종 재고 차감, 쿠폰 적용 가능 여부는 DB 기준으로 검증한다.
이유: 이벤트 피크에서 read p95를 낮추되 과금 정합성은 유지해야 한다.

결정에는 제외 범위가 있어야 한다. 제외 범위가 없으면 다른 팀이 같은 기술을 더 위험한 데이터에 확장할 수 있다.

바뀌는 설계 축

각 문서는 다음 네 축을 명시한다.

축	이번 변경의 영향
성능	어떤 p95, throughput, queue age가 바뀌는가?
정합성	어떤 값이 stale 또는 eventual consistency가 되는가?
장애 격리	어떤 의존성 실패가 핵심 경로에서 분리되는가?
운영 복잡도	어떤 alert, runbook, owner, 배치가 새로 생기는가?

이 표가 비어 있으면 문서가 설명문에 머문 것이다.

실패 모드와 완화

실패 모드는 장애 이름이 아니라 사용자가 겪는 결과로 쓴다.

Redis 장애보다 상품 상세이 느려지고 DB read가 급증한다가 더 좋다.

queue 적체보다 주문 완료 알림이 30분 늦게 도착한다가 더 좋다.

각 실패 모드에는 완화와 포기할 것을 적는다. 모든 기능을 살리는 완화는 대개 없다.

지표와 알림

지표는 컴포넌트 지표와 사용자 지표를 함께 둔다. cache hit rate, queue depth, API p95 하나만으로는 사용자 피해를 설명하기 어렵다.

좋은 지표 예시는 다음과 같다.

• 사용자 영향: 성공률, 거절률, pending 비율, 중복 처리 거절 수
• 포화: DB CPU, lock wait, pool wait, Redis CPU, queue oldest age
• 정합성: mismatch count, stale age, reconciliation 실패 수
• 운영: rollback 실행 시간, DLQ 처리 SLA, alert noise 비율

배포와 rollback

배포 계획은 feature flag 한 줄로 끝나지 않는다.

old code와 new code가 같은 데이터를 읽고 쓸 수 있는지 확인해야 한다.

schema 변경이 있으면 expand, backfill, switch, contract 순서로 쪼갠다.

cache key가 바뀌면 old key TTL과 메모리 증가를 계산한다.

queue 메시지 schema가 바뀌면 old consumer가 새 메시지를 읽을 수 있는지 확인한다.

rollback은 코드 rollback과 데이터 되돌리기를 분리한다.

데이터가 이미 바뀌었다면 코드만 되돌려도 복구되지 않는다.

미해결 질문

미해결 질문은 리뷰 시점에 모르는 것을 명확히 표시하는 장치다. 좋은 미해결 질문은 owner와 마감이 있다.

질문: 이벤트 피크의 실제 hot key 분포를 모른다.
owner: data-platform
due: 2026-07-05
검증: 지난 3회 이벤트 access log에서 top 1,000 product QPS 추출

owner가 없는 질문은 사실상 방치다.

적용 수준

개인 프로젝트 문서는 짧아도 되지만 선택 이유와 포기한 것을 빼면 안 된다.

현재는 단일 DB로 처리한다. 예상 피크가 낮고 정합성 설명이 쉽기 때문이다. 100 RPS 이상에서 DB p95가 500ms를 넘으면 cache를 검토한다 정도면 충분하다.

기업 문서는 API owner, data owner, on-call owner, 고객 공지 owner, dashboard, rollback 권한자를 더 명확히 남겨야 한다.

위험 신호

• 문서가 기술 선택으로 시작하고 문제 증거가 없다.
• 목표는 있지만 비목표가 없다.
• 대안 비교가 선택한 안을 칭찬하는 내용뿐이다.
• 성능, 정합성, 장애 격리, 운영 복잡도 표가 비어 있다.
• rollback이 코드 되돌리기만 의미한다.
• 지표가 평균 latency와 CPU뿐이다.
• 미해결 질문에 owner와 due date가 없다.

확인 질문

확인 질문

• 확인 질문: 설계 문서 템플릿에서 가장 중요한 칸은 무엇인가?
  • 답변: 결정 자체보다 선택 이유, 제외 범위, 바뀌는 설계 축, rollback 조건이다.
• 확인 질문: 이 문서가 바꾸는 설계 축은 무엇인가?
  • 답변: 문서 작성 방식은 직접 성능을 바꾸지 않지만 정합성 기준, 장애 격리 책임, 운영 복잡도 관리를 명시하게 만든다.
• 확인 질문: 템플릿이 실패하는 신호는 무엇인가?
  • 답변: 모든 문서가 같은 문장으로 채워지고 실제 기능의 위험, 지표, owner, 포기한 대안이 보이지 않는 것이다.