Communitygithub.com

BESSER-PEARL/uml-drawing

올바른 UML 클래스 다이어그램을 BESSER B-UML로 그리고, 한 번의 호출로 삽입 가능한 SVG/PNG로 렌더링합니다. README, 설계 문서, 위키, 슬라이드용.

uml-drawing란 무엇인가요?

이 스킬은 AI 에이전트가 정확한 UML 클래스 다이어그램을 생성하고 문서에 바로 삽입 가능한 이미지로 제공할 수 있도록 합니다. 일반적인 '다이어그램 추가' 요청 시 발생하는 오류(잘못된 다중성, 화살표 방향 오류, 상속 관계 실수)를 방지하며, BESSER B-UML 프레임워크를 사용하여 다이어그램을 모델 기반으로 구축합니다. 이 스킬은 클래스 다이어그램에 특화되어 있으며, 자연어 설명, 기존 코드 분석, 또는 PlantUML/Draw.io 같은 도구에서 변환하여 모델을 생성할 수 있습니다. 생성된 모델은 B-UML 코드로 삽입하거나, BESSER의 헤드리스 SVG 엔드포인트를 통해 이미지로 렌더링할 수 있어 문서와 이미지가 항상 일치합니다. 마크다운, 위키, 슬라이드 등에서 플러그인 없이 사용 가능하며, 동일한 모델로 코드 생성도 가능하여 설계 문서가 곧 실행 가능한 시스템이 될 수 있습니다.

지원 대상✓Claude Code~Codex CLI✓Cursor✓Windsurf
npx skills add BESSER-PEARL/uml-drawing

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

데이터 모델

문서

문서에 올바른 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), 삽입합니다:
     ![데이터 모델](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을 반환합니다. 저장소에 저장하고 다음을 사용하여 삽입합니다:

![데이터 모델](docs/img/data-model.svg)
  • 모델 파일은 가져오기 가능한 형태(§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 스킬.

관련 스킬