마크다운 문서는 왜 읽히지 않나
Claude Code로 일하다 보면 기획 문서, 코드 분석, 리서치 요약이 전부 마크다운으로 쌓입니다. 내용은 충분한데 100줄을 넘어가면 기호와 들여쓰기만 가득한 화면이 되고, 앞부분만 훑고 넘기게 됩니다.
Anthropic의 Claude Code 엔지니어가 올해 5월 블로그에서 같은 고백을 했습니다. "HTML이 새로운 마크다운이다." 본인도 100줄 넘는 마크다운은 읽지 않아 결과물을 HTML로 받기 시작했다는 것입니다. 문서가 부족해서가 아니라, 만드는 속도가 읽는 속도를 추월한 것이 문제입니다.
HTML 변환 한 줄로 무엇이 달라지나
프롬프트는 한 줄이면 됩니다. "리서치 마크다운 파일을 HTML로 변환해 줘. 상단 탭으로 채널별로 정리하고, 내용은 주제별 카드 레이아웃으로." 같은 내용이 탭과 카드로 재배치되는 것만으로 스크롤 없이 한눈에 들어오고, 마크다운으로 읽을 때와 이해 속도가 확연히 달라집니다.
레이아웃, 차트, 표는 지정하면 지정한 대로 나옵니다. "HTML로 만들어 줘" 한 마디로 시작해 원하는 구조를 점점 구체화하면 됩니다.
Playground 플러그인은 무엇을 더해 주나
정적 HTML로 닿지 않는 마지막 단계가 인터랙션입니다. 버튼을 누르고 슬라이더를 움직여 확인하는 동적 화면은 단순 변환 요청만으로는 제대로 나오지 않습니다. Anthropic이 이를 Playground 플러그인으로 묶어 제공합니다. Claude Code에서 /plugin install playground@claude-plugins-official 한 줄이면 설치되고, 문제 유형별 템플릿이 내장되어 있습니다.
코드베이스 의존성을 시각화하면 모듈이 색으로 구분된 노드 맵으로 그려지고, 레이어별 프리셋 버튼으로 보고 싶은 부분만 집중해 볼 수 있습니다. 노드에 단 코멘트는 피드백 프롬프트로 변환되어, Claude Code에 붙여 넣으면 해당 모듈을 타깃으로 분석이 시작됩니다.
실행 흐름도 마찬가지입니다. 질문 하나가 답변이 되기까지 8단계 프로세스를 동적으로 보여 주고, 질문 프리셋을 누르면 해당 흐름이 강조됩니다. 텍스트 설명을 읽는 것보다 걸리는 시간은 짧고 이해도는 높습니다.
언제 HTML이고 언제 텍스트인가
전부 HTML로 받으면 토큰이 훨씬 더 듭니다. 기준은 단순합니다. 표, 다이어그램, 카드로 봐야 이해가 빠른 완성된 결과물이면 HTML, 초안이나 메모, 에이전트 간 데이터처럼 중간 산출물이면 텍스트로 토큰을 아낍니다.
토큰을 더 써도 남는 이유는 분명합니다. AI가 문서를 만드는 속도는 이미 사람이 이해하는 속도를 앞질렀습니다. 그 간극을 줄이는 것이 지금 시점의 생산성입니다. AI에게 일을 맡기는 능력이 아니라, AI 결과물을 빠르게 읽고 검증하는 능력 말입니다.