동일한 프롬프트, 동일한 다이어그램

Prateek Rai가 tldraw-canvas-kit를 출시했습니다. 이는 Claude Code나 Cursor와 같은 로컬 AI 어시스턴트가 오프라인 tldraw 데스크톱 앱을 제어하여 매번 동일한 엔지니어링 다이어그램을 생성할 수 있게 해주는 19가지 "Agent Skills" 모음입니다. 이 키트는 클라우드 연결이나 텔레메트리(telemetry) 없이 작동하므로, 팀은 시각적 자산을 완전히 온프레미스(on-premises) 상태로 유지할 수 있습니다.

로컬 기반의 결정론적(deterministic) 다이어그램 도구가 중요한 이유

엔지니어링 팀은 슬라이드 데크, 문서 사이트, 디자인 도구 사이에서 플로우차트, 클래스 다이어그램, 아키텍처 맵을 옮기느라 수많은 시간을 소비합니다. 복사하여 붙여넣는 각 단계에서 선 스타일이 바뀌거나, ID가 재생성되거나, 레이아웃이 어긋나는 등 미세한 변화가 발생합니다. LLM이 다이어그램을 다시 생성할 때, 텍스트 프롬프트가 동일하더라도 결과물의 배치가 달라지는 경우가 많습니다. 감사(audit) 가능한 문서나 재현 가능한 디자인 결과물이 필요한 조직에게 이러한 가변성은 리스크가 됩니다.

Prateek은 두 가지 페인 포인트(pain points)를 해결하기 위해 tldraw-canvas-kit를 구축했습니다: (1) 사용자의 기기에서 완전히 실행되는 도구, 그리고 (2) 동일한 프롬프트가 동일한 다이어그램을 생성한다는 보장. AI 에이전트가 호출할 수 있는 로컬 HTTP API를 노출함으로써, 이 키트는 네트워크 지연, 데이터 유출 위험, SaaS 구독의 필요성을 제거합니다.

키트 작동 방식

  • 오프라인 코어 – tldraw 데스크톱 앱은 JSON 인코딩된 명령을 수락하는 로컬 서버를 실행합니다. 외부 호출은 발생하지 않으며, 사용 데이터가 기기 외부로 유출되지 않습니다.
  • Agent Skills – 각 스킬은 레이아웃 수학, 스텐실(stencil) 선택, 안정적인 ID와 같은 고정된 구조 사양을 인코딩합니다. 에이전트가 스킬을 호출하면 결정론적인 드로잉 명령 세트를 받게 됩니다.
  • 멱등성(Idempotent) 업데이트 – 스킬이 기존 다이어그램에 실행되면, 도형을 제자리에서 업데이트하고, 불필요한 요소를 제거하며, 엣지(edge)를 다시 고정합니다. 그 결과 중복 객체가 쌓이지 않고 새로고침할 수 있는 캔버스가 만들어집니다.
  • 파일 형식 – 다이어그램은 일반 .tldraw 파일로 저장됩니다. 레이아웃 로직이 파일 내부에 포함되어 있기 때문에, 데크를 공유하면 해당 뷰를 재현하는 데 필요한 탐색 규칙도 자동으로 포함됩니다.

이 키트는 시퀀스 및 플로우차트부터 ER 다이어그램, 상태 머신(state machines), 스윔레인(swimlanes), 유스케이스(use-case), 컴포넌트, 패키지, 배포, 아키텍처, 마인드 맵, 코드베이스 맵에 이르기까지 13가지 다이어그램 카테고리를 지원합니다. 사용자는 원하는 다이어그램을 설명하기만 하면 되며, 스킬이 하위 구조를 처리합니다.

개발 과정에서 얻은 교훈

  1. 화살표 스타일이 기본적으로 손으로 그린 듯한 모습으로 설정됨 – 깔끔한 선을 요청하더라도 API는 처음에 스케치 스타일의 화살표를 생성합니다. 스타일을 변경하려면 스킬이 후속 명령을 내려야 합니다.
  2. 화살표가 도형과 조용히 교차할 수 있음 – 커넥터가 노드를 통과하더라도 API는 오류를 발생시키지 않습니다. 이러한 충돌을 잡아내려면 생성된 스크린샷을 시각적으로 확인해야 합니다.
  3. 짧은 화살표에서 엣지 레이블 줄바꿈 오류 발생 – 커넥터가 너무 짧으면 레이블이 제대로 줄바꿈되지 않을 수 있으므로, 스킬이 최소 길이를 강제하거나 레이블 위치를 조정해야 합니다.

이러한 특이 사항들은 왜 스킬이 API에 대한 가정이 아닌, API의 실제 동작을 기반으로 구축되었는지를 잘 보여줍니다.

키트 설치 및 사용법

npx skills add prateek11rai/tldraw-canvas-kit

이 명령은 macOS와 Linux에서 작동합니다. 설치 후, 동일한 워크스테이션의 AI 에이전트는 로컬 문서를 쿼리하고, 코드를 생성하며, 실행 중인 tldraw 서버로 드로잉 명령을 보낼 수 있습니다. 그 결과, 호스트를 벗어나지 않고도 추가 편집이 가능하거나 프레젠테이션으로 내보낼 수 있는 재현 가능한 다이어그램이 생성됩니다.

수혜 대상 및 트레이드오프(trade-offs)

  • 보안 중심 팀 – 엄격한 데이터 처리 정책을 가진 기업은 모든 디자인 결과물을 방화벽 뒤에 유지할 수 있습니다.
  • 문서화 엔지니어 – 버전 관리 저장소에 다이어그램을 포함해야 하는 경우, 결정론적인 신뢰할 수 있는 소스(source of truth)를 얻을 수 있습니다.
  • 개인 기여자 – LLM 실행 후 매번 수동으로 레이아웃을 조정하는 데 지친 개발자는 이 프로세스를 자동화할 수 있습니다.

주요 제한 사항은 로컬에서 실행되는 tldraw 인스턴스에 의존한다는 점입니다. 이미 클라우드 기반 다이어그램 서비스에 의존하고 있는 조직은 데스크톱 앱을 도입하고 워크플로우를 조정해야 합니다. 또한, 현재의 스킬 세트는 커스텀 스텐실 라이브러리를 지원하지 않으므로 사용자는 미리 정의된 도형 내에서 작업해야 합니다.

다음 단계

Prateek은 커뮤니티 피드백을 바탕으로 기술 라이브러리를 확장하고 Windows 지원을 추가하여 잠재적 사용자층을 넓힐 계획입니다. 또한 그는 제3자 에이전트들이 이 키트를 통합하여, 모두 동일한 결정론적 코어를 공유하는 특화된 다이어그램 생성기 마켓플레이스가 형성되기를 기대하고 있습니다.

핵심 요약

tldraw-canvas-kit은 AI 기반의 다이어그램 생성이 반드시 클라우드 전용의 확률론적 프로세스일 필요는 없다는 것을 증명합니다. 그리기 로직을 로컬 API에 고정하고 안정적인 식별자를 강제함으로써, 엔지니어는 개인정보 보호나 제어권을 희생하지 않고도 재현 가능하며 감사 준비가 된 시각 자료를 생성할 수 있습니다.