길리랩blog

현대 개발 환경에서 UML을 다시 쓰는 법

애자일·DevOps·클라우드 네이티브 환경에서 UML을 경량 모델링·다이어그램-애즈-코드·C4·ADR과 결합해 실무에 적용하는 전략을 정리한다.

2026-08-12 · 최초 발행 2025-10-31

전 범주 UML을 다 쓸 필요는 없다

애자일·DevOps·클라우드 네이티브로 전환하면서 UML의 역할도 다시 정의할 필요가 생겼다. 표준 표기법 전체를 교과서대로 적용하는 대신, 비즈니스 가치에 직결되는 최소 다이어그램 집합만 운용하는 쪽으로 무게중심이 옮겨갔다. UML은 애초에 방법론이 아니라 시스템 구조·행위를 시각화·명세·구성·문서화하기 위한 표준 모델링 언어(OMG 관리, UML 2.x 기반)다 — 어떻게 쓸지는 팀의 몫이다. 다이어그램-코드 동기화, 다이어그램-애즈-코드(diagram-as-code)와 CI 통합, C4 모델·ADR와의 상호 보완적 결합이 지금 실무에서 통하는 방향이다.

경량 모델링이 작동하는 방식

핵심 다이어그램만 고른다. 도메인 모델은 Class/Component, 협력·거래는 Sequence, 상태 변이는 State로 최소화하고, 요구사항 변경 빈도와 팀 숙련도를 기준으로 범위를 정한다. 절차도 반복 가능하게 만든다 — 도메인 탐색 → 설계 스파이크 → 리뷰·정제 → 아티팩트 고정 태깅을 타임박스로 운영한다.

다이어그램-코드 동기화는 PlantUML/Mermaid 같은 텍스트 소스를 관리하고 PR 단위로 렌더링·검증을 자동화하는 데서 시작한다. 클래스/컴포넌트 ID를 이슈·테스트 케이스에 매핑하고, 커밋 메시지·ADR 링크로 변경 이력의 일관성을 확보하면 추적성이 붙는다.

아키텍처 계층은 C4와 UML을 섞어 쓴다. C4의 L1~L3(컨텍스트·컨테이너·컴포넌트)로 큰 틀을 프레이밍한 뒤, 중요한 협력·프로토콜만 UML Sequence·State로 정밀화한다. 다이어그램이 바뀌면 그 근거·대안·결정·결과를 ADR로 남겨 리뷰 재현성을 확보한다.

자동화와 품질 게이트도 빠질 수 없다. CI 파이프라인에서 다이어그램 렌더링, 링크 검증, 모델 린팅, 누락/순환 의존성 탐지를 돌리고, 다이어그램 복잡도(노드/엣지 임계), 명명 규칙, Stereotype 정책, 버전 태그 검증을 품질 기준으로 삼아 유지보수성을 지킨다.

어디에 쓰이는가

마이크로서비스 경계를 설정할 때는 Bounded Context를 정의한 뒤 인터페이스·이벤트 계약을 Sequence/Component로 명세한다. 사가(보상 트랜잭션) 흐름을 시각화하면 장애·롤백 설계가 쉬워지고, 스키마 레지스트리·API 스펙(AsyncAPI/OpenAPI)과 상호 참조를 걸어둘 수 있다.

레거시를 현대화할 때는 코드 리버스 엔지니어링으로 클래스/패키지 다이어그램을 초기 생성해 순환 의존성을 찾아내고, 단계적 모듈화 계획을 세운다. 컴포넌트 수준의 목표 상태(TBD) 모델을 제시하고 위험 기반으로 우선순위를 매긴다.

규제 산업에서는 요구→설계→검증 추적 행렬을 모델 ID로 연결하고, 릴리스 노트에 모델 변경 요약을 자동으로 넣는다. 변경 영향 분석(Impact Analysis) 보고서를 자동 생성하면 심사 대응 시간이 준다.

DevSecOps 협업에서는 Misuse/Threat 시나리오를 Sequence/Activity로 모델링하고 취약 지점에 컨트롤 스테레오타입을 적용한다. 비인가 데이터 플로우, 암호화 누락, 광역 권한 사용을 탐지하는 규칙이 보안 게이트 역할을 한다.

도입 절차

  1. 준비: 현행 아키텍처·도메인 복잡도를 진단하고 이해관계자를 식별한다. 표기·리뷰 기준을 먼저 합의한다.
  2. 경량 표준 정의: 사용할 다이어그램 범주, 스테레오타입, 네이밍 규칙, 태깅 스키마를 확정하고 C4 매핑 표준을 문서화한다.
  3. 도구화: PlantUML/Mermaid 템플릿, 레이아웃 가이드, 린터를 구성하고 리포지토리 구조·브랜칭 전략을 정의한다.
  4. CI/CD 통합: 렌더링·검증·아티팩트 배포(HTML/PDF/Wiki)를 자동화하고, 실패 시 PR을 차단하는 정책을 건다.
  5. 운영·거버넌스: 모델 변경 RFC/ADR 프로세스를 운영하고, 분기별 다이어그램 부채 점검과 교육·리뷰 라운드테이블을 돌린다.

변경이 흘러가는 경로

⤢✕예아니오아니오예예아니오optimistic lock원자적 검증/배포입력: 요구사항/이슈/ADR모델 작성/갱신:PlantUML/Mermaid파일 충돌 발생?수동 병합/잠금 정책 적용PR 생성CI: 렌더링/린트/링크검증품질 게이트 통과?피드백 반영, 복잡도 축소/명명수정출력: 다이어그램 아티팩트배포(Wiki/포털)변경 영향 있음?테스트/문서 동기화, 트레이스업데이트릴리스 태깅/아카이브

입력은 요구사항·이슈·ADR이고, 모델 작성 → PR → CI 검증 → 품질 게이트를 거쳐 아티팩트 배포·태깅, 변경 영향 반영으로 이어진다. 파일 충돌은 잠금이나 수동 병합으로, 게이트 실패는 수정·재시도로 처리한다. 검증·배포는 원자적으로 묶고, optimistic lock으로 편집 충돌을 최소화한다.

접근 방식별 운영 지표

접근 방식 확장성(팀/시스템) 일관성 안정성(변경 내성) 운영 편의
풀 스펙 UML 일괄 도입 중간: 복잡도 증가 시 비용 급증 높음: 표준 엄격 적용 중간: 유지 비용 부담 낮음: 교육·도구 부담 큼
경량 UML + C4 하이브리드 높음: 규모 확장에 유연 높음: 계층·표준 분리 높음: 변경에 탄력 높음: 자동화·템플릿 용이
코드 중심 다이어그램만 사용 높음: 진입 장벽 낮음 중간: 팀별 편차 낮음: 의도·맥락 손실 높음: 작성·리뷰 간편

사가 트랜잭션을 시퀀스로 정밀화하기

전제조건은 Java 11+, PlantUML 1.2024.x, Docker 또는 로컬 JAR다. docker run --rm -v $PWD:/work plantuml/plantuml -tpng seq.puml이나 java -jar plantuml-1.2024.x.jar -tpng seq.puml로 바로 실행할 수 있다.

주문 사가의 보상 트랜잭션을 모델링한 예시다.

@startuml
title Order Saga: Payment -> Inventory -> Ship (with Compensation)
participant API
participant Order
participant Payment
participant Inventory
participant Shipping

API -> Order: createOrder(cmd)
Order -> Payment: authorize(amount)
alt auth failed
  Payment --> Order: fail(reason)
  Order --> API: error(402)
else auth ok
  Payment --> Order: ok(txId)
  Order -> Inventory: reserve(items)
  alt reserve failed
    Inventory --> Order: fail
    Order -> Payment: cancel(txId)  ' compensation
    Payment --> Order: canceled
    Order --> API: error(409)
  else reserve ok
    Inventory --> Order: ok
    Order -> Shipping: request(parcel)
    Shipping --> Order: scheduled
    Order --> API: success(orderId)
  end
end
@enduml

어디까지 표준화하고 어디서 멈출 것인가

최소 충분 다이어그램 원칙이 기본이다. 의사결정·리뷰·온보딩에 직접 기여하는 다이어그램만 유지한다는 뜻인데, 과도하게 생략하면 암묵지가 늘고 유지·전달 리스크가 커진다.

표준 UML과 팀 맞춤 확장 사이에서는 표준 스테레오타입을 우선하고, 필요할 때만 메타모델을 최소로 확장한다. 확장을 남용하면 도구 호환성과 학습 비용이 늘어난다.

자동 생성과 수동 정밀화도 역할이 다르다. 구조(클래스/컴포넌트)는 자동 생성에 맡기고, 행위(시퀀스/상태)는 수동으로 정밀화한다. 자동화의 정확도에는 한계가 있어서 수동 보정이 필요하다.

보안·거버넌스는 리포지토리 권한 분리, 비공개 경로·자격 정보 마스킹, 변경 RFC/ADR 의무화가 원칙이다. 다만 승인 흐름이 늘어나는 만큼 리드타임도 늘어난다는 트레이드오프는 감수해야 한다.

효과와 전제

설계 리뷰 시간이 2030% 줄고 합의를 반복하는 일이 준다. 변경 영향 누락이 줄면서 릴리스 결함이 1020% 저감되고, 신규 인력 숙련 시간은 30~40% 단축된다. 리팩토링 계획 수립 시간도 25% 내외 절감된다. 다만 이 수치는 팀 숙련도·자동화 수준·도메인 복잡도에 따라 달라진다.

경량·자동화·연계가 지금 UML을 실무 도구로 살아남게 하는 세 축이다. C4·ADR와 엮고, 다이어그램-애즈-코드와 CI 품질 게이트로 추적성을 강화하는 쪽이 모델의 생존성을 높인다. 최소 충분 다이어그램 원칙과 표준화·거버넌스의 균형을 잡는 것이 팀 생산성과 품질을 동시에 얻는 길이다.

UMLC4 모델PlantUML경량 모델링아키텍처 거버넌스