Community이미지github.com

유니코드 다이어그램

아키텍처, 시스템 설계 및 흐름도를 유니코드 상자 그리기 문자(┌─┐ │ └─┘ ░ 그림자)로 그립니다. 텍스트 다이어그램, ASCII 또는 상자 그리기 다이어그램이 필요하거나 설계 문서나 README에 다이어그램을 넣을 때 사용하세요.

유니코드 다이어그램란 무엇인가요?

이 기술은 개발자가 텍스트 전용 환경(터미널, 설계 문서, README)에서 아키텍처, 시스템 설계 및 흐름도를 그릴 때 사용합니다. 일반 ASCII 문자 대신 유니코드 상자 그리기 문자(┌─┐, └─┘, ░ 그림자 등)를 사용하여 더 선명하고 표현력 있는 다이어그램을 생성합니다. 주요 기능은 `textdiagram.py` 엔진을 통해 제공되며, 상자, 화살표, 경로, 버스, 프레임 등을 자동으로 정렬하여 그립니다. 모든 텍스트는 대문자로 변환되며(일부 단위 제외), 상자는 그림자를 포함하고, 화살표는 채워진 머리(▶) 또는 빈 머리(▷)를 사용할 수 있습니다. 다이어그램은 최대 80열 너비로 제한되며, 엔진은 겹침이나 정렬 오류를 감지하여 `DiagramError`를 발생시킵니다. 이 기술은 Claude Code, Cursor, Codex와 같은 AI 에이전트에서 사용하도록 설계되었으며, 사용자가 다이어그램을 요청할 때 엔진을 `/tmp/textdiagram/textdiagram.py`에 생성하고 Python 스크립트를 실행하여 결과를 출력합니다. 출력된 다이어그램은 수동으로 편집하지 않고 스크립트를 수정하여 다시 실행하는 방식으로 작업합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rohalrafael/unicode-diagrams/tree/HEAD

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

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

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

문서

유니코드 다이어그램은(는) 무엇을 하나요?

유니코드 상자 그리기 문자를 사용하여 일반 텍스트로 다이어그램을 그립니다. 하나의 일관된 스타일을 사용합니다. 항상 아래 textdiagram.py 그리드 엔진으로 다이어그램을 빌드하세요. 직접 그리지 마세요: 직접 그리면 정렬이 어긋납니다.

스타일 규칙

  • 펜스 코드 블록 안의 일반 텍스트. Mermaid, SVG, 이미지 또는 이모지는 사용하지 않습니다.
  • 너비: 기본값 80열. 변경하려면 생성자에 max_width를 전달하세요. 예: D(max_width=100). 엔진은 더 긴 줄에서 오류를 발생시킵니다.
  • 모든 텍스트는 대문자입니다. 엔진이 자동으로 처리합니다: 스크립트에는 일반 텍스트를 작성하세요. 예외: 대소문자에 따라 의미가 달라지는 단위는 정확히 다음과 같이 작성하면 그대로 유지됩니다: Hz kHz MHz GHz, kB MB GB TB KiB MiB GiB TiB, kb Mb Gb Tb kbps Mbps Gbps, ms µs ns. NGINX나 K8S 같은 다른 단어는 대문자로 표시됩니다.
  • 컴포넌트 상자(시스템의 일부: 서비스, 클라이언트, 데이터베이스, 큐, 워커): 가는 선 ┌─┐ │ └─┘에 오른쪽 한 열, 아래 한 행의 가는 ░ 그림자 추가. 부분을 그룹화하려면 상자를 여러 섹션으로 나눕니다: 가는 구분선 ├───┤, 하나의 프레임, 하나의 그림자.
  • 제목 상자(문서의 주요 제목, 다이어그램당 하나): 이중선 ╔═╗ ║ ╚═╝, 그림자 없음. 한 줄에 하나의 항목(이름, 문서 유형, 버전), 각 줄은 상자 중앙에 정렬. d.header(...)로 생성: 엔진이 상자를 전체 다이어그램 위에 가운데 정렬합니다. 선택 사항: 왼쪽에 메타 상자(회사, RFC, 날짜)와 오른쪽에 스탬프 상자(상태). 세 상자 모두 같은 높이를 가집니다. 제목 상자의 패딩 줄은 중앙 점 ·을 포함합니다. 헤더 상자에서 시작하거나 끝나는 화살표는 없습니다.
  • 프레임 상자(섹션 헤더, 메모, 콜아웃): 가는 선, 그림자 없음. 메모/콜아웃: 상단 테두리에 이름을 넣습니다. 예: ┌─ NOTE ───┐. 범례를 추가하지 마세요: 모든 다이어그램에서 스타일이 동일합니다.
  • 자유 텍스트(d.annotate): 상자 없는 짧은 설명, 다이어그램 옆에 위치. 드물게 사용합니다. 줄이 자유 텍스트를 가로지르면 안 됩니다.
  • 수평 화살표: 선 안에 레이블, 양쪽에 공백 하나씩: ── HTTPS ──▶. 양쪽 끝이 상자에 닿음: 선은 보내는 상자의 그림자 열에서 시작하고 머리는 받는 상자에 닿습니다.
  • 수직 화살표: 선은 하단 테두리의 ┬에서 시작, ▼로 끝남. 레이블은 선 오른쪽, 그림자 아래 한 행에 위치. 또는 레이블을 선에 삽입(inline=True): 선, 빈 행, 선에 가운데 정렬된 레이블 행, 빈 행, 선.
  • 꺾인 화살표(d.route): 여러 번 꺾일 수 있음, 모든 방향 가능(▲ ▼ ◀ ▶). 레이블은 가로 세그먼트 내부에, 또는 세로 세그먼트 옆에(또는 inline=True로 세로 세그먼트에 삽입) 위치. 교차하거나 합류하는 선은 접합 문자(┼ ├ ┤ ┬ ┴)를 생성. 선은 절대 상자를 통과하지 않습니다.
  • 버스(d.fan_out): 하나의 상자에서 나와 대상당 하나의 화살표로 분기. 레이블은 공유 선에 위치.
  • 화살표 머리: 채워짐 ▶ ◀ ▲ ▼은 주요 흐름. 빔 ▷ ◁ △ ▽은 두 번째 관계 유형(비동기, 선택, 이벤트). 다이어그램에 두 가지 유형이 필요한 경우에만 빈 머리를 사용하고, 레이블이나 메모에 의미를 명시하세요(범례는 사용하지 않음).
  • 모든 화살표에 무엇이 흐르는지(프로토콜, 이벤트, 데이터) 레이블을 붙입니다.
  • 상자의 역할이 명확하지 않은 경우: 시스템 부분은 COMPONENT, 주요 제목은 TITLE, 나머지는 FRAME을 사용하세요.

워크플로우

  1. 그리기 전에 컴포넌트, 프레임 및 화살표를 나열합니다.
  2. 엔진을 /tmp/textdiagram/textdiagram.py에 작성합니다(전체 소스는 이 파일 끝에 있으며, 정확히 복사하세요). 매 세션마다 다시 작성하여 이전 버전이 사용되지 않도록 합니다.
  3. 엔진을 가져오고 다이어그램을 빌드하는 짧은 Python 스크립트를 작성합니다. 레이아웃 도우미를 사용하여 상자를 배치합니다(좌표를 추측하지 마세요):
    • Diagram.x_right_of(a, label) — 화살표 레이블 공간을 확보하여 a 오른쪽에 배치할 다음 상자의 x 좌표.
    • Diagram.x_left_of(a, lines, label) — 레이블 공간을 확보하여 a 왼쪽에 배치할 새 상자의 x 좌표.
    • Diagram.y_below(a) — a 아래에 배치할 상자의 y 좌표. 인라인 레이블 포함: Diagram.y_below(a, lines=N).
    • Diagram.x_centered_under(a, lines) — a 아래 중앙에 상자를 배치할 x 좌표(arrow_v에 필요).
    • 경로 레인에는 상자의 가장자리를 사용합니다: a.right + 4, a.bottom + 2.
  4. 실행합니다. DiagramError가 발생하면 메시지에 따라 레이아웃을 수정하고 다시 실행합니다.
  5. 출력을 정확히 인쇄된 대로 코드 블록에 붙여넣습니다. 수동으로 편집하지 마세요. 변경하려면 스크립트를 수정하고 다시 실행하세요.

예시 1: 헤더, 섹션, 경로

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()                                                   # max_width=80이 기본값
t = d.header(["Order Platform", "Architecture"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"])                             # role="component"이 기본값
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # 섹션: 하나의 상자, 하나의 그림자
            [["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls")  # S자 형태
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Reads", row=svc.rows[1])           # 하나의 섹션에 연결
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events")  # 한 번 꺾음
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # 루프: 세 번 꺾음
        via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())

출력:

┌────────────┐               ╔══════════════════╗            ┌───────────────┐
│  ACME INC  │               ║  ORDER PLATFORM  ║            │  *~~~~~~~~~*  │
│  RFC 9000  │               ║   ARCHITECTURE   ║            │   DEEP DIVE   │
│  NOV 2026  │               ║        ·         ║            │  *~~~~~~~~~*  │
└────────────┘               ╚══════════════════╝            └───────────────┘

┌──────────┐            ┌───────────┐                             ┌─────────┐
│  CLIENT  │── HTTPS ──▶│  GATEWAY  │░                            │  AUDIT  │░
└──────────┘░           └─────┬─────┘░                            └─────────┘░
 ░░░░░▲░░░░░░            ░░░░░│░░░░░░░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └───── CALLS ─────┐                      │
      │                                         │                      │
      │                                         ▼                      │
      │                                 ┌─ SERVICES ────┐              │
      │                                 │  AUTH         │─── EVENTS ───┘
      │          ┌─────────┐            ├───────────────┤░
      │          │  CACHE  │◀─ READS ───│  ORDERS       │░
      │          └─────────┘░           ├───────────────┤░
      │           ░░░░░░░░░░░           │  BILLING      │────┐
      │                                 └───────────────┘░   │
      │                                  ░░░░░░░░░░░░░░░░░   │
      │                                                      │
      └─────────────────────── RETRY ────────────────────────┘

예시 2: 버스, 빈 머리, 인라인 레이블, 자유 텍스트

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow")  # 버스, 빈 머리
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True)       # 레이블이 선에 삽입됨
d.annotate(46, y + 16, ["At-least-once", "delivery"])     # 자유 텍스트, 상자 없음
print(d.render())

출력:

┌────────────┐        ╔═════════════╗       ┌─────────────┐
│  ACME INC  │        ║  EVENT BUS  ║       │  *~~~~~~~*  │
│  ADR 12    │        ║    DESIGN   ║       │    DRAFT    │
│  NOV 2026  │        ║      ·      ║       │  *~~~~~~~*  │
└────────────┘        ╚═════════════╝       └─────────────┘

                                    ┌───────────┐
                            ┌──────▷│  BILLING  │░
┌─────────────┐             │       └───────────┘░
│  PUBLISHER  │── EVENTS ───┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
    NIGHTLY                 ├──────▷│  AUDIT  │░
    BACKUP                  │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARCHIVE  │░             └──────▷│  SEARCH  │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                              AT-LEAST-ONCE
                                              DELIVERY

API 참조

  • D(max_width=80) — 다이어그램 생성; max_width는 열 제한.
  • d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left") → Box (.x .y .w .h .right .bottom .cx .rows; right/bottom은 그림자 포함). lines는 문자열 리스트이거나, 상자를 분할할 섹션(문자열 리스트의 리스트)입니다. box.rows는 각 섹션의 화살표 행을 보유합니다. align="center"는 텍스트를 중앙 정렬합니다.
  • d.header(title, left=None, right=None, y=0) → title Box. 각 인수는 문자열 리스트입니다. 상자는 렌더링 시 최종 x를 얻습니다. 다이어그램당 하나의 헤더.
  • d.arrow_h(a, b, label="", row=None, head="filled") — a와 b가 나란히 있음; 양방향 작동. row는 섹션 행을 선택합니다(a.rows[i]). head는 "filled" 또는 "hollow".
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b가 a 아래, 중앙에 위치. 레이블은 여러 줄일 수 있습니다("\n"). inline=True인 경우 Diagram.y_below(a, lines=N)으로 공간을 확보하세요.
  • d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False) — sides는 "left" "right" "top" "bottom". 선은 a의 a_side에서 나와 b의 b_side로 들어갑니다. len(via) + 2개의 세그먼트를 가지며, 가로와 세로가 번갈아 나타나고 a_side에서 나가는 방향으로 시작합니다. 각 via 값은 중간 세그먼트 하나의 레인입니다: 세로 세그먼트의 x, 가로 세그먼트의 y. via=[]은 한 번 꺾음, 하나의 값은 두 번 꺾음(S 또는 U자 형태), 두 개의 값은 세 번 꺾음(루프). a_row / b_row는 섹션 행을 선택합니다. label_seg는 레이블을 전달할 세그먼트(0부터 시작)를 선택합니다.
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — 버스. trunk는 공유 선의 레인입니다: 왼쪽/오른쪽면의 경우 x, 위쪽/아래쪽면의 경우 y.
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — 한 번 꺾음, route의 짧은 형태. vh: a의 하단을 나와 b의 측면으로 회전. hv: a의 측면을 나와 b의 상단으로 회전. 방향은 b의 위치를 따릅니다.
  • d.annotate(x, y, lines, align="left") → Box (역할 "text") — 자유 텍스트, 대문자화됨. lines는 문자열("\n"은 새 줄 시작) 또는 리스트.
  • d.text(x, y, s) — 원시 텍스트(대문자화되지 않음).
  • d.render() — 다이어그램 반환; 헤더 배치; 너비 및 와이드 문자 확인.
  • 엔진은 겹침, 작은 간격, 잘못된 레인 값 또는 최대 너비 초과 시 DiagramError를 발생시킵니다.

셸을 사용할 수 없는 경우

동일한 규칙으로 직접 그리십시오. 그런 다음 각 줄의 열을 세고 다음을 확인하십시오: 오른쪽 그림자는 상자 오른쪽 한 열; 아래쪽 그림자 행은 상자 왼쪽 가장자리에서 한 열 오른쪽에서 시작하여 그림자 열에서 끝남; 모든 상자 가장자리가 정렬됩니다.

엔진 소스: textdiagram.py

"""textdiagram: 문자 그리드에 정렬된 유니코드 상자 다이어그램을 그립니다.

스타일:
  모든 텍스트는 KEEP의 단위를 제외하고 대문자입니다.
  COMPONENT 상자: 가는 선 + 오른쪽 한 열, 아래 한 행의 가는 그림자(░).
  TITLE 상자: 이중선, 그림자 없음, 다이어그램 위에 가운데 정렬(렌더링 시 배치).
  FRAME 상자: 가는 선, 그림자 없음(메모, 콜아웃).
  헤더: 제목 상자와 선택적 메타 상자(왼쪽) 및 스탬프 상자(오른쪽);
  제목 상자의 패딩 줄은 가운데 점을 포함합니다.
  섹션: 가는 구분선으로 분할된 하나의 상자, 전체 상자에 대해 하나의 그림자.
  수평 화살표: 선 안의 레이블, 양쪽 끝이 상자에 닿음:  ── LABEL ──▶
  수직 화살표: 선 오른쪽의 레이블, 그림자 아래 한 행.
  경로: 레인 좌표(via)로 설정된 여러 번 꺾인 화살표.
  머리: 채워짐(▶) 또는 빔(▷). fan_out: 하나의 선이 여러 화살표로 분할.
  위/아래 선의 레이블: 선 옆, 또는 선에 삽입(inline=True).
  annotate: 상자 없는 자유 텍스트.
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # 화살표 레이블 양쪽의 대시 수
HEADER_GAP = 2  # 헤더 상자 사이의 열

# 대소문자에 따라 의미가 달라지는 단위 (MB = 바이트, Mb = 비트, ms = 밀리, MS = 메가).
# 단어는 정확히 다음 중 하나와 같이 작성된 경우에만 유지됩니다.
KEEP = {
    "Hz", "kHz", "MHz", "GHz",
    "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
    "kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
    "ms", "µs", "ns",
}

# 상자 그리기 문자를 팔 집합으로: 두 개의 화살표 선이 만나는 곳에서 팔이
# 하나의 접합 문자(┼, ├, ...)로 결합됩니다.
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): 

관련 스킬