마크다운 말고 HTML로 써보세요 — Claude Code가 갑자기 똑똑해지는 이유

요즘 Claude Code나 Cursor 같은 AI 코딩 에이전트를 쓰시는 분들이라면 한 번쯤 이런 경험 있으실 겁니다. 분명히 프롬프트는 깔끔하게 마크다운으로 정리해서 줬는데, 결과물이 어딘가 산만하고 지시를 빠뜨립니다. 그런데 최근 개발자 커뮤니티에서 의외의 해결책이 돌고 있습니다. 마크다운 대신 HTML 태그를 쓰면 에이전트 성능이 눈에 띄게 좋아진다는 이야기인데요. 직관과는 정반대라 처음 들으면 갸우뚱하지만, 막상 써본 사람들의 반응이 심상치 않습니다.

“마크다운이 내 워크플로우를 망쳤다”

5월 9일에 올라온 DIY Smart Code 채널의 영상 “Markdown Killed My AI Workflow (HTML Fixed It)"은 며칠 만에 4,475회 조회와 166개의 좋아요를 받으며 빠르게 퍼졌습니다. 제목부터 도발적인데요. 핵심 주장은 이렇습니다. 마크다운은 사람이 읽기엔 편하지만, LLM 입장에서는 구조의 경계가 모호하다는 겁니다.

예를 들어 ## 작업 목록 아래에 항목 다섯 개를 적어두면, 마크다운에서는 이 섹션이 어디서 끝나는지 명확하지 않습니다. 다음 ## 헤딩이 나오기 전까지가 끝이라는 건 사람의 약속이지, 토큰 단위로 보는 모델 입장에서는 문맥적으로 흐릿한 영역이 됩니다. 반면 <task_list>...</task_list>처럼 닫는 태그가 있으면 시작과 끝이 명확하게 구분됩니다.

Anthropic이 사실상 답을 알려줬다

사실 이건 완전히 새로운 이야기는 아닙니다. Anthropic 공식 문서에서도 오래전부터 XML 스타일 태그 사용을 권장해왔습니다. Claude는 학습 과정에서 <example>, <instructions>, <context> 같은 태그에 특별히 반응하도록 훈련됐다는 게 공식 가이드라인의 설명입니다.

문제는 많은 개발자들이 이 권고를 일회성 프롬프트에만 적용하고, 정작 가장 자주 쓰는 CLAUDE.md 파일이나 시스템 지시문은 마크다운으로 작성한다는 점입니다. 5월 10일에 올라온 AI Evening News의 영상 “Stop Asking Claude Code for Markdown — HTML Makes AI Work Feel 10X Faster”도 같은 맥락에서 이 격차를 지적합니다. 가장 중요한 컨텍스트 파일이 정작 가장 비효율적인 형식으로 적혀 있다는 겁니다.

HTML이 잘 먹히는 진짜 이유

왜 HTML/XML 태그가 더 잘 작동할까요. 몇 가지 가설이 거론됩니다.

첫째, 경계의 명확성입니다. <rules>...</rules>로 감싸진 영역은 모델이 “여기까지가 규칙"이라고 단언할 수 있습니다. 마크다운 헤딩은 그게 안 됩니다.

둘째, 중첩 구조 표현이 가능합니다. 마크다운에서 “이 코드 예시는 이 규칙의 하위 항목"이라는 걸 표현하려면 들여쓰기와 헤딩 레벨로 어색하게 흉내내야 합니다. HTML은 그냥 태그를 중첩하면 끝입니다.

셋째, 의미론적 명명이 가능합니다. <must_do>, <never_do>, <example_good>, <example_bad> 같은 태그 이름 자체가 모델에게 추가 신호가 됩니다. 마크다운으로는 “절대 하지 말 것"이라고 한국어로 적어야 하고, 그 한국어 자체를 모델이 다시 해석해야 합니다.

그런데 정말 10배 빨라질까

여기서 한 가지 짚고 가야 할 부분이 있습니다. “10X faster"라는 표현은 마케팅적 과장에 가깝습니다. 실제로 첫 번째 영상의 부제목도 “Or doesn’t it?"이라고 의문부호를 달아뒀습니다. 모든 작업에서 HTML이 우월한 건 아니라는 뜻입니다.

같은 날 올라온 GilliLab IT의 영상 “The LLM Agent Loop Trap Most Developers Fall Into”는 좀 더 균형 잡힌 시각을 제시합니다. 형식의 문제도 있지만, 더 큰 문제는 에이전트가 무한 루프에 빠지는 구조적 함정이라는 지적입니다. HTML로 바꾼다고 모든 문제가 풀리지는 않습니다.

실용적으로 보자면 이런 구분이 도움이 됩니다. 짧고 단순한 작업은 마크다운으로 충분합니다. 하지만 여러 단계의 규칙, 예시, 금지사항이 섞여 있는 복잡한 시스템 프롬프트나 에이전트 지시문은 HTML 태그로 구조화할 때 효과가 큽니다.

지금 당장 해볼 만한 것

당장 시도해볼 수 있는 가장 간단한 변화는 CLAUDE.md 파일의 핵심 규칙 부분을 태그로 감싸보는 겁니다. 예를 들어 “항상 테스트를 먼저 작성하라” 같은 지시는 그냥 평문으로 두기보다 <critical_rules>...</critical_rules> 안에 넣어두는 식입니다. 코드 예시는 <good_example>과 <bad_example>로 나누면 모델이 패턴을 더 정확히 따라옵니다.

흥미로운 건 이 트렌드가 프롬프트 엔지니어링의 회귀처럼 보인다는 점입니다. 한때 우리는 마크다운이라는 사람 친화적 형식으로 LLM과 대화하는 게 자연스럽다고 믿었습니다. 그런데 에이전트 시대로 넘어오면서 다시 기계 친화적이고 구조적인 형식으로 돌아가고 있습니다. AI가 똑똑해질수록 우리가 더 정확하게 말해야 한다는 역설이랄까요.

여러분의 CLAUDE.md나 시스템 프롬프트는 지금 어떤 형식으로 되어 있나요. 한 번쯤 핵심 섹션만이라도 HTML 태그로 바꿔보고 결과물의 질이 달라지는지 비교해볼 만한 실험입니다. 의외로 가장 큰 성능 향상이, 모델 업그레이드가 아니라 형식 변경에서 올지도 모릅니다.