C4 모델과 UML: 아키텍처 문서화의 역할 분담
C4 모델과 UML의 표현 범위, 문서화 운영 방식, ADR·CI 기반 거버넌스와 선택적 병행 전략을 정리한다.
2026-08-14 · 최초 발행 2025-10-31
아키텍처 문서는 누가 무엇을 이해해야 하는지에서 출발한다
소프트웨어 아키텍처 문서화는 이해관계자가 같은 시스템을 같은 관점에서 보게 하고, 이후 변경을 감당할 수 있게 만드는 작업이다. C4 모델과 Unified Modeling Language(UML)는 이 목적에 접근하는 방식이 다르다.
C4 모델은 Simon Brown이 제안한 계층형 아키텍처 시각화 방식이다. Context, Container, Component, Code의 4단계로 시스템을 표현하며, 필요한 범위만 보여 주는 최소 표기법으로 커뮤니케이션과 인지 부하를 다룬다. 모델·문서·코드 사이의 추적성도 지향한다.
UML은 OMG 표준의 범용 모델링 언어다. 14종 다이어그램을 이용해 시스템의 구조, 행위, 상태를 정밀하게 표현하고 XMI를 통한 도구 상호운용성과 모델 교환을 지원한다. 분석·설계·생성 자동화와 연계할 여지도 있다.
C4는 범위를 좁혀 대화를 시작한다
C4의 뷰는 C1(Context)에서 C2(Container), C3(Component), C4(Code)로 내려간다. 시스템 전체의 맥락에서 시작해 구현에 가까운 구조까지 확대·축소할 수 있으므로, 레벨마다 다뤄야 할 질문과 참여할 이해관계자를 구분하기 좋다.
표현 자체는 단순한 도형과 관계에 집중한다. 대신 텍스트 주석과 ADR(Architecture Decision Record)을 함께 관리해 시각 모델과 결정 근거를 연결한다. Structurizr DSL, PlantUML C4, Diagrams-as-Code를 사용하면 다이어그램을 Git에서 버전 관리하고 CI에서 렌더링·검증하는 흐름도 구성할 수 있다.
UML은 정적 구조뿐 아니라 동적 흐름, 상태, 배치처럼 여러 관점을 세밀하게 담을 수 있다. 그만큼 다이어그램 종류와 모델 관리 범위가 늘어나며, 모델과 코드가 멀어지거나 복잡도가 커질 위험도 있다. 반대로 C4는 행위를 정밀하게 모델링하는 데 한계가 있다.
대체가 가능한 곳과 UML이 남는 곳
아키텍처 문서가 시스템 경계, 책임, 의존성, 온보딩을 설명하는 데 초점이 있다면 C4는 UML을 실질적으로 대체할 수 있다. 마이크로서비스와 클라우드 네이티브 구조처럼 여러 서비스의 관계를 빠르게 공유해야 하는 환경에서 특히 그렇다.
규제 준수 요구가 있는 금융·의료 영역, 상세 행위 검증, 정적 분석·코드 생성 연계, 시뮬레이션이 필요한 경우에는 UML을 병행한다. 시퀀스, 상태, 활동 다이어그램을 모든 영역에 적용하기보다 필요한 시나리오에 한정하는 편이 관리 범위를 통제하기 쉽다.
운영 기준은 C1~C3를 C4로 표준화하고, 컴포넌트와 UML 시퀀스·상태 모델을 추적 링크로 연결하는 방식이 될 수 있다. ADR에는 결정 근거를 남기고, Git PR 검토와 모델 일관성 검사를 변경 관리에 포함한다.
문서화 목적에 따른 선택 기준
| 지표 | C4 모델 | UML |
|---|---|---|
| 커뮤니케이션 효율(성능) | 비개발·개발자 간 공통 이해가 쉽고 회의 시간을 줄일 수 있음 | 개발자 중심의 정밀성은 높지만 비개발자에게는 이해 장벽이 있음 |
| 확장성 | 레벨별 확대·축소가 쉽고 대규모 조직 표준화에 활용하기 좋음 | 다이어그램 종류가 늘수록 복잡도가 증가할 수 있음 |
| 일관성 | ADR·리포지토리 기반으로 변경을 추적하기 쉬움 | 다이어그램 사이 추적성을 위해 추가 거버넌스가 필요함 |
| 안정성(변경 내성) | 최소 표기법으로 변경 파급도가 낮음 | 모델이 세밀할수록 변경 영향 범위가 커짐 |
| 운영 편의 | Docs-as-Code와 CI 통합에 적합함 | 도구 의존성, XMI 관리, 교육 비용이 늘어날 수 있음 |
조직의 문서화 흐름에 연결하는 방법
스타트업 SaaS에서는 C1~C3와 ADR, PR 리뷰를 함께 운영해 서비스 맥락과 의존성을 드러내고 의사결정 리드타임을 줄일 수 있다. 금융권처럼 외부감사에 대비해야 하는 환경에서는 상위 문서를 C4로 표준화하고, 핵심 시나리오에만 UML 시퀀스·상태 다이어그램을 더해 문서 정합성과 추적성을 관리한다.
모놀리식에서 마이크로서비스로 전환할 때는 C2로 컨테이너 분해안을 만들고, C3로 팀별 컴포넌트 책임을 정리한다. 위험 시나리오는 UML 시퀀스 다이어그램으로 보완한다. DevOps 파이프라인에서는 Structurizr 또는 PlantUML 렌더링을 CI에 넣고, 스키마와 링크 검사를 통해 문서 일관성을 자동으로 점검할 수 있다.
도입 시에는 먼저 커뮤니케이션 중심 문서화와 규제 준수 범위를 구분하고, C4 적용 레벨과 UML 보완 대상을 정한다. 명명 규칙, 관계 라벨, 시스템·컨테이너 유형 태깅, 컴포넌트·ADR·레포지토리 링크 정책도 함께 정의한다.
도구는 Structurizr DSL 또는 PlantUML C4를 선택해 Git 저장소에 두고, CI 렌더링·링크 검증·다이어그램 린팅을 연결한다. 리뷰는 PR 기반으로 라우팅하며 변경 영향 체크리스트와 다이어그램·코드 스팟 점검 루틴을 운영한다. UML 시퀀스는 핵심 트랜잭션 10% 이내로 한정하고, 상태·활동 다이어그램은 규제와 도메인 규칙이 중요한 영역에 국한한다. ADR 리드타임과 온보딩 시간 같은 KPI를 측정하며 분기별로 표기 규칙과 템플릿을 회고할 수 있다.
모델이 코드와 멀어지지 않게 관리한다
모델과 구현의 괴리가 생기면 릴리스 게이트에 다이어그램 최신성 검사를 추가하고 아키텍처 오너를 지정한다. C2와 C3 사이에 불일치가 발견되면 컴포넌트 책임 매트릭스와 관계 라벨을 점검한다.
세분화가 지나쳐 인지 부하가 커지는 경우에는 C3 범위에 컴포넌트 수 상한을 두고, 비핵심 영역은 텍스트 설명으로 전환한다. 세밀함 자체보다 변경 시점에도 유지할 수 있는 문서 범위를 정하는 일이 중요하다.
신규 개발자 온보딩 시간은 2040% 단축되고, 아키텍처 리뷰 리드타임은 2535% 단축되며, 문서-코드 불일치 이슈는 30% 내외 감소하는 정량 효과를 기대할 수 있다. 이해관계자 간 공통 시각, 변경 의사결정의 투명성·재현성, 팀 지식 자산으로서의 문서화 지속 가능성도 함께 높아진다.