UML·C4·ERD를 함께 쓰는 설계 문서화 전략

같은 시스템을 서로 다른 거리에서 읽기

설계 문서에서 UML, C4 Model, ERD는 같은 문제를 같은 방식으로 설명하지 않는다. UML은 구조와 행동을 폭넓게 다루고, C4는 아키텍처의 맥락과 경계를 공유하는 데 초점을 둔다. ERD는 데이터 구조와 무결성 제약을 중심으로 시스템을 해석한다.

UML(Unified Modeling Language)은 시스템의 구조와 행동을 표준 표기법으로 나타내는 범용 모델링 언어다. Use Case, Class, Sequence, Activity, State, Component 다이어그램 등을 사용하며, OMG 표준을 기반으로 폭넓은 도구 생태계를 갖고 있다.

C4 Model은 소프트웨어 아키텍처를 Context, Container, Component, Code로 점차 상세화하는 시각 프레임워크다. 특정 기술 스택에 묶이지 않고 의사소통을 위한 단순한 표기를 지향한다. Structurizr, PlantUML/Diagrams with C4, Mermaid 등으로 표현할 수 있다.

ERD(Entity-Relationship Diagram)는 엔터티와 속성, 관계를 드러내는 데이터 모델 다이어그램이다. 개념·논리·물리 모델로 나뉘며 정규화와 무결성 제약을 표현한다. Crow’s Foot, Chen, IE 등 여러 표기 방식이 있다.

문서가 답해야 할 질문에 맞춰 고르기

C4는 외부 이해관계자와 시스템의 관계에서 시작해 내부 컴포넌트까지 아키텍처 맥락을 설명한다. UML은 도메인 구조, 행동, 상호작용을 포함한 시스템 설계 전반을 표현할 수 있다. ERD는 데이터 구조와 제약을 정보 모델 관점에서 다룬다.

표현 방식에서도 차이가 난다. UML은 정형 표기와 상세한 표현력이 장점이지만 복잡성을 관리해야 한다. C4는 추상화와 가독성을 우선하며 표기를 최소화한다. ERD는 키와 제약을 통해 데이터를 정형적으로 나타내고, 스키마 전개와 직접 연결된다.

도구 선택 역시 대상에 따라 달라진다. UML에는 Enterprise Architect, Visual Paradigm, PlantUML 같은 도구가 있고, C4는 Structurizr, Mermaid, PlantUML C4 확장처럼 경량 도구와 잘 맞는다. ERD는 ERWin, ER/Studio, dbdiagram.io, DataGrip 등 DB 중심 도구가 주로 쓰인다.

모델	커뮤니케이션·작성 속도	대규모 적용	표기·해석 일관성	변경·오해 리스크	도구·자동화
UML	중간: 표현력은 높지만 학습·작성 비용 존재	높음: 다양한 관점으로 확장 가능	높음: 표준 표기 규칙 견고	중간: 과도한 상세화 시 해석 편차 가능	높음: 도구가 다양하고 코드 연계 일부 가능
C4	높음: 빠른 합의와 공유에 유리	높음: 레벨별 확장 구조에 적합	중간: 표기 자유도가 있어 팀 규칙 필요	높음: 변경 영향 파악이 용이	높음: 경량 도구와 as-code 문서화에 유리
ERD	중간: 초안은 빠르지만 세부 제약에 시간 소요	높음: 스키마 중심 확장에 유리	높음: 제약·키로 정형 해석	높음: 무결성을 기반으로 안정	중간: DB별 차이와 마이그레이션 관리 필요

여기서 성능은 실행 성능이 아니라 모델링과 의사소통 효율을 뜻한다.

아키텍처에서 스키마까지 연결하는 흐름

문서의 출발점은 요구사항이 아키텍처 맥락, 내부 설계, 데이터 구조 중 무엇을 우선 설명해야 하는지 가르는 일이다. 시스템 경계는 C4로, 구성과 행동은 UML로, 데이터 제약은 ERD로 이어갈 수 있다.

C4의 컨테이너, UML의 컴포넌트·시퀀스, ERD의 테이블 사이에는 추적 링크를 유지한다. 요구사항에서 아키텍처, 설계, 스키마까지 연결돼야 변경 영향도 함께 확인할 수 있다. 팀 차원에서는 표기 합의와 레벨·버전 규칙을 마련하고, 다이어그램을 as-code로 관리한다. 검토와 변경 관리는 PR 기반 리뷰, 영향 범위 표시, 릴리스 태깅으로 운영한다.

⤢✕

문서 묶음이 유용한 상황

신규 서비스에서는 C4 L1~L3로 컨텍스트, 컨테이너, 컴포넌트를 먼저 정하고, 핵심 시나리오는 UML 시퀀스로, 핵심 엔터티는 ERD 초안으로 병행할 수 있다.

레거시 모놀리식을 분해할 때는 C4로 경계와 의존성을 시각화해 마이크로서비스 경계를 확정한다. 이어서 ERD로 정규화와 데이터 분리 전략을 세우고, UML로 인터페이스 계약을 정의한다.

데이터 거버넌스나 규제 대응에서는 ERD가 PII와 민감정보 분류, 제약 선언을 담당한다. UML 활동 다이어그램과 시퀀스 다이어그램은 데이터 흐름과 접근 제어 시나리오를 명세하는 데 쓸 수 있다.

상세화 수준을 통제하며 운영하기

PlantUML, Mermaid, Structurizr 기반의 다이어그램 as-code와 Git 버전 관리는 문서 변경을 코드 변경 흐름에 붙이는 방법이다. 팀 표준 템플릿, 레전드, 아이콘 세트를 통일하면 해석의 차이도 줄일 수 있다.

상위 수준은 C4로 유지하고, 실제로 상세 설명이 필요한 지점에만 UML과 ERD를 붙이는 린 문서화 방식이 적합하다. UML의 상세도가 높아질수록 문서 유지보수 비용은 증가한다. C4의 단순 표기는 엄밀한 제약 표현에 한계가 있으며, ERD의 정규화 강화는 성능과 개발 생산성 사이의 균형 문제를 남긴다.

C4 상위 합의를 먼저 두면 의사소통·리뷰 시간은 2540% 절감 추정이며, 재작업 감소가 전제다. 추적 링크와 계층 일관성을 유지하면 변경 영향 분석 시간은 2035% 단축될 수 있다. 맥락에서 행동, 데이터로 이어지는 학습 경로는 신규 인력 온보딩 기간을 30% 내외 단축하는 효과로 이어질 수 있다.

수치는 팀 성숙도와 도구 자동화 수준에 따른 범위 추정이며, 최신 팀 데이터로 검증이 필요하다.