PromptBoard를 만든 과정 — AI 프롬프트 구축을 위한 시각적 캔버스

텍스트 박스에 담기 적합하지 않은 유형의 AI 프롬프트가 있습니다.

아이디어가 너무 길어서가 아닙니다 — 언제든 더 많이 쓸 수 있으니까요. 문제는 당신이 전달하고자 하는 내용의 _구조(structure)_가 본질적으로 시각적이라는 점입니다. 당신은 흐름(flow)을 설명하고 있습니다. 이미지를 가리키고 있습니다. 컨텍스트의 일부에는 적용되지만 다른 일부에는 적용되지 않는 제약 조건(constraints)들을 나열하고 있습니다. 당신은 AI에게 한 단락의 글이 아니라 브리핑(briefing)을 제공하려는 것입니다.

텍스트 박스는 모든 것을 1차원으로 강제합니다. 그리고 AI는 아무리 능력이 뛰어나더라도, 당신의 머릿속에 있던 구조를 평면적인 텍스트 문자열로부터 재구성해야만 합니다.

PromptBoard는 접근 방식을 뒤집음으로써 이 문제를 해결합니다. 먼저 프롬프트를 시각적으로 구축한 다음, 이를 내보내는(export) 방식입니다.

복잡한 작업을 프롬프팅할 때 발생하는 문제

AI 에이전트(agents)를 정기적으로 사용하는 모든 개발자는 다음과 같은 패턴에 직면합니다:

수정해야 할 버그가 있습니다. 단순한 버그가 아닙니다 — 설명해야 할 흐름, 고장 난 상태의 스크린샷, 수정 사항이 준수해야 할 서너 가지의 제약 조건, 그리고 올바른 동작이 어떻게 보여야 하는지에 대한 설명이 포함되어 있습니다.

당신은 타이핑을 시작합니다. 작업 설명을 작성하다가, 먼저 흐름을 설명해야 한다는 것을 깨닫습니다. 스크린샷을 붙여넣고 그 주변에 글을 씁니다. 마지막에 제약 조건을 추가하지만, 그것들이 적용되는 특정 부분과 명확하게 연결되지 않습니다. 전송 버튼을 누를 때쯤이면, 프롬프트는 중간에 이미지가 하나 포함된 400단어 분량의 텍스트 벽이 되어 있습니다.

AI는 종종 이를 처리할 수 있습니다. 하지만 당신은 캔버스(canvas)에서 한 번에 명확하게 할 수 있었던 구조적 추론(structural inference)을 AI에게 요구하고 있는 것입니다.

더 깊은 문제는 프롬프트가 **자연스러운 그래프 구조(natural graph structure)**를 가진다는 점입니다. 즉, 노드(nodes)(개념, 제약 조건, 예시)와 그들 사이의 레이블이 지정된 관계(relationships)로 이루어져 있습니다. 텍스트 박스는 해당 그래프를 선형 시퀀스(linear sequence)로 직렬화(serialize)하며 관계 레이블을 버려버립니다.

디자인: 블록, 화살표, 내보내기

PromptBoard는 세 가지 개념을 중심으로 구축되었습니다:

**블록(Blocks)**은 노드입니다. 세 가지 유형이 있습니다:

• Text (텍스트) — 자유 형식의 콘텐츠로, 컨텍스트(context)를 전달하는 주요 매개체입니다. 선택적으로 라벨을 붙일 수 있습니다.
• Image (이미지) — 드래그 앤 드롭하거나 스크린샷을 붙여넣습니다. 내보내기 시 base64로 임베딩됩니다.
• Flow (플로우) — 로직을 시각적으로 설명하기 위한 프로세스/결정/터미널 노드입니다.

**Arrows (화살표)**는 블록을 연결하며 라벨을 가집니다. "이 제약 조건은 이 플로우 단계에 적용됩니다." "이 스크린샷은 이 버그 설명에 대한 증거입니다." 관계는 읽기 순서로부터 추론되는 것이 아니라 명시적입니다.

**Export (내보내기)**는 캔버스를 다시 텍스트, 즉 구조화된 텍스트로 직렬화(serialize)합니다. 블록은 위에서 아래로, 왼쪽에서 오른쪽 순서로 렌더링됩니다. 화살표는 모든 연결과 그 라벨을 나열하는 ## Flow 섹션이 됩니다. 이미지는 base64로 임베딩됩니다. 출력물은 어떤 AI라도 즉시 파싱할 수 있는 Markdown 파일입니다.

왜 폼(form)이 아니라 캔버스인가

이 도구의 첫 번째 버전은 폼(form)이었습니다. 제목 필드, 설명 필드, 제약 조건 필드, 이미지 업로드. 구조화되어 있고, 명시적이며, 읽기 쉬웠습니다.

하지만 사용할 수 없었습니다.

폼의 문제는 고정된 스키마(schema)를 강요한다는 점입니다. 당신의 컨텍스트가 항상 제목과 설명, 그리고 세 개의 제약 조건을 갖는 것은 아닙니다. 때로는 단순히 서로 연결된 두 가지 요소뿐일 수도 있습니다. 때로는 다섯 개의 이미지만 있고 아직 텍스트는 없을 수도 있습니다.

캔버스에는 스키마가 없습니다. 빈 표면에서 시작하여 의미가 있는 곳에 요소를 배치하면 됩니다. 구조는 미리 정의된 폼이 아니라 레이아웃으로부터 나타납니다. 이것은 당신이 문제를 설명하기 전에 생각하는 방식, 즉 선형적(linearly)이 아니라 공간적(spatially)으로 생각하는 방식과 정확히 일치합니다.

음성 받아쓰기 작동 방식

PromptBoard는 모든 텍스트 블록과 화살표 라벨에 음성 받아쓰기 기능을 제공합니다. 두 가지 모드가 있습니다:

Chromium (Chrome, Edge): continuous: true 설정이 적용된 Web Speech API를 사용합니다. 마이크 버튼을 클릭하고 말하면, 전사된 텍스트가 실시간으로 블록에 추가됩니다. 서버도, API도, 지연 시간(latency)도 없습니다. 모델이 브라우저에서 실행됩니다.

Firefox 및 기타 브라우저: MediaRecorder가 오디오를 캡처한 다음, 전사 (transcription)를 위해 로컬 Whisper 서버 (Transcriber, 포트 4324)로 전송합니다. 만약 Transcriber가 실행 중이지 않으면 대화 상자가 나타납니다. 사용자는 말한 내용을 직접 입력하거나 오디오를 다시 재생할 수 있습니다.

이러한 비대칭성은 의도된 것입니다. Chromium의 내장 음성 인식 (speech recognition)은 메모를 작성하는 속도를 맞추기에 충분히 훌륭합니다. Whisper는 더 길거나 기술적인 받아쓰기 (dictation)에 더 적합합니다.

내보내기 형식 (The export format)

# Fix the checkout form

**Goal**
...

AI가 이를 읽을 때, AI는 다음과 같은 정보를 갖게 됩니다: 평이한 언어로 된 작업 (task), 명시적으로 기술된 제약 조건 (constraints), 직접적인 시각적 증거로서의 스크린샷, 그리고 레이블이 지정된 그래프 형태의 흐름 (flow).

기술 아키텍처 (Technical architecture)

PromptBoard는 약 1,100줄 정도의 단일 HTML 파일입니다. 빌드 단계 (build step)도, npm install도, 서버도 필요 없습니다. 브라우저에서 열기만 하면 바로 작동합니다.

상태 (State): 단일 S 객체가 모든 블록, 화살표, 히스토리 스택 (history stack), 그리고 상호작용 상태를 보유합니다. 모든 것은 JSON 직렬화 (JSON-serializable)가 가능합니다. 보드(Boards)는 localStorage에 저장됩니다 (최대 20개의 보드).

실행 취소/다시 실행 (Undo/redo): 스냅샷 기반 히스토리 (JSON.stringify + 상태의 JSON.parse)를 사용합니다. 최대 60개의 스냅샷을 유지합니다. 텍스트 입력창 이외의 모든 곳에서 Ctrl+Z / Ctrl+Y가 작동합니다.

화살표 (Arrows): 블록의 가장자리가 겹치는 것을 피하기 위해 약간의 수직 오프셋 (perpendicular offset)을 가진 SVG 이차 베지에 곡선 (quadratic Bézier curves)으로 렌더링됩니다. 히트 영역 (Hit areas)은 1.5px의 가시적인 경로 위에 14px 너비의 투명한 경로로 구성됩니다.

캔버스 (Canvas): 3000×2000px 크기의 스크롤 가능한 영역입니다. 블록은 position:absolute div입니다. 드래그는 헤더에서의 mousedown + mousemove + document에서의 mouseup을 사용합니다.

강점 (Strengths)

설치 불필요. 도구가 단 하나의 파일에 담겨 있습니다. USB 드라이브에 담거나, 어떤 정적 호스트 (static host)에서든 서빙하거나, 그냥 프로젝트 폴더에 두고 더블 클릭하여 열기만 하면 됩니다.

멀티모달 출력 (Multimodal output). base64 이미지 임베딩 (embedding) 덕분에 내보낸 .md 파일은 자체적으로 완결성을 갖습니다. 즉, 이미지가 텍스트와 함께 이동합니다. 전체 내용을 Claude나 GPT-4o에 붙여넣으면 스크린샷이 그 자리에 그대로 나타납니다.

음성 우선(Voice-first) 친화적. 타이핑보다 생각이 더 빠른 개발자나, 라이브 환경을 디버깅 중이라 양손이 모두 필요한 개발자에게 음성 받아쓰기(Voice dictation)는 키보드를 만지지 않고도 PromptBoard를 사용할 수 있게 해줍니다.

Machina의 나머지 도구들과의 조합 가능성. .md 내보내기(export)는 BugCapture가 생성하는 것과 동일한 형식입니다. 자연스러운 워크플로우는 다음과 같습니다: BugCapture가 버그를 기록하고, ContextForge가 git diff와 로그를 추가하며, PromptBoard가 시각적 구조와 제약 조건(constraints)을 추가합니다.

사용해 보기

PromptBoard는 무료 오픈 소스 AI 개발 도구 모음인 Machina의 일부입니다.

git clone https://github.com/machina-tools/machina.git

그 다음 브라우저에서 tools/promptboard/index.html을 여세요. 서버는 필요하지 않습니다.

→ GitHub | machina.chat