Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 16. 22:13

코딩 에이전트에게 스크린샷 대신 JSON을 제공하는 이유

요약

코딩 에이전트에게 스크린샷 대신 구조화된 JSON 데이터를 제공함으로써 토큰 비용을 절감하고 컨텍스트 효율성을 높이는 방법을 설명합니다. SlimSnap을 통해 시각적 정보를 텍스트 기반의 구조적 데이터로 변환하여 에이전트의 추론 정확도를 향상시킵니다.

핵심 포인트

  • 스크린샷 대비 JSON 사용 시 토큰 소모량을 최대 85%까지 절감 가능
  • 토큰 절약은 비용 문제뿐만 아니라 컨텍스트 윈도우 유지에 필수적
  • 구조화된 데이터는 에이전트가 픽셀을 추론하는 과정을 생략하게 함
  • SlimSnap은 요소, 경계 상자, 색상, OCR 텍스트를 포함한 JSON 제공

Claude Code는 이미지를 읽을 수 있습니다. Cursor도 마찬가지입니다. ChatGPT도 할 수 있죠. 그럼에도 불구하고 제가 SlimSnap을 만든 이유는 다소 지루한 이유 때문입니다. 이미지는 해당 작업에 적합한 형태가 아닙니다.

지루한 버전으로 설명하겠습니다. 작업의 목적은 "에이전트에게 내 화면에 무엇이 있는지 보여주고, 에이전트가 행동하게 하는 것"입니다. 이 작업을 위해 코딩 세션에 Retina 스크린샷을 붙여넣는 것은, 사용자의 토큰 예산(token budget), 컨텍스트 윈도우(context window), 그리고 에이전트가 올바른 대상에 대해 행동하는 것이 얼마나 중요한지에 따라 비용이 많이 들거나 정보 손실이 발생하는 중간 어디쯤에 위치하게 됩니다.

토큰 계산 (The token math)

시각적 입력(vision input)으로 Claude에 붙여넣은 스크린샷은 크기가 조정(downscaled)되며 API의 이미지당 상한선에 따라 비용이 청구됩니다. Claude Code가 기본적으로 사용하는 모델인 Sonnet 및 Haiku의 경우 약 1,568 토큰이며, Opus 4.7 및 4.8에서는 최대 4,784 토큰에 달합니다. OpenAI의 GPT-4o에서 실행되는 Codex CLI에 붙여넣을 경우, 고해상도 모드의 일반적인 1440x900 스크린샷은 약 1,105 토큰을 소모합니다. Gemini 2.5 기반의 Gemini CLI에 붙여넣으면 동일한 이미지는 약 1,548 토큰이 됩니다. 반면, 동일한 화면을 SlimSnap JSON 문서로 변환하면 약 700 토큰이 소모됩니다. 이 JSON에는 요소(elements), 정규화된 경계 상자(normalized bounding boxes), 추출된 색상(extracted colors), 그리고 각 요소의 OCR 텍스트가 포함되어 있습니다.

턴당 Sonnet 또는 Gemini보다 약 55% 적게, Codex보다 37% 적게, Opus보다는 최대 85% 적은 토큰을 사용합니다. 그리고 에이전트가 행동할 수 있는 구조화된 의도(structured intent)를 가진 유일한 표현 방식입니다.

표현 방식턴당 토큰 수
Opus 4.7 / 4.8의 스크린샷 (최대 청구량)~4,784
...

단순한 호기심으로 던지는 일회성 질문(one-shot question)이라면 상관없을 것입니다. 하지만 제가 실제로 터미널 코딩 에이전트를 사용하는 방식, 즉 몇 번의 프롬프트마다 페이지 상태를 보여주는 긴 반복 세션(long iterative session)에서는 더 이상 단순한 호기심의 문제가 아닙니다. Sonnet에서 스크린샷을 20번 사용하면 아무 말도 하기 전에 약 31k 토큰의 시각 토큰을 소모합니다. Codex CLI에서의 20번은 약 22k입니다. Opus 4.7+에서는 약 96k에 달합니다. SlimSnap JSON을 20번 사용하는 것은 14k입니다. 200k 컨텍스트 윈도우에서 이것은 리팩터링(refactor)을 완료하느냐, 아니면 세션 중간에 컨텍스트가 압축되어 밀려나느냐의 차이입니다.

에이전트를 하루 종일 실행한다면 비용이 중요합니다. 하지만 까다로운 리팩터링 (refactor) 작업을 수행 중이라면 컨텍스트 (context)가 더 중요합니다.

구조가 픽셀을 이깁니다

토큰 계산법은 HN(Hacker News) 댓글에서 승리하는 부분입니다. 하지만 에이전트가 실제로 도움이 되는지 여부에 있어 진짜 중요한 부분은 구조 (structure)입니다.

스크린샷을 붙여넣으면, 에이전트는 픽셀을 보고 모든 것을 추론해야 합니다: 무엇이 버튼인지, 무엇이 텍스트인지, 색상은 무엇인지, 어떤 레이블이 어떤 입력창에 속하는지, 사용자가 어디를 가리키고 있는지 등을 말이죠. 에이전트는 매 턴마다 이 작업을 수행하는데, 왜냐하면 가공되지 않은 픽셀은 지속적인 추론 상태 (reasoning state)가 아니기 때문입니다. 6번의 프롬프트가 지난 후 후속 질문을 던지면, 에이전트는 다시 픽셀로 돌아갑니다. (에이전트가 읽는 대신 보는 이유: Claude는 스크린샷을 OCR 하는 것이 아니라 해석합니다.)

구조화된 JSON을 붙여넣으면, 에이전트는 사실을 읽습니다. 요소 e4는 버튼이며, 정규화된 bbox(bounding box)는 [0.34, 0.60, 0.32, 0.07]이고, 색상은 #3B82F6, OCR 텍스트는 "Sign up"입니다. 다음 턴에서 에이전트는 픽셀을 재해석하지 않고 e4를 참조합니다. 추론은 다음 턴에서도 사용될 동일한 기본 요소 (primitives)에 기반하게 됩니다.

{
  "schema_version": "1.0",
  "captured_at": "2026-05-19T18:17:46Z",
...

주석 (annotations) 또한 동일한 특성을 가집니다. PNG 파일 속의 빨간색 사각형은 그냥 빨간색 사각형일 뿐입니다. 하지만 SlimSnap JSON 속의 빨간색 사각형에는 intent 필드, 겹쳐진 요소를 가리키는 target_ref, 그리고 선택 사항인 콜아웃 (callout) 문자열이 있습니다. 에이전트는 제가 어떤 입력창을 가리키고 있는지 추측할 필요가 없습니다. 스키마 (schema)가 다음과 같이 말해주기 때문입니다: 이 화살표는 e4를 대상으로 하며, 의도(intent)는 highlight이고, 콜아웃은 "이것이 정렬이 어긋나 있습니다"입니다.

이미지를 붙여넣고 "정렬이 어긋난 입력창을 수정해줘"라고 말하면 에이전트는 어떤 입력창인지 추측해야 합니다. 반면 JSON을 붙여넣으면 에이전트는 즉시 행동합니다. 추측해야 할 불확실성이 이미 해소되었기 때문입니다.

슬래시 명령어 대신 스킬 (skill)을 만든 이유

캡처 내용이 구조화된 JSON(structured JSON)이 되면 나머지는 간단합니다. SlimSnap은 실행 시마다 또는 설정 변경 시마다 ~/.slimsnap/config.json에 아주 작은 설정 파일을 작성합니다. 여기에는 기본 저장 폴더와 파일 이름 패턴이 포함됩니다. 그 외에는 아무것도 없습니다.

{
  "schema_version": "1.0",
  "default_save_folder": "/Users/alex/Documents/SlimSnap",
...

Claude Code 스킬(무료, MIT 라이선스, github.com/bickov/slimsnap-skill의 별도 리포지토리)은 해당 설정을 읽고, 저장 폴더를 나열하며, 최신 JSON 파일을 불러와 에이전트의 작업 컨텍스트(working context)로 파싱합니다. 업로드 단계도 필요 없습니다. 기억해야 할 슬래시 명령어(/ command)도 없습니다. "여기 스크린샷이 있습니다"라고 말할 필요도 없습니다. 저는 전역 단축키를 누르고, 주석을 달고, 저장(Save)을 누른 뒤, Claude Code에 "이것 좀 고쳐줘"라고 입력하기만 하면 됩니다. 그러면 에이전트는 이미 구조화된 캡처 내용을 불러온 상태가 됩니다.

제가 CLI 도구나 Claude Code 플러그인 대신 스킬(skill)을 선택한 이유는 스킬이 자동으로 트리거(auto-trigger)되기 때문입니다. 사용자가 호출하는 것이 아니라, 프롬프트가 해당 스킬의 목적과 일치해 보일 때 에이전트가 호출합니다. "내 최신 SlimSnap 캡처에 무엇이 들어있지?"라는 질문이 이를 트리거합니다. "내 마지막 스크린샷에서 정렬이 어긋난 입력값을 고쳐줘"라는 요청도 마찬가지입니다. 스킬은 유용해지기 전까지는 보이지 않습니다.

Claude Code를 기반으로 무언가를 만드는 사람이라면 반드시 명확히 알아야 할 부분이 있습니다. 데스크톱 앱과 에이전트 사이의 약속(contract)은 하드코딩된 경로가 아니라 설정 파일(config file)이라는 점입니다. 스킬은 저장 폴더를 스스로 찾아냅니다. 캡처 파일을 이동하더라도 스킬은 이를 따라갑니다. 만약 여러분이 다른 소비자(CLI, VS Code 확장 프로그램, 다른 에이전트 등)를 만든다면, 동일한 설정을 읽어 그대로 작동하게 됩니다.

오픈 스키마(open schema)가 실제 제품입니다

SlimSnap은 Mac 앱이며 출시 시점에는 무료입니다. 앱보다 더 오래 살아남을 것은 바로 스키마(schema)입니다. 이는 github.com/bickov/slimsnap-schema에 별도의 MIT 리포지토리로 공개되어 있습니다. JSON Schema 2020-12 규격, 두 개의 예시, 그리고 모든 필드를 설명하는 README가 포함되어 있습니다.

이것이 중요한 이유: 1인 개발자가 만든 새로운 데스크톱 도구에 대해 가장 흔히 나오는 반응은 "당신이 사라지면 어떻게 되나요?"입니다. 만약 스키마(Schema)가 공개되어 있고, 이를 사용하는 스킬(Skill)을 누구나 포크(Fork)할 수 있다면, 그에 대한 답은 "당신의 캡처는 여전히 작동하고, 당신의 스킬도 여전히 작동합니다. 원한다면 다른 어노테이터(Annotator)를 만드세요"가 됩니다. 데이터가 앱에 종속되지 않는 것입니다.

이것이 SlimSnap을 오픈 소스 프로젝트로 만든다고 주장하는 것은 아닙니다. 데스크톱 앱은 폐쇄적입니다. 하지만 스키마와 스킬은 공개되어 있습니다. 이것이 제가 제공할 수 있는 가장 최소한의 범위이며, 사람들이 저를 영원히 신뢰하지 않더라도 이 워크플로우(Workflow)에 투자할 수 있게 만드는 방법입니다.

이것이 아닌 것

이것은 Claude Code의 대체제가 아닙니다. Claude Code는 여전히 이미지를 잘 읽습니다. 일회성 질문을 위해 스크린샷을 한 번 붙여넣는 것이라면 그렇게 하셔도 됩니다. JSON으로 변환해야 하는 이유는 워크플로우(Workflow) 때문입니다. 즉, 하루에 이 작업을 수없이 반복하고, 에이전트(Agent)가 저렴하고 정밀하기를 원하며, 캡처와 에이전트 사이의 깔끔한 핸드오프(Handoff)를 원할 때 유효합니다.

또한 백엔드 전용 작업을 위한 것도 아닙니다. Go 서비스를 리팩터링(Refactoring)하고 있다면 Claude Code에 화면을 보여줄 필요가 없습니다. SlimSnap은 시각적인 무언가를 계속 가리키고 에이전트가 그것에 대해 추론해야 하는 프론트엔드(Frontend), 디자인-투-코드(Design-to-code), 그리고 버그 재현(Bug-reproduction) 작업에서 가장 강력한 성능을 발휘합니다.

만약 그것이 당신의 루프(Loop)라면, 도구와 스킬, 그리고 스키마는 slimsnap.ai에서 확인할 수 있습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0