AI 에이전트 소통법: Claude Code가 작성한 마크다운 문서를 렌더링해야 하는 이유
마크다운(Markdown)의 한계를 넘어, 결과물을 HTML로 시각화해 AI와의 협업 및 소통 능률을 높이는 방법과 실효성을 다룹니다.
AI 에이전트 소통법: 마크다운 문서를 렌더링해야 하는 이유
AI 에이전트(AI agent)를 활용해 바이브 코딩(vibe coding)과 업무 자동화를 개선하고자 할 경우 여러 가지 시행착오를 겪게 됩니다. 제가 겪은 일들은 주로 문서 작성과 홈페이지 레이아웃 배치 문제였습니다. 수정에 수정을 거듭할수록 비율이 엉망이 되기 일쑤였습니다.
기능의 경우는 설명하는 것이 어떻게든 가능한 수준이었으나, 컴포넌트의 배치와 비율 조정 문제는 별개였습니다. 생소하고 어려운 용어는 원하는 요구를 전달하는 데 진입장벽이 되었습니다. 구조를 머릿속으로 떠올리는 것과 글로 뱉어내는 것에는 큰 차이가 있기 때문입니다.
최근 Anthropic Claude Code1 팀의 Thariq Shihipar가 마크다운(Markdown)2 문서를 HTML로 시각화하는 것이 좋지 않겠느냐는 제안을 했습니다.3 잠깐 동안 SNS에서 화제가 되었는데, 간혹 “마크다운을 HTML로 변환하는 것이 과연 효율적인가?”라는 주장도 나왔습니다.
마크다운 파일을 HTML로 변환해서 저장하는 것은 그 자체로는 비효율적일 수 있습니다. LLM4이 읽기에는 마크다운이 더 낫기 때문입니다. 하지만 Thariq Shihipar의 제안은 마크다운 파일 유지 여부와는 별개로, 사람의 작업과 검토를 위해 결과물을 시각화하는 것에 가깝다는 생각이 들었습니다.
AI와 인간, 인간과 인간의 소통 도구로
내 웹페이지와 스킬 문서를 읽고 HTML로 시각화해달라고 요구하면, 꽤 만족스러운 결과물을 받아볼 수 있습니다.
예를 들어 현재 웹페이지의 요소별 배치, 비율, gap(갭, 요소 사이 간격), margin(마진, 바깥 여백), padding(패딩, 안쪽 여백) 등을 상세하게 정리해달라고 요청하면, 용어에 익숙하지 않아도 시각적으로 확인 가능한 상태가 됩니다. 그렇게 되면 수정이 필요한 부분만 짚어서 LLM에게 다시 요구할 수 있습니다.
결국 마크다운 변환 및 HTML 시각화의 핵심은 마크다운을 대체하는 것이 아니라, 사람이 더 쉽게 보고 판단할 수 있는 중간 결과물을 만드는 데 있습니다. AI 에이전트가 만든 결과물을 사람이 검토하고, 다시 지시하고, 개선 방향을 잡기 위한 소통 도구로 활용하는 것입니다.
(1) Claude Code (클로드 코드) — Anthropic에서 배포한 터미널 기반 AI 코딩 에이전트로, 개발자의 로컬 환경에서 직접 코드를 읽고 쓰며 작업을 자동화합니다.
(2) 마크다운 (Markdown) — 텍스트에 간단한 기호를 더해 제목, 목록, 굵은 글씨 등의 서식을 지정할 수 있는 가벼운 마크업 언어입니다. LLM이 텍스트를 읽고 쓰기에 가장 최적화된 포맷입니다.
(3) Thariq Shihipar 트윗 — Thariq (@trq212) on X. 원문 링크 →
(4) LLM (거대 언어 모델) — 대규모 텍스트 데이터를 학습해 사람처럼 문장을 이해하고 생성할 수 있는 AI 모델입니다. (예: Claude, ChatGPT)