Baukaalm/system-design-first

시스템 설계 우선

대부분의 작업은 무엇을 구축할지 설명하지만, 프로덕션에서 문제없이 작동할지를 결정짓는 질문들은 숨겨져 있습니다: 사용자 수, 호출 빈도, 데이터 양, 의존성이 느릴 때 어떤 일이 발생하는지, 두 작성자가 경쟁할 때 진실의 소유권은 누구에게 있는지. 이 스킬은 코드를 작성하기 전에 이러한 질문들을 명시적으로 드러내며, 작업 작성자가 읽고 반박할 수 있는 형태로 제시합니다.

프로세스는 다음과 같습니다: 범위 → 추정 → 고수준 설계 → 심층 분석 → 마무리. 실제 작업에 적용되며, 기존 코드베이스, 의도가 있는 작성자, 예산이 존재합니다. 목표는 시스템 관점에서 기능을 명확하게 파악하는 것입니다.

사용자가 작성하는 언어로 응답하십시오. 개요는 당신이 아닌 사용자를 위한 것입니다.

1. 먼저 깊이를 측정하세요

오타 수정에 과도한 설계를 적용하는 것은 결제 흐름에 설계가 부족한 것만큼 잘못입니다. 수준을 선택하고, 한 줄로 설명한 후 그에 따라 시간을 투자하세요.

수준	일반적인 작업	산출물
L0 – 사소함	복사 변경, 이름 변경, 스타일 조정, 로컬 수정이 가능한 명백한 버그	추가 산출물 없음. 숨겨진 위험이 있다면 최대 한 문장으로 언급("이 레이블은 CDN에서 24시간 동안 캐시됨"). 그런 다음 작업을 바로 수행합니다.
L1 – 로컬 변경	새 필드, 새 필터, 작은 엔드포인트 변경, 훅, 쿼리 조정	인라인 설계 확인 3-7줄: 영향을 받는 부분, 담당하는 부하, 문제를 일으킬 수 있는 한 가지(N+1, 캐시 무효화, 페이지네이션, 멱등성). 그런 다음 구현합니다.
L2 – 기능	데이터 흐름이 있는 새 화면, 새 엔드포인트 + 스토리지, 알림, 검색, 내보내기, 타사 통합	설계 개요(4절), 약 1페이지 분량. 그런 다음 개요에 따라 구현합니다.
L3 – 하위 시스템	새 서비스, 실시간 채널, 이벤트 파이프라인, 멀티 테넌트 데이터 모델, 핫 경로 마이그레이션, "스케일"이 포함된 모든 작업	전체 개요 + 위험한 구성 요소별 심층 분석, 고려된 대안, 마이그레이션 경로, 출시 후 측정할 항목.

작업 수준을 높이는 신호: 사용자 대면 지연 시간, 동시 작성자, 팬아웃(하나의 이벤트 → 많은 수신자), 테이블 또는 목록의 무제한 증가, 타사 속도 제한, 금전, 개인식별정보(PII), 예약 실행되는 모든 것, 또는 분명히 유지될 "임시" 솔루션. 수준을 낮추는 신호: 소수의 사용자만 있는 내부 도구, 영구히 메모리에 맞는 데이터, 기능 플래그가 있는 킬 스위치 실험.

사용자가 명시적으로 설계 검토나 심층 분석을 요청하면 크기와 관계없이 L3로 처리합니다.

2. 프로세스, 단계별

다음 순서대로 진행하십시오. L1의 경우 몇 줄로 압축하고, L2/L3의 경우 각 단계가 개요의 섹션이 됩니다. references/framework.md에는 각 단계의 질문 체크리스트가 있습니다. 세션에서 처음 L2+ 프로세스를 실행할 때 읽어보십시오.

1단계 — 이해 및 범위 설정

• 기능을 시스템이 보는 관점에서 한 문단으로 다시 설명하십시오: 행위자, 트리거, 입력, 출력, 부작용.
• 기능적 요구사항(무엇을 하는지)과 비기능적 요구사항(얼마나 잘: 규모, 지연 시간, 가용성, 일관성, 내구성, 보안, 비용, 운영성)을 분리하십시오. 작업은 거의 항상 두 번째 유형을 언급하지 않습니다. 제품 맥락에서 추론하고 추론된 것임을 명시하십시오.
• 범위 외 항목을 기록하여 개요가 조용히 확장되지 않도록 하십시오.
• 작성자의 의도를 수집하십시오: 작업 텍스트, PR 설명, 댓글, 연결된 설계, 기존 ADR, 이 저장소에서 유사한 기능이 구축된 방식. 작성자는 일반적으로 머릿속에 설계를 가지고 있습니다. 이를 대체하지 말고 표면화하십시오.
• 설계를 실질적으로 변경하는 질문(예: "1초 이내에 보여야 합니까, 아니면 1분도 괜찮습니까?")만 사용자에게 물어보십시오. 그 외의 모든 것은 가정을 명시하고 진행하십시오. 가정은 개요에 포함됩니다.

2단계 — 추정

숫자는 의견을 결정으로 바꿉니다. 작업에 추정치가 없더라도 어림잡아 추정하십시오. references/estimation.md에는 참조 숫자(지연 시간 사다리, 2의 거듭제곱, 가용성 나인, 노드당 용량)와 작업 예제가 있습니다.

• 사용자 / 테넌트 → 일간 활성 사용자 → 일간 작업 → 평균 및 최대 QPS(최대는 일반적으로 평균의 2~5배, "모든 사용자가 오전 9시에 앱을 열음"과 같은 버스트 흐름의 경우 더 높음).
• 읽기/쓰기 비율, 페이로드 크기 → 일/년당 스토리지, 대역폭.
• 성장: 제품이 성공한다면 12개월 후의 숫자는?
• 실제 숫자(분석, DB 행 수, 기존 대시보드, 구성 제한)가 있는 경우 이를 사용하고 출처를 인용하십시오. 그렇지 않으면 범위를 제공하고 가정으로 표시하십시오.

그런 다음 숫자를 사용하여 패턴을 정당화하는 것이 아니라 배제하십시오: "30 쓰기/초에서 Postgres 테이블에 인덱스가 있으면 충분합니다. 큐는 처리량이 아니라 재시도와 이메일 제공자로부터의 분리가 필요할 때만 필요합니다."

3단계 — 현재 설계 매핑(As-Is)

설명하기 전에 코드를 읽으십시오. 실제 파일, 모듈, 테이블, 엔드포인트, 작업, 캐시, 큐의 이름을 지정하십시오. 구성 요소를 임의로 만들지 마십시오.

• 기능이 영향을 미치는 구성 요소는 무엇입니까? 짧은 텍스트 다이어그램으로 데이터 흐름을 그리십시오(클라이언트 → BFF → 서비스 → Postgres, 이벤트 → 큐 → 워커).
• 상태는 어디에 있으며 누가 소유합니까(DB, 캐시, 클라이언트 저장소, URL)?
• 재사용할 수 있는 기존 프리미티브는 무엇입니까(아웃박스 테이블, 작업 실행기, 쿼리 캐시, WebSocket 허브, 공유 Pagination 컴포넌트)?
• 기능이 상속하는 핫 경로, 알려진 병목 현상, 기존 SPOF, 현재 제한(속도 제한, 페이지 크기, 타임아웃).
• 프론트엔드 작업의 경우 As-Is는 여전히 시스템입니다: 데이터 페칭 레이어, 캐시 정책, 번들 경계, 실시간 전송 — references/frontend.md를 참조하십시오.

4단계 — 대상 설계 제안(To-Be)

작성자의 의도에서 시작하십시오. 그것이 타당하다면 그렇게 말하고 다듬으십시오. 숫자나 잘 알려진 실패 모드와 충돌하는 경우, 충돌과 그 결과를 보여주고 이를 해결하는 가장 작은 변경을 제안하십시오. 작성자가 결정합니다. 당신의 역할은 트레이드오프를 명확하게 보여주는 것입니다.

• 텍스트 다이어그램 형태의 고수준 설계, API 계약(엔드포인트 / 이벤트 / 메시지 형태 포함) 및 데이터 모델(테이블, 키, 인덱스, 보존 정책).
• 중요하지 않은 모든 선택에 대해 패턴과 거절한 대안을 2단계의 숫자와 연결된 이유와 함께 명명하십시오. references/patterns.md는 카탈로그입니다: 스케일링, 캐싱, 비동기/큐, 데이터 저장소 및 일관성, API 스타일 및 실시간 전송, 속도 제한, ID 생성, 안정성, 관찰 가능성 — 각각 "사용 시기 / 피해야 할 시기 / 트레이드오프"가 포함됩니다.
• 기능을 적합한 표준 시스템에 매핑하십시오("이것은 알림 시스템입니다: 큐 + 채널별 워커 + 중복 제거", "이것은 뉴스피드 팬아웃입니다", "이것은 속도 제한기입니다"). 카탈로그의 마지막 섹션에는 표준 형태와 표준 구성 요소가 나열됩니다. 비유를 통해 독자에게 알려진 참조 지점과 그러한 시스템이 일반적으로 필요로 하는 것에 대한 체크리스트를 제공합니다.
• 저장소의 기존 프리미티브와 숫자를 충족하는 여유 공간이 있는 가장 간단한 설계를 선호하십시오. 어떤 업그레이드가 연기되었으며 어떤 신호가 이를 트리거할 것인지 명시적으로 말하십시오("이 쿼리의 p95가 200ms를 초과하거나 테이블이 5000만 행을 초과하면 읽기 복제본을 추가하십시오").

5단계 — 고장날 수 있는 부분에 대한 심층 분석

L2의 경우 위험한 부분 한두 개를 선택하십시오. L3의 경우 모두 검토하십시오. 일반적인 질문, 문제를 일으키는 빈도 순서:

1. 동시성 및 멱등성 — 이중 제출, 재시도, 두 명의 작성자, 최소 한 번 전달. 멱등성 키는 어디에 있습니까? 고유 제약 조건은 무엇입니까?
2. 일관성 — 누가 오래된 데이터를 얼마나 오래 읽습니까? 그것이 허용 가능합니까? 캐시 무효화 경로는? 자신의 쓰기 읽기(Read-your-writes)는?
3. 의존성 실패 — 제공자 다운, 큐 지연, 원격 모듈 로드 실패. 타임아웃, 지터가 있는 재시도, 회로 차단기, 우아한 성능 저하, 사용자가 보는 것.
4. 핫스팟 — 핫 키, 유명 테넌트, 무제한 목록, N+1, 전체 테이블 스캔, 누락된 인덱스, 캐시 만료 시 떼몰이(Thundering herd).
5. 성장 — 무제한으로 성장하는 테이블/목록/큐, 보존, 아카이빙, 페이지네이션(오프셋 대비 커서), 파티셔닝.
6. 마이그레이션 및 롤아웃 — 백필, 이중 쓰기 기간, 기능 플래그, 롤백 경로, 하위 호환 가능한 계약 변경.
7. 보안 및 개인정보 보호 — 데이터 수준 인증(테넌트 격리), 로그/큐 속 PII, 공개 엔드포인트 속도 제한, 입력 검증.
8. 관찰 가능성 — 작동을 증명하는 메트릭(SLI), 작동하지 않을 때 발생하는 경보, 단일 요청 디버깅을 위해 기록할 로그.

6단계 — 마무리, 시각화 제안

다이어그램은 토큰을 소비하므로 옵트인입니다. 개요 자체는 한 줄 텍스트 흐름(클라이언트 → API → Postgres)만 사용합니다.

L2 및 L3의 경우, 개요를 사용자의 언어로 된 한 가지 질문과 함께 미해결 질문을 나열하여 마무리하십시오:

아키텍처를 그릴까요? 1 — 터미널에 As-Is / To-Be 다이어그램 · 2 — 설계 폴더 추가(Mermaid + architecture.html) · 3 — 아니오

• 사용자가 1 또는 2를 선택한 후에만 references/visualization.md에 따라 그리십시오. 구현을 시작하기 위해 답변을 기다리지 마십시오. 사용자가 답변 없이 넘어가면 "아니오"로 간주합니다.
• 사용자가 이미 다이어그램, 그림, 시각화 또는 설계 폴더를 요청한 경우에만 질문을 건너뛰고 바로 그리십시오.
• 아무도 답변할 수 없는 경우(비대화형 실행, CI, 평가), 그리지 말고 묻지 마십시오. 다이어그램은 요청 시 제공 가능하다고 한 줄로 언급하십시오.
• L0 또는 L1에서는 절대 제공하지 마십시오.

개요(다음 절)를 생성한 후 작업을 계속하십시오: 개요에 따라 구현하고, 개요를 PR/MR 설명에도 포함시키고, 미해결 질문을 조용히 결정하지 말고 작성자를 위해 나열하십시오.

3. 판단 규칙

• 패턴보다 숫자가 우선. 추정 없이 Kafka, 샤딩, CQRS, 전용 캐시 클러스터 또는 마이크로서비스를 권장하지 마십시오. 단순함은 기능입니다. 복잡성은 그 자리를 얻기 위해 노력해야 합니다.
• 설명하되 강의하지 마십시오. 각 권장 사항에는 작성자가 확인할 수 있는 한 문장의 "이유"가 수반됩니다. 표준 시스템에 대한 비유는 환영이지만, 유행어 목록은 환영하지 않습니다.
• 작성자의 설계를 존중하십시오. 의견 차이는 "X는 Z 부하에서 Y를 유발합니다. 가장 저렴한 수정은 W입니다"와 같이 제시하십시오. 작성자가 여전히 자신의 방식을 선호한다면, 그들의 방식을 구현하고 개요에 위험을 기록하십시오.
• 기존 코드는 증거입니다. 읽으십시오. 존재하지 않는 구성 요소를 설명하는 개요는 개요가 없는 것보다 나쁩니다.
• 필수와 있으면 좋은 것을 분리하십시오. 각 권장 사항을 "지금 필요", "출시 전 필요" 또는 "약 N명의 사용자 시점에 필요"로 표시하십시오.
• 프런트엔드도 중요합니다. 클라이언트 캐싱, 페이지네이션, 낙관적 업데이트, 실시간 전송, 번들 경계 및 장애 격리는 시스템 설계입니다. references/frontend.md는 각 단계의 클라이언트 측 버전을 다룹니다.
• 사용자의 언어와 어휘를 따르십시오. 팀이 패턴 이름을 번역해서 사용하면 번역하십시오. 처음에는 영어 용어를 괄호 안에 유지하십시오.

4. 설계 개요

L2 및 L3에 이 구조를 사용하십시오. 제목은 유지하십시오. 섹션이 정말로 비어 있는 경우에만 섹션을 삭제하고 한 줄로 그렇게 말하십시오. L2의 경우 약 1페이지를 목표로 하십시오. references/brief-template.md에는 채워진 예제와 간결한 L1 인라인 형식이 있습니다.

# 설계 개요: <기능>

**깊이:** L2 · **상태:** 제안 · **작성자 의도:** <한 줄>

## 1. 범위
기능적: ...
비기능적(명시되지 않는 한 추론됨): 규모 · 지연 시간 · 가용성 · 일관성 · 보안 · 비용
범위 외: ...
가정: ...

## 2. 추정
| 메트릭 | 현재 | +12개월 | 출처 |
| --- | --- | --- | --- |
| DAU / 테넌트 | | | |
| 최대 QPS (읽기 / 쓰기) | | | |
| 스토리지 증가량 | | | |
결론: <숫자가 허용/금지하는 것>

## 3. 현재 설계 (As-Is)
<한 줄 텍스트 흐름> · 상태 소유권 · 재사용 가능한 프리미티브 · 상속된 제한
파일: ...

## 4. 대상 설계 (To-Be)
<한 줄 텍스트 흐름> · API 계약 · 데이터 모델 · 표준 시스템 비유
패턴 선택: <패턴> — <이유> 때문에; <대안>은 <이유> 때문에 거절됨.

## 5. 위험 및 심층 분석
1. <위험> → 완화 (지금 필요 / 출시 전 / N명의 사용자 시점)
...

## 6. 롤아웃, 마이그레이션, 관찰 가능성
플래그, 백필, 롤백 · SLI + 경보 · 기록할 로그

## 7. 작성자를 위한 미해결 질문
- ...
- 아키텍처를 그릴까요? 1 — 터미널 다이어그램 · 2 — 설계 폴더 추가 · 3 — 아니오

## 8. 구현 계획
각각 리뷰하기에 충분히 작은 순서화된 단계.

5. 참고 자료 — 언제 읽을지

파일	읽을 때
references/framework.md	세션에서 첫 L2+ 프로세스: 단계별 질문 체크리스트, NFR 목록, 작성자 의도 추출 방법, 분석 안티패턴.
references/estimation.md	숫자가 필요할 때마다: 지연 시간 사다리, 나인, 노드당 용량, QPS/스토리지 계산, 작업 예제.
references/patterns.md	패턴 선택 또는 정당화; 기능을 표준 시스템에 매핑(채팅, 피드, 알림, 검색 자동 완성, 파일 동기화, 속도 제한기, KV 저장소, ID 생성기, 결제, ...). 목차 포함.
references/frontend.md	작업이 UI / SPA / 마이크로 프론트엔드 변경인 경우: 데이터 페칭 캐시, 페이지네이션, 실시간, 번들 경계, 장애 격리, 클라이언트 측 숫자.
references/brief-template.md	개요 작성: 전체 L2 예제 및 간결한 L1 인라인 형식.
references/visualization.md	사용자가 다이어그램을 요청한 후에만(6단계). 그리기: 터미널 상자 다이어그램 규칙, Mermaid 규칙, 설계 폴더 레이아웃, assets/architecture.html 채우는 방법.