이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 요구사항 리뷰에서 빠지면 안 되는 항목은 무엇인가?
- 기능, 비기능, 제약, 가정, 검증 계획을 하나의 문서로 어떻게 고정하는가?
- 요구사항 리뷰 템플릿은 성능, 정합성, 장애 격리, 운영 복잡도 판단을 어떻게 돕는가?
개요
요구사항 리뷰 템플릿은 문서 양식을 채우기 위한 것이 아니다.
설계자가 빼먹기 쉬운 질문을 강제로 드러내는 장치다.
특히 System Design에서는 “무엇을 만들 것인가”보다 “어떤 조건에서 성공이라고 볼 것인가”가 중요하다.
템플릿은 기능, 비기능, 제약, 가정, API 계약, 상태, 데이터, 장애, 운영 지표를 한 번에 묻는다.
템플릿의 원칙
좋은 템플릿은 길이가 아니라 판단력을 만든다.
- 기능과 비기능을 분리한다.
- 성공, 실패, 중복, 취소, pending 상태를 묻는다.
- SLO와 측정 위치를 묻는다.
- 제약과 가정을 분리한다.
- 데이터 owner와 보존 기간을 묻는다.
- 장애 때 줄일 기능을 묻는다.
- 검증되지 않은 항목을 action item으로 남긴다.
이 항목이 없으면 리뷰는 취향 싸움이 되기 쉽다.
요구사항 리뷰 템플릿
## 1. 기능 범위
- 사용자 결과:
- caller:
- command API:
- query API:
- 제외 범위:
- 상태 전이:
## 2. API 계약
- 성공 응답:
- 실패 응답:
- 중복 요청 처리:
- pending/degraded 응답:
- 권한 실패:
## 3. 비기능 요구사항
- latency SLO:
- throughput/peak:
- availability:
- consistency:
- retention:
- security/audit:
## 4. 데이터와 상태
- 최종 진실의 원천:
- 저장 데이터:
- 파생 데이터:
- 보존/삭제:
- migration 영향:
## 5. 제약과 가정
- 확정 제약:
- 임시 가정:
- 검증 방법:
- 검증 실패 시 전환 조건:
## 6. 장애와 운영
- 주요 실패 모드:
- fallback/degradation:
- retry/DLQ:
- metric/alert:
- rollback:
- owner:이 템플릿은 모든 항목을 길게 쓰라는 뜻이 아니다.
빈 항목이 있으면 아직 모르는 것이 무엇인지 드러내라는 뜻이다.
알림 기능 리뷰 예시
사용자 결과:
- 관리자는 캠페인을 예약할 수 있다.
- 사용자는 수신 거부를 설정할 수 있다.
- 발송 실패 건은 운영자가 재처리할 수 있다.
제외 범위:
- 발송된 메시지 회수는 지원하지 않는다.
- provider 자체 중복 발송은 내부에서 감지 후 보정한다.
비기능:
- 캠페인 접수 API p95 200ms
- 예약 발송 시작 지연 60초 이하 99%
- 발송 이력 1년 보존
- 수신 거부 반영은 strong consistency이 예시는 구조를 바로 강제한다.
접수 API는 빠르게 끝나야 하므로 실제 발송은 queue 뒤로 간다.
수신 거부는 strong consistency가 필요하므로 오래된 cache를 그대로 쓰면 안 된다.
발송 이력 1년 보존은 table partition이나 보관 저장소를 검토하게 만든다.
리뷰 질문
리뷰어는 다음 질문을 던진다.
| 질문 | 놓치면 생기는 문제 |
|---|---|
| 이 기능의 성공 기준은 무엇인가? | API가 너무 많은 일을 약속한다 |
| 사용자가 기다려야 하는 작업은 무엇인가? | 동기 경로가 길어진다 |
| 중복 요청이 들어오면 어떻게 되는가? | 중복 주문, 중복 발송 |
| stale data를 허용하는가? | cache/read model 판단 불가 |
| 장애 때 포기할 기능은 무엇인가? | 전체 장애로 번진다 |
| 어떤 숫자가 가정인가? | capacity와 비용 판단이 흔들린다 |
| 어떤 지표로 검증하는가? | 운영 중 성공 여부를 모른다 |
질문은 답을 압박하기보다 모르는 것을 분리하기 위한 것이다.
승인 기준
요구사항 리뷰를 통과하려면 최소한 다음은 채워져야 한다.
- 핵심 command와 query가 구분되어 있다.
- 성공 응답과 실패 응답이 있다.
- 비기능 요구사항이 숫자나 등급으로 표현되어 있다.
- 제약과 가정이 분리되어 있다.
- 가정 검증 방법이 있다.
- 주요 실패 모드와 fallback 방향이 있다.
- 관측 지표가 적혀 있다.
하나라도 비어 있으면 설계를 멈추라는 뜻은 아니다.
대신 risk와 owner를 남기고 다음 검증 일정을 정해야 한다.
설계 축 연결
템플릿 항목은 설계 축과 연결된다.
| 템플릿 항목 | 연결되는 설계 축 |
|---|---|
| latency SLO | 성능, timeout, cache, 비동기 분리 |
| consistency | 정합성, lock, idempotency, read model |
| fallback | 장애 격리, degradation, 사용자 계약 |
| retention | 운영 복잡도, storage, 분리 보관, 삭제 |
| throughput | scale out, queue, partition, rate limit |
| security/audit | 권한, 로그, compliance, 비용 |
따라서 템플릿은 문서가 아니라 설계 판단의 index다.
위험 신호
- 템플릿에 기능 설명만 있고 비기능 항목이 비어 있다.
- SLO는 있는데 측정 위치와 제외 범위가 없다.
- 제약과 가정이 한 줄에 섞여 있다.
- 장애와 rollback 항목을 배포 직전에 채우려 한다.
- API 성공 응답이 실제 처리 완료와 접수를 구분하지 않는다.
- owner가 없어 검증되지 않은 가정이 방치된다.
개인 프로젝트 기준
개인 프로젝트에서는 템플릿을 가볍게 줄여도 된다.
필수 항목은 다음이다.
- 기능 범위
- 제외 범위
- 핵심 API 계약
- 예상 트래픽
- 실패 시나리오
- 생략한 컴포넌트와 전환 조건
이 정도만 있어도 설계가 “만든 기능 소개”에서 “판단 문서”로 바뀐다.
기업 운영 기준
기업 운영에서는 템플릿이 의사결정 기록이 된다.
- 제품 owner가 기능 범위를 승인한다.
- 플랫폼/인프라가 capacity와 SLO를 리뷰한다.
- 보안/법무가 제약을 확인한다.
- 운영팀이 alert와 runbook을 확인한다.
- 개발팀이 migration과 rollback을 확인한다.
리뷰 결과는 PRD나 설계 문서에 남아야 한다.
장애가 난 뒤 “그때 누가 결정했는가”를 찾는 시간이 줄어든다.
확인 질문
확인 질문
- 확인 질문: 요구사항 리뷰 템플릿의 목적은 무엇인가?
- 답변: 문서 양식을 채우는 것이 아니라 기능, 비기능, 제약, 가정, 장애, 운영 질문을 빠뜨리지 않게 만드는 것이다.
- 확인 질문: 템플릿에서 비어 있어도 되는 항목은 어떻게 처리해야 하는가?
- 답변: 모르는 상태로 숨기지 말고 risk, owner, 검증 일정으로 남겨야 한다.
- 확인 질문: 템플릿이 바꾸는 설계 축은 무엇인가?
- 답변: 성능, 정합성, 장애 격리 기준을 명확히 하지만, 리뷰와 검증, 운영 문서화 복잡도를 추가한다.