문서에 올바른 UML 다이어그램 삽입하기
에이전트는 문서에 "다이어그램 추가"를 자주 요청받지만, 모델링을 미묘하게 잘못하거나(유효하지 않은 다중성, 화살표 방향 반대, 상속 거꾸로) 실제 그림으로 렌더링되지 않는 코드 블록을 반환하는 경우가 많습니다. 이 스킬은 올바른 클래스 다이어그램과 실제 삽입 가능한 이미지를 생성합니다.
범위
- 현재는 클래스 다이어그램만 지원합니다 — 클래스, 속성, 연관, 다중성, 상속. 다른 UML 다이어그램 유형(상태 기계, 객체, 시퀀스, 활동 등)은 이 스킬의 범위를 벗어납니다.
- 항상 BESSER B-UML을 통해 진행됩니다. 모든 다이어그램은 먼저 B-UML
DomainModel로 구축된 후 전달됩니다. 모델을 거치는 과정이 다이어그램을 정확하게 만들고 코드로 재사용 가능하게 합니다.
시작 가능한 지점
- 설명 — 사용자가 도메인을 설명하면 에이전트가 모델을 작성합니다.
- 기존 코드 — 에이전트가 소스를 읽고 구조를 기반으로 B-UML 모델을 구축합니다. (자동 코드 스캐너는 없으며, 에이전트가 읽은 내용을 바탕으로 직접 모델링합니다 — 원클릭 임포터가 아닙니다.)
- 지원되는 B-UML 변환 경로 — PlantUML, Draw.io 또는 UI 목업.
두 가지 전달 방식
한 번 모델링한 후 내장 B-UML 코드(전달 A) 또는 렌더링된 이미지(전달 B)로 전달합니다 — 동일한 모델에서 생성되므로 서로 불일치하지 않습니다. 상황에 따라 선택하세요 (실행 가능해야 하는 설계 문서 → 코드; README에 그림이 필요한 경우 → 이미지), 또는 둘 다 제공할 수 있습니다. 자세한 내용은 아래 전달 섹션을 참조하세요.
결과물이 저장될 위치. 사용자가 대상 문서(README, 설계 문서)를 지정하면 해당 파일에 삽입합니다. 문서를 지정하지 않거나 저장소/시스템의 독립형 다이어그램을 요청하는 경우, 기본적으로 새로운 독립 .md 파일(예: docs/<model>.md)로 전달합니다: 렌더링된 이미지(전달 B) 및/또는 B-UML 코드(전달 A)와 다이어그램이 설명하는 내용을 간략히 설명하는 한두 줄을 포함합니다. 이렇게 하면 단순한 "내 저장소 다이어그램 작성" 요청이 느슨한 SVG가 아닌 커밋 가능한 문서로 변환됩니다. 새 파일을 생성할 때는 위치를 알려주고 (그리고 사용자가 원할 경우 기존 문서에 삽입하는 대안도 제시하세요).
워크플로
1. B-UML 모델 구축 — 설명, 에이전트가 읽은 기존 코드, 또는 지원되는 B-UML 변환 경로(PlantUML / Draw.io / 목업)를 통해
2. model.validate() → 구조적으로 올바른지 확인
그런 다음 하나(또는 둘 다)를 전달합니다:
A) 코드 삽입: .md 파일의 펜스 블록에 DomainModel Python 코드를 넣습니다.
B) 이미지 삽입: 모델을 BESSER의 헤드리스 SVG 엔드포인트에 POST하고(한 번의 HTTP 호출 — 브라우저 없음), 반환된 SVG를 저장한 후(예: docs/img/data-model.svg), 삽입합니다:

3. 모델이 변경되면 모델을 업데이트하고 다시 전달합니다 — 단일 진실 공급원
1. 모델 구축
올바른 다이어그램은 올바른 모델에서 시작합니다. 최소 형태:
from besser.BUML.metamodel.structural import (
DomainModel, Class, Property, Multiplicity,
BinaryAssociation, Generalization, StringType, IntegerType,
)
publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book = Class(name="Book", attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})
book_is_a = Generalization(general=publication, specific=book) # Book is a Publication
# A Book is written by 1..* Authors; an Author writes 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes = Property(name="writes", type=book, multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})
model = DomainModel(
name="Library",
types={publication, book, author},
associations={book_author},
generalizations={book_is_a},
)
assert model.validate()["success"]
이름: 공백이나 하이픈을 사용하지 마세요. 이 최소 형태를 넘어서는 모든 것(열거형, 모든 다중성/컴포지션 패턴, 연관 클래스, 일반화 집합, 메서드, 검증 세부 정보)은 이 스킬에 번들로 제공되는 references/class-diagram.md 를 참조하세요. 클래스가 아닌 모델 유형(객체, 피처, 배포, OCL 등)은 BESSER 플랫폼의 besser-user 스킬을 참조하세요.
가져오기 가능한 형태 — 두 전달 경로 모두에 필수. 모든
Class(...),BinaryAssociation(...),Generalization(...)을 위에 표시된 대로 명시적인 최상위 할당으로 작성하세요. BESSER의 임포터(SVG 엔드포인트와 편집기의 가져오기에서 사용됨)는 파일의 구조를 읽습니다 — 실행하지 않습니다 — 따라서 헬퍼 함수나 루프 내부에서 작성된 관계는 보이지 않습니다: 클래스는 가져오지만 연관은 조용히 사라집니다. 관계당 하나의 리터럴 명령문을 사용하세요.임포터가 파일을 실행하지 않기 때문에
model.validate()는 렌더링 경로에서 실행되지 않습니다 — 엔드포인트를 통해 렌더링하기 위해 BESSER가 설치되어 있을 필요는 없습니다.validate()호출은 BESSER가 로컬에 있을 때(그리고 코드를 생성하기 전에) 유지하세요. 엔드포인트의 경우 아무 작업도 하지 않으며 필수 사항이 아닙니다.
모델의 출처:
- 설명에서 — 위와 같이 작성합니다.
- 기존 코드에서 — 소스를 읽고 그 구조(클래스, 필드, 관계, 상속)를 B-UML 모델로 변환합니다. 에이전트가 모델링을 수행하며 자동 코드 스캐너는 없습니다.
- PlantUML / Draw.io / UI 목업에서 — 해당하는 B-UML 변환(BESSER 플랫폼에서 사용 가능)을 사용한 후 계속 진행합니다.
이제 두 가지 방법 중 하나로 전달합니다.
전달 A — B-UML 코드를 문서에 삽입
모델을 .md 파일의 펜스 ```python 블록에 직접 넣습니다. 이 코드는 올바르고, validate()로 확인되었으며, 재실행 가능하고 편집기로 가져올 수 있습니다. 문서 자체가 모델을 포함해야 할 때(설계 문서, 명세) 가장 적합합니다:
## 데이터 모델
```python
# (위의 DomainModel)
```
이 B-UML 모델은 도메인의 진실 공급원입니다 — `validate()`로 확인되었으며, 모든 BESSER 생성기의 입력입니다.
전달 B — 렌더링된 이미지 삽입
모델은 BESSER의 렌더러를 통해 실제 그림이 되므로 이미지는 항상 모델과 일치합니다. 두 가지 방법 중에서 선택하세요: 자동 처리 또는 수동 조정.
B1. 자동 렌더링(기본값) — 한 번의 HTTP 호출, 브라우저 없음
BESSER는 헤드리스 B-UML → SVG 엔드포인트를 제공합니다. 에이전트가 모델 .py 파일을 POST하면 SVG를 반환합니다 — 편집기, 수동 단계, 사용자가 클릭할 작업이 없습니다:
curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
-F "[email protected];type=text/x-python" \
-o docs/img/data-model.svg
엔드포인트는 B-UML을 파싱하고 자동으로 레이아웃을 배치한 후 image/svg+xml을 반환합니다. 저장소에 저장하고 다음을 사용하여 삽입합니다:

- 모델 파일은 가져오기 가능한 형태(§1의 설명 참조)여야 합니다 — 편집기에서 가져오는 것과 동일한 형태입니다. 클래스 다이어그램만 가능합니다.
- 레이아웃은 자동입니다. 배치가 중요할 때는 B2로 수동 조정하세요.
.py파일은 BOM 없는 UTF-8로 저장하세요 — 선행 바이트 순서 표시가 있으면 엔드포인트가 파일을 거부합니다(HTTP 400).- 여기서 렌더링할 모델에서는 열거형 리터럴
default_value=...를 생략하세요 — 현재 엔드포인트가 이로 인해 실패합니다(HTTP 500). 코드 생성에는 문제가 없으며, 속성 유형으로 사용된 일반 열거형은 정상적으로 렌더링됩니다. - 200이 아닌 응답은 작은 JSON 오류이며 SVG가 아닙니다(
{ "detail": ... }) — 저장 전에 상태를 확인하세요.
B2. 편집기에서 수동 내보내기(레이아웃이 중요할 때)
https://editor.besser-pearl.org를 열고, .py 파일을 가져오기(B-UML 형식 선택)한 후 상자와 경로 선을 원하는 대로 드래그하고, 내보내기를 클릭하여 형식을 선택합니다:
- SVG — 모든 크기에서 선명하며 문서와 웹에 가장 적합합니다.
- PNG — 투명 배경.
- PNG (흰색 배경) — 불투명한 이미지가 필요한 표면용.
저장소에 저장하고 동일한 방식으로 삽입합니다. (편집기는 모델을 B-UML 또는 JSON으로도 내보낼 수 있습니다 — 이는 모델이지 이미지가 아닙니다.)
어느 방법이든 SVG와 PNG는 플러그인 없이 GitHub, GitLab, 문서 사이트, 위키, 슬라이드 등 마크다운 이미지가 지원되는 모든 곳에서 렌더링됩니다.
불일치 방지
어느 방식을 선택하든 모델이 진실 공급원입니다. 요구 사항이 변경되면 모델을 업데이트하고 다시 전달하세요(코드를 다시 붙여넣거나 이미지를 다시 내보내기) — 내보낸 SVG/PNG를 수동으로 편집하지 마세요. 생성된 것입니다.
그림 이상의 가치
다이어그램은 실제 B-UML 모델이므로 동일한 아티팩트로 Python 클래스, SQL, FastAPI 백엔드, Django, React 등 동작하는 코드를 생성할 수 있습니다. 시스템을 설명하기 위해 그린 다이어그램이 시스템이 될 수 있습니다. 코드를 생성하려면 besser-generators 스킬을 참조하세요.
관련 스킬 참조 시점
- 심층 모델 구축(열거형, 상속, 메서드, OCL, 객체/피처/배포/NN/양자 모델) → besser-user 스킬.
- 모델에서 코드 생성 → besser-generators 스킬.
- 오류(가져오기/검증/편집기 문제) → besser-troubleshooting 스킬.