Community코딩 & 개발github.com

시스템 설계

분산 시스템을 제약 조건(서비스 경계, 동기/이벤트 기반 통신, 일관성, 장애 동작, 용량)으로부터 설계하거나 평가하고, 각 선택이 가져오는 트레이드오프를 명시합니다. 서비스를 분할하거나 병합할 때, 호출 방식과 이벤트 방식 중 선택할 때, 데이터 위치를 결정할 때, 아키텍처 제안을 검토할 때, 혹은 시스템 설계 질문에 답할 때 사용하세요.

시스템 설계란 무엇인가요?

이 스킬은 분산 시스템 설계에 대한 체계적인 접근 방식을 제공합니다. 서비스 경계 설정, 동기/비동기 통신 패턴 선택, 일관성 모델, 장애 처리, 그리고 용량 추정을 포함한 핵심 설계 결정을 내리는 방법을 안내합니다. Cursor, Claude Code 등 AI 에이전트와 함께 사용할 수 있으며, 개발자가 아키텍처 제안을 검토하거나 시스템 설계 질문에 답변할 때 특히 유용합니다. 스킬은 '제약 조건 우선' 방식을 강조하여, 로드, 데이터, 일관성, 가용성, 지연 시간, 소유권이라는 여섯 가지 주요 제약 조건을 먼저 문서화하도록 합니다. 그런 다음 서비스 경계 설정, 동기/이벤트 기반 통신 결정, 모든 원격 호출에 대한 장애 처리 계획, 일관성 모델 선택을 순서대로 진행합니다. 설계 결과를 구조화된 형식(제약, 설계, 흐름, 장애 시나리오, 트레이드오프, 거부된 대안)으로 문서화하는 방법도 포함되어 있어, AI가 생성한 설계나 기존 아키텍처를 평가할 때 체계적인 평가 기준을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-system-design

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

시스템 설계은(는) 무엇을 하나요?

실패 모드는 구성 요소에 성급히 도달하는 것입니다. 제약 조건을 명명하기 전에 서비스를 명명하는 설계는 상자로 그린 추측일 뿐이며, 달성하려는 목표가 무엇인지 명시되지 않았기 때문에 평가할 수 없습니다.

1. 구성 요소보다 제약 조건 먼저

먼저 다음을 기록하세요. 각 항목은 설계 가능성을 좁혀줍니다:

  • 부하 — 피크 시 초당 요청 수와 읽기/쓰기 비율. 읽기와 쓰기는 완전히 다른 방식으로 확장되므로, 비율이 절대 숫자보다 더 많은 것을 결정합니다.
  • 데이터 — 총 볼륨, 증가율, 단일 항목의 크기.
  • 일관성 — 즉시 정확해야 하는 것과 오래된(stale) 데이터가 허용될 수 있는 것. 거의 '전부'인 경우는 없으며, 엄격해야 하는 작은 부분을 명명하는 것이 나머지를 저렴하게 만듭니다.
  • 가용성 — 이 구성 요소의 장애가 비즈니스에 미치는 영향과 허용 가능한 저하된 동작.
  • 지연 시간 — 사용자 경로에 대한 예산, 평균이 아닌 백분위 수 기준.
  • 소유권 — 각 부분을 배포하고 장애에 대응하는 팀. 팀 경계를 가로지르는 경계는 모든 변경에 조정 비용이 됩니다.

대략적으로 추정하고 그렇게 말하세요. 아키텍처를 선택하기에는 하나의 자릿수(order of magnitude)면 충분하며, 가지고 있지 않은 정밀도는 추구할 가치가 없습니다.

2. 경계

명사(noun)가 아니라 함께 변경되고 누가 데이터를 소유하는지에 따라 분할하세요. 다른 서비스 없이는 배포할 수 없는 서비스는 네트워크 호출이 추가된, 두 개의 저장소에 있는 하나의 서비스입니다.

각 데이터 조각에는 이를 쓰는 단 한 명의 소유자가 있습니다. 다른 모든 사람은 소유자의 인터페이스나 소유자가 게시한 복사본을 통해 읽습니다. 두 서비스가 동일한 테이블에 쓰는 것은 분산 모놀리스(distributed monolith)입니다: 독립적인 배포, 공유된 장애, 불변 조건을 강제할 명확한 위치가 없습니다.

실제 강제력(독립적인 확장, 별도 소유권, 진정으로 다른 가용성 요구 사항)이 분할을 요구할 때까지는 더 적고 더 큰 서비스를 선호하세요. 분할은 수행하는 것은 저렴하지만 되돌리기는 비용이 많이 들며, 모든 경계는 함수 호출을 실패하고, 재시도하고, 두 번 도착할 수 있는 네트워크 호출로 변환합니다.

3. 동기 또는 이벤트 기반

호출자가 답 없이는 진행할 수 없고 사용자가 기다리고 있을 때 동기적으로 호출하세요. 모든 동기 종속성은 해당 다운타임과 지연 시간을 예산에 추가하므로, 이를 세어보세요: 다섯 서비스를 동기적으로 거치는 요청은 그중 어떤 하나보다 가용성이 낮습니다.

시스템의 다른 부분이 어떤 일이 일어났음을 알아야 하지만 호출자가 그 응답을 필요로 하지 않을 때 이벤트를 게시하세요. 이는 가용성을 분리합니다 – 소비자가 다운되어도 쓰기에는 실패하지 않습니다.

비용에 대해 솔직하세요. 이벤트는 최종 일관성, 순서 외 전달 및 중복 전달, 더 이상 하나의 스택 추적에 나타나지 않는 디버깅 경로를 제공합니다. 현대적으로 들리기 때문이 아니라 디커플링이 필요할 때 그 트레이드오프를 취하세요.

쓰기가 로컬 상태를 업데이트 하고 다른 사람에게 알려야 하는 경우, 둘이 분기될 수 없어야 합니다. 로우를 쓰고 브로커를 호출하는 대신 상태 변경과 동일한 트랜잭션에 이벤트를 쓰고 거기서 게시하세요. 이 두 호출 사이의 간격이 손실된 메시지가 있는 곳입니다.

4. 모든 원격 호출은 실패한다고 가정

각각에 대해 사전에 결정하세요:

  • 타임아웃 — 명시적인 타임아웃. 호출자 자체 예산보다 짧아야 합니다. 타임아웃이 없는 호출은 스레드가 쌓이면서 느린 종속성을 장애로 바꿉니다.
  • 재시도 — 일시적 오류에만, 백오프와 지터(jitter)를 적용하고, 연산이 멱등성(idempotent)일 때만. 멱등성이 없는 쓰기를 재시도하면 중복됩니다; 모든 클라이언트의 동기화된 재시도는 작은 문제를 폭주(stampede)로 만듭니다.
  • 멱등성 — 호출자가 제공하는 키로, 타임아웃 후 재시도를 식별할 수 있습니다. 호출자는 손실된 요청과 손실된 응답을 구분할 수 없으므로 재시도합니다.
  • 저하 — 이 종속성이 다운되었을 때 사용자가 보는 것. 캐시된 결과나 부분 결과를 제공하는 것이 일반적으로 오류 페이지보다 낫고, 설계 시점에 결정하는 것이 가능하게 만듭니다.

5. 일관성

절대 깨져서는 안 되는 불변 조건(돈 보존, 재고 과판매 금지, 이중 청구 금지)을 식별하고, 이를 단일 서비스 내 단일 트랜잭션 안에 유지하세요. 이 제약 조건은 다른 어떤 것보다도 경계를 결정해야 합니다.

해당 불변 조건 밖의 모든 것은 최종적으로 일관될 수 있습니다. 워크플로가 여러 서비스에 걸쳐 있을 때, 각 단계에 대한 보상 조치(compensating action)가 있는 일련의 로컬 트랜잭션으로 모델링하고, 중간 상태가 보일 수 있음을 받아들이세요.

서비스 간 분산 트랜잭션은 최후의 수단입니다. 보상 조치 설계는 생각하기는 더 어렵지만 운영하기는 훨씬 쉽습니다.

6. 문서로 작성하세요

제약 조건   <부하, 데이터, 일관성, 가용성, 지연 시간, 소유권>
설계        <구성 요소와 각각이 소유하는 것>
흐름        <순서대로 중요한 두세 가지 경로>
장애        <각 종속성이 다운되었을 때 어떤 일이 발생하며 사용자가 보는 것>
트레이드오프  <이 설계가 어렵게 만드는 것과 10배 규모에서 가장 먼저 변경할 것>
거부됨      <대안과 선택하지 않은 이유>

장애와 거부됨 행이 설계를 그림과 구분짓습니다. 행복 경로만 설명하는 제안은 평가되지 않은 것입니다.

하지 말아야 할 것

  • 측정하거나 추정하지 않은 부하에 대해 큐, 캐시 또는 샤드를 추가하지 마세요.
  • 1배일 때 100배를 위해 설계하지 마세요. 알려진 다음 단계가 가능하도록 설계하고, 그 이상에서 무엇이 먼저 깨지는지 말하세요.
  • 단일 옵션을 불가피한 것으로 제시하지 마세요. 거부한 것을 명명하세요.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

관련 스킬