길리랩blog

Markdown과 PlantUML을 엮은 설계 문서화 실전 사례

Markdown 문서와 PlantUML 다이어그램을 한 리포지터리에서 관리하며 ADR·API·인시던트·온보딩 문서를 자동화한 네 가지 실전 사례를 정리한다.

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

코드 중심 팀이 문서에서 부딪히는 문제

코드 중심 팀에서 문서가 낡는 이유는 대체로 하나다 — 문서와 다이어그램이 서로 다른 도구, 다른 리듬으로 관리되기 때문이다. Markdown의 경량성에 PlantUML의 다이어그램-as-코드 방식을 결합하면 설계·운영 지식을 리포지터리 안에서 함께 버전 관리하고 자동화할 수 있다. 이 글은 그 결합 방식의 구조와, 실제로 어떤 상황에 적용했을 때 어떤 효과가 났는지를 사례 중심으로 정리한다.

Markdown + PlantUML이 만드는 단일 출처

Markdown 문서와 PlantUML 다이어그램 소스를 단일 리포지터리에 두고, CI/CD로 이미지와 사이트를 자동 생성·배포하는 것이 이 방식의 정의다. 핵심 개념은 세 가지다.

  • Diagram as Code: PlantUML DSL로 시퀀스·컴포넌트·활동·상태·ER 다이어그램을 정의한다.
  • 단일 출처(Single Source of Truth): .md와 .puml을 같은 브랜치에서 변경·리뷰·릴리스한다.
  • 자동 렌더링: 로컬 CLI, PlantUML Server, Kroki 등으로 SVG/PNG를 생성한다.

파이프라인은 브랜치 → PR 리뷰 → CI 렌더링 → 정적 사이트 배포의 Git 중심 워크플로우를 따른다. 변경 영향은 다이어그램 재생성 대상 파일만 증분 처리해서 최소화하고, 링크·맞춤법·Lint·구조 검증을 품질 게이트로 넣는다.

DSL은 설계 변경을 텍스트로 커밋하기 때문에 diff와 리뷰가 쉽다. SVG(벡터·접근성), PNG(호환성), ASCII 아트(터미널) 중 상황에 맞는 포맷을 고르고, 공통 스킨·스타일·스프라이트를 템플릿화해 재사용한다.

렌더링은 로컬 CLI(Java + Graphviz 기반 plantuml.jar), 서버/서비스(Self-hosted PlantUML Server, Kroki API), 컨테이너(재현 가능한 빌드를 위한 Docker 이미지 고정) 세 갈래로 나뉜다. 여기에 파일 구조·네이밍·인덱스 자동 생성 같은 Lint/Conventions, 내부 앵커·상호 참조를 확인하는 링크 무결성 검사, 코드와 문서를 동시에 바꿀 때의 승인 흐름이 거버넌스를 채운다. ADR(Architecture Decision Record) 연계, 릴리스 노트·운영 가이드의 타임라인 관리, 다국어·버전 분기 지원도 이 구조 위에서 자연스럽게 붙는다.

사례 1: ADR과 시퀀스 다이어그램을 함께 관리하기

아키텍처 결정의 근거와 상호작용 흐름을 동시에 관리하는 게 목적이다. docs/adr/NNN-decision.md와 diagrams/sequence/auth-flow.puml을 입력으로 받아, CI에서 puml→svg 변환 후 md 안에 상대경로로 삽입한다. 결과물은 정적 사이트(GitHub Pages 등)에 게시되고 ADR 인덱스가 자동 갱신된다. 다이어그램 파싱 오류가 나면 파이프라인이 실패하며 문제 파일의 경로·라인을 로깅하고 캐시를 무효화한다.

사례 2: 마이크로서비스 API 문서를 스펙과 함께 동기화

API 계약이 바뀌면 다이어그램도 같이 바뀌어야 한다. OpenAPI 스키마와 컴포넌트/배포 다이어그램 puml을 입력으로 받아 OpenAPI→Markdown 변환, PlantUML 렌더링, 링크체커 실행을 거친다. 출력은 버전 태그별 문서 세트이고 CDN 캐시를 무효화한다. 스키마 유효성 검사에 실패하면 변환을 중단하고 이전 안정 버전으로 롤백한다.

사례 3: 인시던트 포스트모템을 활동 다이어그램으로 남기기

복구 절차의 재현성과 교육 자료 확보가 목적이다. incident.md와 remediation-activity.puml을 입력으로, 타임라인 테이블 생성 스크립트와 활동/상태 다이어그램 렌더링을 거쳐 검색 인덱스를 생성하고 내부 포털에 업로드한다. 개인식별정보(PII)가 검출되면 게시를 중단하고 보안 리뷰를 요청한다.

사례 4: 온보딩 핸드북을 자동으로 생성하기

신규 입사자 교육 시간을 줄이는 게 목적이다. 팀별 시스템 지도(component.puml)와 배포 토폴로지(deployment.puml)를 입력으로 목차를 자동 생성하고 이미지를 최적화한다. 출력은 PDF/HTML을 동시에 산출하고 접근성 검사를 거친다. 이미지 대체텍스트가 빠지면 경고하고, 접근성 점수가 미달이면 실패 처리한다.

렌더링 옵션 비교

항목 로컬 CLI Self-hosted PlantUML Server Kroki(Hosted/Self)
성능 소규모 변경에 빠름 동시성·캐싱 우수 API 캐시로 고속 응답
확장성 개발자 로컬 한정 수평 확장 가능 서비스 수준에 의존
일관성 로컬 환경 편차 존재 중앙화로 일관성 높음 버전 고정 시 일관성 확보
안정성 개발자 환경 영향 운영 책임 필요 외부 서비스 가용성 의존
운영 편의 설치 간단 모니터링·업데이트 필요 최소 운영, 네트워크 종속

처리 파이프라인

⤢✕.puml 변경.md 변경통과실패개발자 커밋.md + .pumlCI 트리거변경 파일 식별PlantUML 렌더링SVG/PNG 생성Markdown 빌드정적 사이트 생성품질 게이트링크/린트/접근성배포Pages/S3+CDN파이프라인 중단로그/아티팩트 저장알림PR 코멘트/Slack

실제 구현: 전제조건부터 배포까지

PlantUML 1.2024.x, Java 11+가 필요하고 일부 다이어그램은 Graphviz(dot)도 있어야 한다. Docker를 쓴다면 네트워크 접근이 가능해야 하고 폰트 패키지 설치도 확인해야 한다.

인증 흐름 시퀀스 다이어그램:

@startuml
title 인증 흐름
actor User
participant Web as "WebApp"
participant Auth as "AuthService"
User -> Web: 로그인 요청
Web -> Auth: 토큰 발급 요청
Auth --> Web: JWT 토큰
Web --> User: 로그인 성공
@enduml

Markdown 문서에서는 렌더링된 SVG를 그냥 이미지로 참조한다.

# 인증 흐름

아래 다이어그램은 로그인 처리 절차 설명.

![Auth Flow](../diagrams/auth-flow.svg)

여러 .puml을 한 번에 렌더링하려면 Makefile로 묶는 게 편하다.

PLANTUML_VERSION ?= 1.2024.7
PUML_FILES := $(shell find diagrams -name '*.puml')
SVG_FILES := $(patsubst %.puml,%.svg,$(PUML_FILES))

all: $(SVG_FILES)

%.svg: %.puml
	docker run --rm -v $$PWD:/work -w /work \
		plantuml/plantuml:$(PLANTUML_VERSION) \
		-tsvg $<

clean:
	rm -f $(SVG_FILES)

CI에서는 렌더링부터 사이트 빌드, 링크 체크, 배포까지 한 워크플로우로 묶는다.

name: docs
on:
  push:
    branches: [main]
  pull_request:
jobs:
  build-docs:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Render PlantUML to SVG
        uses: docker://plantuml/plantuml:1.2024.7
        with:
          args: -tsvg $(git ls-files "diagrams/**/*.puml")
      - name: Build site
        run: |
          npm ci
          npm run build # 예: Docusaurus, MkDocs, VitePress 등
      - name: Link check
        run: npx linkinator build --recurse
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build
  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build-docs
    permissions:
      pages: write
      id-token: write
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/deploy-pages@v4

보안·운영에서 챙길 것

외부 렌더링 서비스를 쓰면 소스가 유출될 위험이 있으므로 사내 Kroki/PlantUML Server를 권장한다. CI 시크릿은 마스킹하고, 외부 기여자의 워크플로우 권한은 제한해야 한다. 운영 측면에서는 버전을 고정해 재현성을 보장하고, Docker 이미지 태깅과 캐시 전략을 함께 쓴다. 폰트·아이콘 일관성을 위해 컨테이너 안에 폰트 패키지를 설치해두는 것도 잊기 쉬운 부분이다.

트레이드오프는 두 가지다. 중앙 서버를 운영하면 유지보수 비용이 늘지만 문서 렌더링 일관성이 좋아진다. SVG는 접근성·검색성이 좋지만 일부 뷰어에서 호환성 문제가 생길 수 있다.

효과는 리드타임과 온보딩 기간에서 나타난다

자동 렌더링·배포 파이프라인 덕분에 문서 최신화 리드타임이 3050% 줄어든다. diff 기반 다이어그램 코드 리뷰로 리뷰 효율이 2030% 올라가고, 체계화된 시스템 지도 덕분에 온보딩 기간이 15~25% 단축된다. 정성적으로는 문서-코드 동기화가 좋아지고 설계 지식이 쌓이고 전파되기 쉬워지며, 인시던트 대응이 표준화되고 복구 절차가 재현 가능해진다.

단일 리포지터리, 표준화된 렌더링 파이프라인, 품질 게이트 세 가지만 갖추면 최신성·일관성·재현성은 대부분 따라온다. 처음에는 로컬 CLI나 컨테이너로 시작하고, 필요할 때 Self-hosted 서버로 확장하는 순서가 부담이 적다.

PlantUMLMarkdownDiagram as CodeADR문서 자동화