Community이미지github.com

C4 다이어그램

C4 모델(시스템 컨텍스트 L1, 컨테이너 L2, 컴포넌트 L3, 코드 L4, 시스템 랜드스케이프, 동적, 또는 배포 다이어그램)을 사용하여 소프트웨어 아키텍처 다이어그램을 생성, 검토, 업데이트 또는 설명할 때 발동합니다.

C4 다이어그램란 무엇인가요?

이 스킬은 C4 모델을 기반으로 소프트웨어 아키텍처 다이어그램을 작성, 검토 및 설명하기 위한 포괄적인 지침을 제공합니다. C4는 네 가지 줌 레벨(컨텍스트, 컨테이너, 컴포넌트, 코드)로 구성된 '코드의 지도' 집합으로, 사람, 소프트웨어 시스템, 컨테이너, 컴포넌트, 코드라는 계층적 추상화를 통해 일관된 다이어그램을 그릴 수 있도록 돕습니다. 이 스킬은 표기법과 도구에 독립적이며, 추상화와 규칙 자체에 중점을 둡니다. 주로 Markdown/Mermaid 환경에서 사용되며, C4 네이티브 신택스 대신 `flowchart`를 기본으로 사용할 것을 권장합니다. 다이어그램에는 항상 범례와 엄격한 추상화 수준 유지, 단방향 화살표, 명확한 동사 레이블, 프로토콜/기술 명시가 포함되어야 합니다. 또한 큐/토픽, 마이크로서비스, 확장 규칙 등 특수 모델링 패턴을 지원하며, L1 시스템 컨텍스트, L2 컨테이너, 배포, 동적 다이어그램에 대한 템플릿을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

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

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

문서

C4 다이어그램은(는) 무엇을 하나요?

출처: 공식 C4 모델 https://c4model.com/. C4 다이어그램을 그리거나, 검토하거나, 설명할 때마다 이 규칙을 적용하세요. 출력에 산문(ADR, 문서, PR 설명)이 포함될 경우 writing 스킬도 함께 불러오세요.

1. 목적

C4는 네 가지 줌 레벨(컨텍스트, 컨테이너, 컴포넌트, 코드)로 구성된 '코드의 지도' 집합입니다. Simon Brown이 UML과 4+1 뷰 모델에서 영감을 받아 임시방편 상자-선 다이어그램을 대체하기 위해 만들었습니다. C4가 해결하는 일반적인 실패 사례: 범례 없음, 추상화 수준 혼합, 레이블 없는 화살표, 기술 정보 누락, '비즈니스 로직'과 같은 모호한 레이블.

C4는 표기법과 도구에 독립적입니다. 아래의 추상화와 규칙이 중요하며, 모양은 중요하지 않습니다.

2. 추상화

계층 구조: 사람 -> 소프트웨어 시스템 -> 컨테이너 -> 컴포넌트 -> 코드. 각 레벨은 상위 레벨의 한 요소를 확대하여 보여줍니다.

추상화정의예시
사람시스템의 인간 사용자, 행위자, 역할 또는 페르소나고객, 지원 에이전트, 관리자
소프트웨어 시스템가장 높은 수준의 추상화; 사용자에게 가치를 제공합니다. 일반적으로 단일 팀이 소유하고 구축합니다. 제품 도메인, 바운디드 컨텍스트, 트라이브, 스쿼드가 아닙니다.티켓팅 플랫폼, 결제 시스템
컨테이너소프트웨어 시스템 내에서 독립적으로 실행/배포 가능한 애플리케이션 또는 데이터 저장소서버 사이드 웹 앱, SPA, 데스크탑 앱, 모바일 앱, 서버리스 함수, 배치/콘솔 앱, 마이크로서비스 API, 데이터베이스 스키마, S3/블롭 저장소, CDN, 파일 시스템, 셸 스크립트
컴포넌트컨테이너 내에서 잘 정의된 인터페이스 뒤에 있는 관련 기능의 그룹. 별도로 배포할 수 없음: 컨테이너의 모든 컴포넌트는 하나의 프로세스 공간을 공유합니다.OrderController, PaymentService, EmailSender
코드컴포넌트 내의 클래스, 인터페이스, 함수 또는 DB 테이블class OrderValidator, orders 테이블

컨테이너 규칙 (C4 FAQ)

  • C4 컨테이너는 Docker가 아닙니다. 패키징 방식과 관계없이 실행/배포 가능한 애플리케이션 또는 데이터 저장소입니다.
  • 서버 렌더링 HTML 앱은 1개의 컨테이너입니다. 서버와 SPA 또는 모바일 클라이언트는 원격 API를 통해 통신하는 2개의 컨테이너입니다.
  • JAR, DLL, 어셈블리, 모듈은 컨테이너가 아닙니다. 이들은 컨테이너 내부의 코드를 구성합니다.
  • 관리형 데이터 서비스(S3, RDS, CDN)는 사용자가 버킷이나 스키마를 소유하거나 제어하는 경우 시스템 경계 내의 컨테이너입니다. 외부 시스템이 아닙니다.

컴포넌트 규칙

  • 컴포넌트는 폴더, 패키지 또는 JAR이 아닙니다. 인터페이스가 있는 기능 그룹입니다.
  • 컴포넌트는 독립적으로 배포할 수 없습니다. 별도로 배포된다면 컨테이너입니다.

용어 조정

팀은 다이어그램이나 해당 문서에서 용어를 명시적으로 정의하는 경우 언어에 특화된 이름(예: 함수형 코드의 모듈 또는 함수)을 대체하여 사용할 수 있습니다. 각각이 엄격하게 정의되지 않은 한 추가 추상화 수준을 임의로 만들지 마세요.

3. 특수 모델링 패턴

큐와 토픽

  • 잘못된 예: 모든 서비스가 연결된 중앙에 하나의 거대한 '메시지 버스' 컨테이너(허브-앤-스포크). 생산자와 소비자가 무엇을 누구에게 하는지 숨깁니다.
  • 옵션 1 (권장): 각 큐 또는 토픽을 자체 컨테이너(메시지 데이터 저장소)로 모델링합니다. 생산자는 쓰기, 소비자는 읽기 또는 구독합니다.
  • 옵션 2: 직접적인 점대점 결합의 경우 큐 박스를 생략하고 관계 레이블을 "Queue orders [AMQP]를 통해 주문 이벤트 발행"으로 지정합니다. 선택적으로 이러한 선을 HTTP 호출과 다르게 스타일 지정합니다(범례에 설명).

예: 주문 API --"[Kafka]로 OrderPlaced 발행"--> [(orders topic)] --"[Kafka]에서 OrderPlaced 읽음"--> 처리 워커.

마이크로서비스 (Conway의 법칙)

  • 한 팀이 전체 소프트웨어 시스템을 소유: 각 마이크로서비스를 해당 시스템 경계 내의 컨테이너 그룹(API 컨테이너와 자체 데이터베이스 스키마 컨테이너, 또는 단일 상태 비저장 Lambda 컨테이너)으로 모델링합니다.
  • 별도 팀이 각 서비스를 소유: 독립적으로 소유된 각 서비스를 자체 소프트웨어 시스템으로 승격시키고, 각각 자체 시스템 컨텍스트 및 컨테이너 다이어그램을 갖습니다. 시스템 경계 전반에 걸쳐 큐/토픽 소유권을 명시적으로 표시합니다.

4. 다이어그램 카탈로그

핵심 정적 레벨

레벨다이어그램권장 여부범위대상표시/생략
1시스템 컨텍스트예1개 소프트웨어 시스템기술 및 비기술시스템 주변의 사람과 외부 시스템. 하위 수준 기술 및 프로토콜 생략
2컨테이너예1개 소프트웨어 시스템기술, 운영주요 기술 선택 및 프로세스 간 프로토콜. 클러스터링, 로드 밸런서, 장애 조치 생략
3컴포넌트아니오: 명확한 가치가 있고 이상적으로 자동화될 수 있을 때만1개 컨테이너아키텍트, 개발자한 컨테이너 내의 컴포넌트 및 상호 작용
4코드아니오: IDE에서 필요 시 생성1개 컴포넌트개발자UML 클래스 다이어그램 또는 ERD

지원 다이어그램

다이어그램권장 여부용도
시스템 랜드스케이프예, 조직 및 포트폴리오용모든 시스템과 사람에 대한 엔터프라이즈 또는 부서 지도. 단일 초점 시스템이 없는 컨텍스트 다이어그램
동적아니오: 필요한 경우에만 사용복잡한 런타임 협업. 번호가 매겨진 협업 스타일 또는 UML 시퀀스 스타일
배포예1개 환경(프로덕션, 스테이징, 개발). 시스템/컨테이너 인스턴스를 포함하는 중첩 배포 노드(물리, VM, Docker, Kubernetes, 런타임)와 인프라 노드(DNS, 로드 밸런서, 방화벽)

호환성

  • arc42: 컨텍스트 및 범위 -> L1; 빌딩 블록 레벨 1 -> L2; 빌딩 블록 레벨 2 -> L3; 빌딩 블록 레벨 3 -> L4.
  • UML: 워크플로, 상태 머신 및 데이터 모델에 대해 C4를 UML 상태, 시퀀스 및 ERD 다이어그램으로 보완합니다.

확장 규칙

다이어그램이 복잡해지면 수십 개의 상자를 하나의 캔버스에 억지로 넣지 마세요. 동일한 추상화 수준에서 업무 영역, 바운디드 컨텍스트, 기능 또는 단일 서비스 초점(초점 서비스와 그 인바운드/아웃바운드 이웃)별로 분할합니다.

5. 표기법 규칙

다이어그램

  • 제목은 다이어그램 유형과 범위를 명시합니다: 체크아웃 시스템의 컨테이너 다이어그램.
  • 모양, 색상, 테두리, 선 유형, 화살촉 및 약어를 설명하는 키/범례를 항상 포함합니다.
  • 엄격한 추상화 순수성을 유지합니다: 추상화 수준을 절대 혼합하지 말고(예: L2 컨테이너 다이어그램 안에 컴포넌트 상자를 넣지 않음), L1 시스템 컨텍스트 다이어그램 안에 프로토콜이나 내부 구현 단계([HTTPS], masked packet, tool_runner)를 절대 넣지 않습니다.
  • 경쟁 또는 이전 아키텍처를 비교할 때는 경계 제목을 명시적으로 레이블링하고(옵션 A (대체됨) 대 옵션 B (현재)), 요구 사항이나 가정이 변경될 때마다 문서의 모든 다이어그램을 업데이트합니다.

요소

  • 이름, 명시적 요소 유형(사람, 소프트웨어 시스템, 컨테이너, 컴포넌트, 데이터베이스, 배포 노드) 및 간결한 책임 설명.
  • 모든 컨테이너, 컴포넌트 및 배포 노드에 명시적 기술.

관계

  • 단방향 화살표만 사용합니다. <-->는 절대 사용하지 않습니다. 데이터가 양방향으로 흐르는 경우 개시자의 방향을 표시하고 레이블에 응답을 설명합니다.
  • 구체적인 능동 동사 레이블. 맨 사용은 절대 사용하지 않습니다. 주문 제출, 좌석 지도 읽음으로 작성합니다.
  • 컨테이너 간 관계에 프로토콜/기술: [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Markdown의 Mermaid

기본값은 flowchart (flowchart TB 또는 LR)이며, Mermaid 네이티브 C4Context/C4Container가 아닙니다. 네이티브 C4 문법은 실험적이며 Markdown 뷰어에서 렌더링이 실패하는 경우가 많습니다. 사용자가 명시적으로 요청하고 렌더러 지원을 확인한 경우에만 출력합니다.

Flowchart 규칙:

  • 시스템 경계(컨테이너/컴포넌트) 또는 배포 노드에 subgraph 사용.
  • 데이터베이스, 데이터 저장소, 큐 및 토픽에 [(...)] 사용.
  • 인용된 HTML 레이블: "<b>Name</b><br/>«Container: Tech»<br/>Short responsibility".
  • 인용된 레이블이 있는 화살표: A -->|"Action [Protocol]"| B.
  • 요소 유형당 하나의 classDef를 일관되게 적용합니다.
  • 색상, 실린더 모양 또는 여러 선 스타일을 사용할 때마다 컴팩트한 범례 서브그래프(연결되지 않은 노드, Dagre가 상단에 배치할 때 보이지 않는 bottomNode ~~~ 범례 링크로 하단에 고정)가 필요합니다. 제목은 코드 블록 바로 위에 제목 또는 Title: ... 줄로 배치합니다.
  • 동적 다이어그램: sequenceDiagram 또는 번호가 매겨진 화살표 레이블이 있는 flowchart (1. 주문 제출 [JSON/HTTPS]).
  • 배포 다이어그램: flowchart의 중첩 subgraph.
  • 괄호, 대괄호 또는 콜론이 포함된 레이블은 항상 인용합니다.
  • sequenceDiagram 또는 stateDiagram-v2 레이블 안에 이스케이프되지 않은 세미콜론(;)을 절대 넣지 마십시오(Mermaid는 ;을 문 종결자로 처리하여 나머지 텍스트를 잘못된 상태 또는 구문 오류로 분할합니다). sequenceDiagram의 긴 Note 블록은 <br/>로 감싸서 텍스트가 뷰포트 가장자리에서 잘리지 않도록 합니다.

템플릿: L1 시스템 컨텍스트

제목: 티켓팅 플랫폼의 시스템 컨텍스트 다이어그램

flowchart TB
    customer["<b>고객</b><br/>«사람»<br/>이벤트 티켓 구매"]
    ticketing["<b>티켓팅 플랫폼</b><br/>«소프트웨어 시스템»<br/>고객이 이벤트를 탐색하고 티켓을 구매할 수 있음"]
    payments["<b>결제 제공자</b><br/>«소프트웨어 시스템, 외부»<br/>카드 청구"]
    email["<b>이메일 서비스</b><br/>«소프트웨어 시스템, 외부»<br/>확인 이메일 전송"]

    customer -->|"이용하여 이벤트 탐색 및 티켓 구매"| ticketing
    ticketing -->|"카드 청구 요청"| payments
    ticketing -->|"사용하여 확인 이메일 전송"| email
    email -->|"에게 확인 이메일 전송"| customer

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class ticketing system
    class payments,email external

    subgraph 범례
        direction LR
        l1["사람"]:::person
        l2["소프트웨어 시스템 (범위 내)"]:::system
        l3["소프트웨어 시스템 (외부)"]:::external
    end

템플릿: L2 컨테이너 (큐 컨테이너 포함)

제목: 티켓팅 플랫폼의 컨테이너 다이어그램

flowchart TB
    customer["<b>고객</b><br/>«사람»<br/>이벤트 티켓 구매"]
    payments["<b>결제 제공자</b><br/>«소프트웨어 시스템, 외부»<br/>카드 청구"]

    subgraph boundary["티켓팅 플랫폼 [소프트웨어 시스템]"]
        spa["<b>웹 앱</b><br/>«컨테이너: React SPA»<br/>이벤트 탐색 및 체크아웃 UI"]
        api["<b>주문 API</b><br/>«컨테이너: Java, Spring Boot»<br/>주문 검증 및 접수"]
        db[("<b>주문 DB</b><br/>«컨테이너: PostgreSQL»<br/>주문 및 티켓 저장")]
        topic[("<b>orders topic</b><br/>«컨테이너: Kafka topic»<br/>OrderPlaced 이벤트")]
        worker["<b>처리 워커</b><br/>«컨테이너: Python»<br/>티켓 발행 및 이메일 전송"]
    end

    customer -->|"[HTTPS]로 탐색 및 구매"| spa
    spa -->|"[JSON/HTTPS]로 주문 제출"| api
    api -->|"[SQL/TCP]로 주문 쓰기"| db
    api -->|"[Kafka]로 OrderPlaced 발행"| topic
    worker -->|"[Kafka]에서 OrderPlaced 읽음"| topic
    worker -->|"[SQL/TCP]로 티켓 상태 업데이트"| db
    api -->|"[JSON/HTTPS]로 카드 청구 요청"| payments

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class spa,api,worker container
    class db,topic store
    class payments external

    subgraph 범례
        direction LR
        l1["사람"]:::person
        l2["컨테이너"]:::container
        l3[("데이터 저장소 / 큐 / 토픽")]:::store
        l4["외부 시스템"]:::external
    end

범례 참고: 화살표는 개시자에서 대상을 가리킵니다. 레이블은 동작과 [프로토콜]을 나타냅니다.

템플릿: 배포

제목: 티켓팅 플랫폼의 배포 다이어그램 (프로덕션)

flowchart TB
    users["<b>고객 브라우저</b><br/>«배포 노드: Chrome»"]

    subgraph aws["AWS «배포 노드: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«인프라 노드: DNS»"]
        lb["<b>로드 밸런서</b><br/>«인프라 노드: ALB»"]
        subgraph eks["EKS «배포 노드: Kubernetes 클러스터»"]
            subgraph pod["order-api pod «배포 노드: Docker, x3»"]
                api["<b>주문 API</b><br/>«컨테이너 인스턴스: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «배포 노드: PostgreSQL 16»"]
            db[("<b>주문 DB</b><br/>«컨테이너 인스턴스: PostgreSQL 스키마»")]
        end
    end

    users -->|"[DNS]로 호스트 이름 확인"| dns
    users -->|"[HTTPS]로 요청 전송"| lb
    lb -->|"[HTTP]로 요청 전달"| api
    api -->|"[SQL/TCP]로 주문 읽기 및 쓰기"| db

기본값 이상의 색상이나 스타일을 사용하는 경우 범례 서브그래프를 추가하세요.

템플릿: 동적 (시퀀스)

제목: 티켓팅 플랫폼 주문 체크아웃의 동적 다이어그램 (시퀀스 스타일)

sequenceDiagram
    autonumber
    actor customer as 고객
    participant spa as 웹 앱 (React SPA)
    participant api as 주문 API (Spring Boot)
    participant payments as 결제 제공자
    participant db as 주문 DB (PostgreSQL)
    participant topic as orders topic (Kafka)

    customer->>spa: "주문" 클릭
    spa->>api: POST /orders [JSON/HTTPS]
    api->>payments: 카드 청구 [JSON/HTTPS]
    payments-->>api: 결제 승인됨
    api->>db: 주문 행 삽입 [SQL/TCP]
    api->>topic: OrderPlaced 발행 [Kafka]
    api-->>spa: 201 Created (주문 확인)
    spa-->>customer: 주문 영수증 표시

최대 Markdown 뷰어 호환성을 위해 sequenceDiagram 참가자 및 메시지 레이블에 인용되지 않은 슬래시, 세미콜론(;, Mermaid가 문 종결자로 구문 분석함) 또는 원시 줄바꿈이 없도록 유지하세요.

7. 다이어그래

…

[번역을 위해 잘림]

Individual skills in this repo

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

관련 스킬