AI 에이전트에게 픽셀을 설명하지 마세요 — 대신 주석을 다세요

만약 여러분이 Claude Code, Codex, Cursor 등 무엇이든 AI 에이전트와 페어 프로그래밍 (pair-program)을 해본 적이 있다면, 이런 순간을 경험했을 것입니다. UI 스크린샷을 찍어 채팅창에 붙여넣은 뒤 다음과 같이 타이핑하기 시작하는 순간 말이죠:

"오른쪽 상단에 있는 버튼 보이죠? 아니, 그거 말고, 정렬이 어긋난 아이콘 옆에 있는 다른 버튼요 — 모바일에서는 너비가 전체(full width)가 되도록 만들고, 하는 김에 아이콘도 좀 고쳐주세요."

여러분은 산문(prose)으로 픽셀을 설명하고 있습니다. 그러면 에이전트는, 참 기특하게도, 스크린샷에 있는 6개의 버튼 중 여러분이 실제로 의도한 것이 무엇인지 추측하기 위해 최선을 다합니다.

상황은 더 나빠질 수 있습니다. 많은 채팅 UI (chat UIs)는 클립보드에서 이미지만 유지하고, 함께 복사한 텍스트는 조용히 버려버립니다. 그래서 여러분이 정성스럽게 작성한 캡션(caption)은 전달조차 되지 않습니다. Cmd+C와 Cmd+V 사이에서 컨텍스트 (context)의 절반이 증발해 버리는 것입니다.

저는 매일 이 벽에 부딪혔습니다. 그래서 이를 해결하기 위한 도구를 만들었고, 오픈 소스 (open-sourced)로 공개했습니다. 이 포스트는 도구 자체보다는 그 밑바탕이 되는 아이디어에 관한 것이지만, 구체적인 설명을 위해 이 도구를 사용하겠습니다.

핵심 아이디어: 설명하지 말고 가리키세요

인간은 서로에게 픽셀을 설명하지 않습니다. 우리는 가리킵니다. "이거요." "바로 여기요." 우리는 손가락, 커서, 혹은 공중에 그린 원을 사용합니다.

따라서 이를 소리 내어 말해보면 해결책은 명확합니다: 이미지에 마커 (markers)로 주석을 달고, 에이전트가 참조할 수 있도록 각 마커에 안정적인 식별자 (identity)를 부여하는 것입니다. "오른쪽 상단의 버튼"이라고 말하는 대신 "마커 1"이라고 말하면, 이미지 상의 해당 버튼에는 실제로 번호가 매겨진 핀이 찍히게 됩니다.

하지만 시각적 마커만으로는 충분하지 않습니다. 왜냐하면 에이전트는 이미지를 평면적인 래스터 (raster) 이미지로 읽기 때문입니다. 에이전트는 "1"이라고 표시된 원이 가로 62%, 세로 48% 위치에 있다는 것을 알지 못합니다. 그래서 아이디어의 두 번째 절반은 다음과 같습니다: 주석이 달린 이미지와 함께, 모든 마커를 위치 및 설명과 매핑하는 구조화된 텍스트 블록 (structured text block)을 생성하고, 그 뒤에 실제 지시 사항을 덧붙이는 것입니다.

이것들을 하나로 합치면, 단 한 번의 붙여넣기로 에이전트에게 필요한 모든 것을 전달할 수 있습니다:

# 주석이 달린 캡처 — 1280×800 px

이미지가 첨부되었습니다. 번호가 매겨진 (원형) 배지들이 특정 요소들을 가리키고 있습니다.
...

이제 에이전트는 추측하지 않습니다. "마커 1은 대략 62% × 48% 위치에 있는 주요 CTA (Call to Action)입니다. 마커 2는 왼쪽 상단 근처에 정렬이 어긋난 아이콘입니다." 모호함은 사라지고, 당신의 지침은 모호한 공간 언어 대신 구체적인 앵커 (anchor)에 연결됩니다.

픽셀이 아닌 퍼센트(%)를 사용하는 이유

작지만 중요한 세부 사항이 있습니다. 위치는 절대적인 픽셀 좌표가 아니라, 왼쪽 상단을 원점(origin)으로 하는 **이미지의 퍼센트 (%)**로 표현됩니다. 에이전트는 가공되지 않은 픽셀 연산을 처리하는 것보다 레이아웃에 대해 상대적으로 추론하는 것("왼쪽 상단 근처", "가로 중앙")을 훨씬 더 안정적으로 수행하며, 퍼센트는 모델이 이미지를 보기 전에 채팅 UI가 적용하는 어떠한 다운스케일링 (downscaling) 작업에서도 유지됩니다. 만약 플랫폼이 당신의 1280px 캡처본을 768px로 크기를 조정하더라도, "62%"는 여전히 동일한 버튼을 가리킵니다. 하지만 "794px"는 그렇지 않습니다.

텍스트를 누락시키는 UI에 대비하는 법

이미지만 남기고 텍스트를 삭제하는 채팅 UI를 기억하시나요? 이에 대한 방어책도 있습니다. 바로 **범례 (legend)를 그림 안에 구워 넣는 것 (bake)**입니다. 마커 설명과 지침을 캡션 블록 (caption block)으로서 내보낸 이미지 위에 직접 렌더링하세요. 이는 의도적으로 클립보드 텍스트와 중복되도록 하는 것입니다. 플랫폼이 둘 다 유지한다면 좋고, 이미지만 유지하더라도 범례는 픽셀과 함께 그대로 남아있을 것입니다. 이중 안전장치(Belt and suspenders)를 마련하는 셈입니다.

실제로 사용할 수 있을 만큼 마찰 없는 환경 만들기

이러한 아이디어는 이를 호출하는 비용이 단순히 설명을 타이핑하는 비용보다 적을 때만 가치가 있습니다. 주석을 다는 데 30초 동안 씨름해야 한다면, 당신은 이를 건너뛸 것입니다. 따라서 워크플로우는 거의 즉각적이어야 합니다:

1. 영역을 캡처하기 위한 글로벌 단축키 (앱 전환이나 창 조절 불필요).
2. 클릭하여 마커를 배치 — 마커는 자동으로 번호가 매겨집니다.
3. 마커당 한 줄의 메모.
4. 복사. 끝. 에이전트에 붙여넣기.

이것이 기준점입니다: 하던 일을 중단하지 않고, 어디서든, 10초 이내에 캡처에서 클립보드까지 완료되어야 합니다. macOS에서 이는 메뉴 바 앱, 네이티브 해상도의 멀티 디스플레이 캡처를 위한 ScreenCaptureKit, 그리고 재할당 가능한 글로벌 단축키를 의미합니다. 단축키를 누르기 전까지는 당신의 작업 흐름을 방해하지 않습니다.

도구: Pinpoint

이 모든 것을 구현한 것이 바로 Pinpoint입니다. Pinpoint는 SwiftUI와 ScreenCaptureKit으로 제작된 네이티브 macOS 메뉴바 앱입니다. 단축키로 영역을 캡처하고, 번호가 매겨진 마커를 떨어뜨리고, 메모와 화살표를 추가한 뒤, 주석이 달린 이미지와 그 위에 구조화된 프롬프트를 복사할 수 있습니다. 모든 것은 로컬에 저장되며, 캡처물은 절대 Mac을 벗어나지 않습니다. 무료이며 MIT 라이선스이고, 공증 및 서명이 완료되었습니다.

• 소스 및 다운로드: https://github.com/croustibat/Pinpoint
• 랜딩 페이지: https://pinpoint-ashy.vercel.app/

저는 이 앱을 저 자신을 위해 만들었고 매일 사용하고 있습니다. 저에게 흥미로웠던 부분은 Swift 자체라기보다는 형식(format)에 대한 질문이었습니다. 즉, 에이전트가 후속 질문 없이 작동하기 위해 스크린샷 프롬프트는 실제로 무엇을 포함해야 하는가? 제가 현재 생각하는 답은 백분율 기반의 마커 맵과 내장된 범례입니다. 하지만 다른 분들이 이 문제를 어떻게 해결하고 계신지 정말 듣고 싶습니다.

도구를 사용하지 않더라도 얻을 수 있는 교훈

이 패턴은 macOS를 넘어, 이 앱을 넘어서 일반화됩니다. 에이전트에게 이미지를 전달할 때, 무엇을 가리키는지 추론하게 만들지 마세요. 안정적이고 이름이 지정된 앵커(anchor)와 그 위치에 대한 기계가 읽을 수 있는 맵을 제공하세요. 이 원칙은 사용자가 자체 워크플로우, 브라우저 확장 프로그램 또는 CLI에 구현하든 상관없이 유지됩니다. 즉, 설명하는 것보다 가리키는 것이 낫고, 단락으로 된 공간적 서술(spatial prose)보다는 구조화된 맵이 낫습니다.

AI 에이전트와 함께 UI 작업을 배포할 때는 다음번