업무를 하면서 저는 엔지니어링 다이어그램과 가끔씩 발표 자료(deck)를 계속해서 만들어냅니다. 그것들은 그때그때 가장 가까운 도구—여기서는 화이트보드 앱, 저기서는 슬라이드 앱—에 담기게 되며, 결코 일관되지 않고, 영구적이지 않으며, 항상 일회성으로 끝납니다.

저는 두 가지를 원했습니다. 로컬(locally)에서 실행되는 도구, 그리고 매번 매번 똑같이 보이는 결과물입니다. 그래서 저는 이틀 동안 코딩 에이전트(coding agents)에게 캔버스 앱을 제어하는 법을 가르쳤고, 이를 tldraw-canvas-kit로 출시했습니다.

이것은 무엇인가

tldraw-canvas-kit는 코딩 에이전트—Claude Code, Cursor, Codex, 또는 skills CLI가 지원하는 무엇이든—가 로컬 API를 통해 무료 tldraw offline desktop app을 제어할 수 있게 해주는 19개의 Agent Skills 세트입니다. 13가지 다이어그램 유형(시퀀스(sequence), 플로우차트(flowchart), ER, 상태(state), 클래스(class), 액티비티 스윔레인(activity swimlanes), 유스케이스(use-case), 컴포넌트(component), 패키지(package), 배포(deployment), 아키텍처(architecture), 마인드맵(mindmap), 그리고 리포지토리(repo)를 역공학하는 코드베이스 맵(codebase map))를 비롯하여, 프레젠테이션, 백서(whitepapers), 인터랙티브 위젯(interactive widgets), 내보내기(export), 그리고 테마 설정(theming)을 지원합니다.

당신은 의도(intent)를 설명하고, 스킬(skill)이 구조를 담당합니다. 그 역할 분담이 핵심입니다.

왜 tldraw Offline인가

오프라인 앱이 돌파구였습니다. 이 앱은 로컬 HTTP 서버—포트와 실행 시마다 생성되는 베어러 토큰(bearer token)이 포함된 server.json—를 실행하므로, 동일한 머신에 있는 에이전트가 문서를 검색하고, 라이브 에디터에 대해 코드를 실행하며, 문서에 영구적인 스크립트를 설치할 수 있습니다. 클라우드도, 계정도, 저와 제 다이어그램 사이의 텔레메트리(telemetry)도 없습니다.

문서는 일반적인 .tldraw 파일입니다. 그리고 앱이 자체 SDK를 제공하기 때문에, 문서에 포함된 스크립트는 라이선스 키가 필요하지 않습니다—동작 방식이 파일 내부에 함께 이동하기 때문입니다. 누군가에게 발표 자료를 보내면 필름스트립(filmstrip) 탐색 기능도 함께 전달됩니다.

결정론(Determinism)이 곧 제품이다

LLM은 이미 시퀀스 다이어그램(sequence diagram)이 무엇인지 알고 있습니다. 하지만 두 번 물어보면, 두 개의 서로 다른 레이아웃, 두 개의 서로 다른 화살표 스타일, 두 개의 서로 다른 모든 것들을 얻게 됩니다. 에이전트(agent)에게 부족한 것은 지식이 아니라 일관성(consistency)입니다.

따라서 각 기술(skill)은 고정된 구조 사양(spec)입니다. 레이아웃 수학, 스텐실(stencils), 안정적인 ID 체계, 그리고 키트가 생성하는 모든 도형에 대한 meta 태깅 등이 포함됩니다. 동일한 요청은 매 실행마다 동일한 캔버스(canvas)를 생성합니다.

멱등성(Idempotency)은 핵심적인 지지대 역할을 합니다. 기존 다이어그램에 대해 기술을 재실행하면, 도형을 제자리에서 업데이트하고, 사양에서 제외된 항목을 정리하며, 사양이 변경된 엣지(edge)를 조정(reconcile)합니다. 마지막 항목은 어렵게 해결한 버그였습니다. 초기 버전에서는 키가 이미 존재하는 엣지를 건너뛰었는데, 이는 엣지의 스타일을 결코 수정할 수 없음을 의미했습니다. 해결책은 엣지의 meta에 전체 사양을 저장하고, 불일치 시 삭제 후 재생성하는 방식이며, 이는 이제 모든 다이어그램 기술이 따르는 규칙입니다.

현실이 사양을 수정한다

모든 기술은 실제 앱을 대상으로 검증되었으며, 사양은 현실에 의해 반복적으로 수정되었습니다. 제가 발견한 가장 인상적인 세 가지 사례는 다음과 같습니다.

• 화살표가 사용자 정의 점선 스타일을 조용히 무시하고 스케치 스타일로 기본 설정됩니다. 화살표를 먼저 생성한 다음 업데이트해야 합니다. 오류나 경고도 없이, 깔끔한 아키텍처 다이어그램이 조용히 손으로 그린 듯한 모습으로 출력됩니다.
• 화살표가 중간에 있는 도형을 가로질러 직선으로 그려지지만, 린트(lint)가 이를 잡아내지 못합니다. 엣지가 노드(node)의 라벨을 가로지르고 있음에도 문서는 완벽하게 유효성 검사를 통과합니다. 데이터 모델이 문자 그대로 이러한 종류의 결함을 볼 수 없기 때문에, 스크린샷 검토가 필수적인 검증 단계가 되었습니다.
• 화살표가 글자당 약 30px 정도의 길이를 갖지 않으면 엣지 라벨이 단어 중간에서 줄바꿈됩니다. "deliver"가 두 줄에 걸쳐 "deliv-er"가 되는 식의 문제는 직접 눈으로 확인해야만 알 수 있는 종류의 것입니다.

이 모든 과정에 걸친 공통된 패턴은 다음과 같습니다. 모든 실패한 테스트는 기술 문서(skill docs)의 영구적인 규칙이 되었습니다. 테스트 결과물(artifacts)은 사양(specifications)으로 변했습니다. 기술(skills)은 제가 API가 무엇을 할 것이라고 추측한 내용이 아니라, API가 실제로 입증해 보이는 동작 그 자체입니다.

데모가 곧 테스트 스위트(Test Suite)입니다

쇼케이스 덱(showcase deck)은 기술당 하나의 슬라이드로 구성되어 있으며, 슬라이드 _내부_에 실제 미니 다이어그램이 포함된 23개의 슬라이드로 이루어져 있습니다: 시퀀스(sequence), ER, 상태 머신(state machines), 3단계 중첩 배포 구역(three-level-nested deployment zones), 그리고 키트 자체 리포지토리(repo)의 코드베이스 맵(codebase map) 등이 포함됩니다.

총 203개의 도형(shapes)과 45개의 연결된 에지(bound edges)로 구성되어 있으며, 린트(lint) 오류는 단 하나도 발견되지 않았습니다. 또한 빌더(builder)가 충분히 결정론적(deterministic)이어서, 두 개의 별도 문서에서 바이트 단위로 일치하는 개수를 생성해냈습니다. 그래서 저는 이를 통합 테스트(integration test)로 배포했습니다: tests/golden-deck/run.sh는 덱을 다시 빌드하고 정확한 도형 개수, 멱등성(idempotent) 있는 재실행, 그리고 내비게이션 상호작용을 검증(assert)합니다.

README 갤러리와 이 포스트의 모든 스크린샷은 테스트 결과물입니다. 이미지가 올바르게 보인다면, 테스트를 통과한 것입니다.

내 캔버스 안에 React가 있습니다

이 프로젝트에서 발견한 가장 놀라운 사실은 다음과 같습니다: 문서 스크립트가 정확히 세 개의 모듈 — tldraw, react, react-dom — 을 임포트(import)할 수 있다는 점입니다. 이는 캔버스 위에 실제 클릭 가능한 HTML을 렌더링하는 커스텀 도형 타입(custom shape types)을 만들 수 있음을 의미합니다.

덱의 인터랙티브 슬라이드에는 격자(graticule)가 있는 로우 폴리(low-poly) SVG 세계 지도와 도형 프롭(shape prop)에 의해 구동되는 맥동하는 지역 핀(pulsing region pin)이 박수(claps) 카운터 옆에 배치되어 있습니다. 실제 React 컴포넌트들이 .tldraw 파일 내부에 존재하며, 저장하고 다시 열어도 그대로 유지됩니다.

가장 많은 시간을 잡아먹었던 주의사항(gotcha)은 다음과 같습니다: 렌더 클로저(render closures)가 빠른 클릭을 병합해버리는 문제입니다. 카운터를 빠르게 다섯 번 클릭하면 한 번만 증가하는데, 이는 각 핸들러(handler)가 동일한 오래된 값(stale value)을 캡처했기 때문입니다. 이에 대한 규칙 — 핸들러는 클로저가 아닌 최신 스토어 상태(fresh store state)를 읽어야 한다 — 이 이제 위젯 기술(widget skill)의 계약(contract)에 포함되었습니다.

위젯은 기성품이 아니라 연구의 결과물입니다

이것을 구축하는 동안 에이전트 기술(agent-skills) 생태계를 조사해 보았는데, 한 가지 격차가 눈에 띄었습니다. 기술(skills)들은 기성품 컴포넌트(canned components)를 제공하거나, 아니면 아무것도 제공하지 않거나 둘 중 하나였습니다. 이 키트(kit)는 둘 다 하지 않습니다. 이 키트는 _계약(contracts)_과 연구 교리(research doctrine)를 제공합니다. 먼저 라이브 API를 확인하고, 그다음 도메인 권위 참조(domain-authority references) (tldraw.dev 예시, D3 갤러리, MDN)를 확인한 뒤, 키트의 컨벤션(conventions)으로 포팅(port)합니다.

초기에는 직접 만든 와이어프레임 지구본(wireframe globe)이 있었습니다. 하지만 정확히 이 교리를 위반했다는 이유로 리포지토리(repo)에서 삭제되었으며, 요청 시점에 구축되는 연구된 위치 인식 지도(location-aware map)로 대체되었습니다.

동일한 컨벤션(conventions)이 미디어에도 적용됩니다. 가져온 스크린샷은 .tldraw zip 파일 내부에 번들링(bundled)된 에셋(assets)이 되며, 슬라이드 밖으로 넘치지 않도록 박스 크기에 맞춰 조정(fit-to-box)됩니다. 또한 각 프레젠테이션은 자신의 폴더 내에 존재하며, 그 옆에 에셋(assets)과 내보내기(exports) 파일이 함께 위치합니다.

출시 (Shipping It)

이 키트는 두 가지 방식으로 설치할 수 있습니다: 70개 이상의 에이전트를 위한 skills CLI를 통하거나, 번들링된 캔버스 연산자(canvas-operator) 서브 에이전트(subagent)가 포함된 Claude Code 플러그인으로 설치하는 방식입니다. 모든 기술(skill)은 독립적으로 공급(vendored)되며, CI 체크가 동기화 및 발견을 수행하고, 커밋(commits)은 서명되며, 골든 덱(golden deck)이 회귀 테스트 게이트(regression gate) 역할을 합니다.

npx skills add prateek11rai/tldraw-canvas-kit

링크: repo, v0.1.0 release, skills.sh 페이지.

솔직한 한계점: 현재는 macOS와 Linux만 지원합니다 (Windows는 테스트되지 않았습니다 — 기여를 환영합니다). 또한 오프라인 앱의 API는 새롭고 비공식적이므로, 내부 사항이 변경될 수 있습니다.

나를 위해 만들어진 것 (Built for Me)

제가 이것에 대해 게시했을 때, 다음과 같이 마무리했습니다: 아마도 이것을 사용할 사람은 거의 없을 것입니다. 이것은 저를 위한 것입니다.

그것이 여전히 솔직한 프레임워크입니다. 저는 세션 사이에 다이어그램이 멋대로 움직이는 것을 멈추고 싶었고, 이제는 그렇지 않습니다. 만약 에이전트가 결정론적 (deterministically)으로 제어할 수 있는 로컬 캔버스 (local canvas)가 당신에게도 갈증을 느끼게 한다면 — 단 한 번의 npx 명령어로 실행할 수 있습니다.

tldraw-canvas-kit는 비공식 프로젝트이며, tldraw Inc.와 관련이 없습니다. 오프라인 앱과 그 로컬 API (local API)는 그들의 소유이며 둘 다 매우 훌륭합니다 — 모든 공로는 tldraw 팀에게 있습니다.