Draw.io 다이어그램 엔지니어은(는) 무엇을 하나요?

작은 결정론적 중간 표현(IR)을 통해 다이어그램을 구축합니다. IR을 진실의 원천(source of truth)으로, .drawio 파일을 컴파일된 산출물로 취급합니다.

워크플로우

처음 사용하거나 환경 오류가 발생한 후에는 doctor를 실행하세요. user-workflows.md에서 기능 상태, 스타터 선택, 번들 내용 및 안전한 덮어쓰기 동작을 확인하세요. 덜 일반적인 명령을 구성하거나 종료 코드를 해석할 때는 cli.md를 읽으세요. 레거시 또는 버전이 있는 Diagram IR의 경우 compatibility.md를 읽고 편집하기 전에 migrate --check를 실행하세요.
요청 사항과 관련 소스 자료를 검사하세요. 사용자가 지정하지 않은 경우 적절한 다이어그램 유형, 범위, 방향 및 테마를 유추하세요. 조율된 아키텍처 다이어그램 패키지의 경우 blueprint.md를 읽고, blueprint.schema.json을 기준으로 작성한 후 blueprint를 사용하세요. ERD의 경우 erd.md를 읽고, erd.schema.json을 기준으로 작성한 후 erd를 사용하세요. SQL DDL이 진실의 원천인 경우 이를 직접 수용하세요. 고가용성의 경우 ha.md를 읽고, ha.schema.json을 기준으로 작성한 후 ha를 사용하세요.
가장 작은 구조화된 소스를 작성하거나 적용하세요. 소스가 없으면 init architecture, init blueprint, init erd 또는 init ha를 사용하세요. Diagram IR은 ir-format.md을, 다이어그램별 선택 사항은 authoring.md를 읽으세요. Python/TypeScript 트리, OpenAPI, SQL, Compose, Terraform, Kubernetes, GitHub Actions 또는 GitLab CI에서 시작하는 경우 importers.md를 읽고 import를 사용하여 IR을 생성하세요. 자동 연결자가 시각적으로 모호하게 남아 있거나 고정된 인터페이스가 중요한 경우 명시적 포트를 할당하기 전에 routing.md를 읽으세요. 조직 스타일링이나 더 깊은 시각적 QA가 필요한 경우 style-system.md를 읽고 검증된 테마 팩을 사용하세요. 신뢰할 수 없는 콘텐츠를 가져오거나 릴리스 번들을 준비할 때는 security.md를 읽으세요. 레이블, 설명, 링크, 메타데이터 또는 엔터티 기본값에 절대 자격 증명을 배치하지 마세요.
단일 명령 번들 워크플로우를 선호하세요:
```
python3 <skill-dir>/scripts/drawio_tool.py build source.json \
  -o build/diagram --name diagram --strict
```
이 명령은 정규화된 IR, 편집 가능한 .drawio, 모든 SVG 미리보기, audit.json, security.json 및 bundle.json을 생성합니다. 사용자가 개별 아티팩트나 증분 워크플로우를 필요로 하는 경우에만 하위 수준 명령(compile, validate, preview, security, audit)을 사용하세요.
draw.io Desktop을 사용할 수 있고 Desktop 내보내기가 요청된 경우 desktop-export.md를 읽고 번들의 .drawio에서 렌더링한 후 검증 보고서를 유지하세요:
```
python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \
  -o diagram.png --report diagram.export.json
```
모든 번들 미리보기를 시각적으로 검사하세요. 계층 구조, 잘린 텍스트, 충돌, 불명확한 가장자리, 약한 대비, 과도한 세부 사항을 수정하세요. 가장 좋은 결과를 제시하기 전에 최대 두 번까지 재빌드하세요.
번들의 편집 가능한 .drawio, IR 소스, 감사 보고서, 미리보기 및 요청된 내보내기를 제공하세요. Desktop 내보내기를 건너뛴 경우 이를 명확히 명시하세요.

승인된 아키텍처를 새로 생성된 모델과 비교할 때는 drift.md를 읽고 diff를 실행한 후 기계 판독 가능 보고서와 편집 가능한 드리프트 뷰를 모두 제공하세요.

기존 다이어그램 편집

사용자의 아티팩트를 보존하세요. 검사 및 검증부터 시작하세요:

python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio

의미론적 편집 전에 검토 가능한 Diagram IR을 복구하세요:

python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
  -o existing.diagram.json --report existing.extraction.json --strict

복구된 모델에 의존하기 전에 round-trip.md를 읽으세요. lossless: true는 모든 의미론적 셀이 지원되는 컴파일러 메타데이터를 사용했음을 의미합니다. --strict가 3으로 종료될 때 유효한 최선의 모델이 여전히 작성될 수 있습니다. 원본을 교체하기 전에 유추된 모든 셀을 검토하세요.

IR 기반 다이어그램의 경우 의미론적 연산을 작성하고 원자적으로 적용하세요:

python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json

파괴적이거나 다중 페이지 편집 전에 patching.md를 읽으세요. 추출에서 지원되지 않는 XML 전용 콘텐츠를 보고하면 일치하는 mxCell 값, 스타일 또는 지오메트리만 수정하고 시각적 검토가 통과할 때까지 원본을 보존하세요. 안정적인 ID를 단지 깔끔함을 위해 다시 번호 매기지 마세요.

품질 계약

전달 전에 다음 모두를 충족해야 합니다:

끊어진 가장자리 끝점, 중복 ID, 잘못된 부모 참조 또는 노드 겹침이 없어야 합니다.
레이블이 노드에 맞고 일반 확대/축소에서 읽을 수 있어야 합니다.
방향과 그룹화가 의도된 계층 구조를 전달해야 합니다.
가장자리 레이블은 구현 세부 사항이 아닌 관계를 설명해야 합니다.
색상은 일관된 의미를 가지며 유일한 구분 요소가 되어서는 안 됩니다.
장식적 세부 사항이 기본 읽기 경로를 압도해서는 안 됩니다.

릴리스 게이트로 --strict를 사용하세요. 검사가 실패하거나 다이어그램에 수동 시각적 검토가 필요한 경우 quality-gates.md를 읽으세요.

작성 규칙

node-7과 같은 순서 ID 대신 api-gateway와 같은 안정적이고 의미론적인 ID를 사용하세요.
레이블을 짧게 유지하세요. 더 긴 문맥은 description에 넣으세요.
계층, 신뢰 영역, 제한된 컨텍스트 또는 소유권에 대해 명시적 group 값을 사용하세요.
요청/데이터 파이프라인에는 왼쪽에서 오른쪽을, 프로세스나 계층 구조에는 위에서 아래로를 선호하세요.
다이어그램당 하나의 주요 아이디어를 유지하세요. 모든 것을 축소하기보다는 큰 시스템을 여러 페이지 또는 수준으로 분할하세요.
사용자가 의도적인 배치를 필요로 하는 경우에만 position을 사용하세요. 그렇지 않으면 컴파일러가 노드를 결정론적으로 배치하도록 하세요.
공급업체별 draw.io 스텐실 이름을 추측하지 마세요. 검증된 모양 매핑이 존재할 때까지 중립적인 의미론적 종류를 사용하세요.

도구 동작

scripts/drawio_tool.py는 JSON 입력에 대해 표준 라이브러리 전용입니다. PyYAML이 설치된 경우 YAML 입력이 지원됩니다. 다음을 제공합니다:

doctor: 핵심 파일 및 Python/XML 지원을 확인한 후 선택적 YAML 및 Desktop 기능을 보고합니다.
init: 아키텍처, Blueprint, ERD, HA, 라우팅, 인프라 또는 CI에 대한 안전한 스타터를 복사합니다.
build: 모델 또는 소스를 자동 감지하고 완전히 감사된 drawio-diagram-bundle/v1을 생성합니다.
migrate: 레거시/버전 없는 Diagram IR을 결정론적으로 업그레이드하고 기계 판독 가능 변경 보고서를 출력합니다.
compile: IR을 검증하고, 결정론적 레이아웃을 계산하며, 압축되지 않은 편집 가능한 draw.io XML을 출력합니다.
extract: 압축 또는 비압축 draw.io에서 Diagram IR을 복구하고, 컴파일러 지원 의미론을 보존하며 유추된 모든 레거시 셀을 보고합니다.
blueprint: 하나의 아키텍처 모델을 컨텍스트, 논리, 데이터, 배포, 보안 및 결정 페이지로 프로젝션합니다.
erd: 엔터티, 필드, 키, 유형 및 카디널리티를 검증한 후 모델 또는 SQL DDL에서 편집 가능한 Crow's Foot ERD를 생성합니다.
ha: 장애 도메인, 복제본, 복제, 상태 확인 및 장애 조치를 검증한 후 토폴로지 및 장애 조치 페이지를 생성합니다.
import: Python/TypeScript 모듈 트리, OpenAPI, SQL DDL, Docker Compose, Terraform, Kubernetes, GitHub Actions 또는 GitLab CI를 Diagram IR로 변환합니다.
diff: Diagram IR을 의미론적으로 비교하고, 구조화된 드리프트 보고서를 출력하며, 선택적으로 편집 가능한 색상 및 모양 코딩된 드리프트 뷰를 생성합니다.
patch: 노드, 가장자리, 그룹, 위치 및 다이어그램 변경 사항을 원자적으로 적용합니다.
preview: draw.io Desktop 없이 검토 가능한 SVG를 생성합니다.
security: 모델, .drawio 또는 전체 번들에서 자격 증명, 안전하지 않은 링크, 금지된 XML 구문 및 압축 해제 위험을 스캔합니다.
audit: 구조화된 소스 및 생성된 지오메트리를 검사한 후 수리 제안 및 미리보기 경로와 함께 결과를 그룹화합니다.
validate: IR 또는 .drawio를 린트하고 0–100 품질 점수를 출력하며 --strict 하에서 실패합니다.
inspect: 페이지, 노드, 가장자리, 그룹 및 캔버스 경계를 요약합니다.
render: macOS, Windows 및 Linux에서 draw.io Desktop CLI를 발견하고, DRAWIO_DESKTOP_BINARY 또는 --binary를 존중하며 PNG, SVG, PDF 또는 JPG로 내보냅니다.
verify-export: Desktop을 실행하지 않고 기본 내보내기의 형식 서명, 구조적 종결자, 치수 및 안전한 SVG 콘텐츠를 검증합니다.

처음 사용하기 전에 python3 -c "import xml.etree.ElementTree"를 확인하세요. macOS Homebrew Python이 pyexpat/libexpat 심볼 오류를 보고하는 경우 /usr/bin/python3를 사용하거나 Python 설치를 복구하세요. ABI 실패를 다이어그램 입력 탓으로 돌리지 마세요.

고정 템플릿이 아닌 간결한 시작점으로 example.architecture.json, example.blueprint.json, example.erd.json, example.ha.json, example.routing.json, example.terraform.tf 또는 example.kubernetes.json을 사용하세요. 재사용 가능한 사용자 정의 테마 예제가 유용한 경우 corporate.json을 적용하세요.

Draw.io 다이어그램 엔지니어