AI 에이전트가 짧은 답변을 만들 때는 마크다운이면 충분합니다. 하지만 에이전트가 코드베이스를 읽고, PR을 분석하고, 긴 계획을 세우고, 리서치 결과를 정리하기 시작하면 문제가 달라집니다. 출력이 길어질수록 사람이 핵심을 찾고, 비교하고, 검증하는 비용이 커집니다.
HTML 아티팩트는 이 문제를 줄이기 위한 작업 산출물입니다. 여기서 아티팩트는 에이전트가 만든 결과를 별도 파일이나 화면으로 남긴 문서에 가깝습니다. HTML은 표, CSS, SVG, 스크립트, 이미지, 캔버스 등을 담을 수 있어 마크다운보다 더 다양한 정보 구조를 표현할 수 있습니다.1
핵심은 “더 예쁘게 보여주기”가 아닙니다. 긴 에이전트 작업을 사람이 더 빨리 이해하고 검증할 수 있게 만드는 것입니다.
긴 출력의 병목은 작성이 아니라 검증이다
에이전트가 긴 보고서를 잘 쓰는 것만으로는 충분하지 않습니다. 실제 업무에서는 사람이 그 결과가 맞는지 확인해야 합니다. 코드 리뷰라면 어떤 diff가 위험한지 봐야 하고, 계획서라면 빠진 요구사항이 없는지 확인해야 하며, 리서치라면 근거와 결론의 연결을 따라가야 합니다.
HTML은 이런 검증 과정을 구조화할 수 있습니다. 예를 들어 코드 리뷰 문서는 실제 diff, 인라인 주석, 심각도별 색상, 흐름도, 모듈 지도를 한 화면에 함께 표시할 수 있습니다.1 텍스트 설명만 나열하는 것보다 변경 지점, 영향 범위, 위험도를 함께 보는 편이 훨씬 빠릅니다.
계획 검토에서도 마찬가지입니다. 여러 HTML 계획 파일을 만든 뒤 구현 세션에 넘기면 구현 에이전트가 더 넓은 맥락을 사용할 수 있고, 검증 에이전트도 같은 파일을 읽어 요구사항을 더 잘 파악할 수 있습니다.1 즉 HTML 아티팩트는 사람만을 위한 보고서가 아니라, 다음 에이전트 작업으로 맥락을 전달하는 매개체가 될 수 있습니다.
HTML은 보고서를 탐색 가능한 작업대로 바꾼다
마크다운 문서는 위에서 아래로 읽는 데 적합합니다. 반면 HTML은 긴 결과물을 탐색 가능한 작은 UI로 만들 수 있습니다.
긴 스펙이나 계획서에는 탭, 링크, 일러스트를 넣어 섹션별로 이동하게 만들 수 있습니다.1 딥 리서치 결과처럼 정보량이 많은 작업에서는 이 차이가 큽니다. 요약, 근거, 쟁점, 미확인 사항을 한 문서 안에서 분리해 보여주면 독자는 처음부터 끝까지 읽지 않고도 필요한 부분으로 이동할 수 있습니다.
공유도 쉽습니다. HTML 파일은 브라우저에서 바로 열 수 있고, 마크다운 파일보다 별도 첨부나 렌더링 환경에 덜 의존합니다.1 팀 안에서 “이 파일을 열어 보면 된다”는 방식으로 전달하기 좋습니다.
여기에 인터랙션까지 넣을 수 있습니다. HTML 문서에는 슬라이더, 노브, 버튼 같은 조작 요소를 넣어 사용자가 옵션을 조정하게 할 수 있습니다.1 사용자가 조정한 결과를 다시 프롬프트나 JSON으로 복사해 Claude Code에 전달하는 왕복 작업도 가능합니다.1 이 경우 HTML 아티팩트는 완성된 문서라기보다, 사람과 에이전트가 같은 상태를 보며 조정하는 임시 작업대에 가깝습니다.
어디에 쓰면 효과가 큰가
HTML 아티팩트는 특히 다음과 같은 작업에 잘 맞습니다.
첫째, 코드 리뷰입니다. 단순한 리뷰 코멘트보다 diff, 파일 구조, 위험도, 흐름도를 함께 보여줄 때 판단이 쉬워집니다.1
둘째, 계획 수립과 검증입니다. 긴 구현 계획을 HTML로 정리해 두면 다음 세션이나 검증 에이전트가 맥락을 이어받기 쉽습니다.1
셋째, 로깅입니다. 에이전트가 어떤 단계를 거쳤고, 어떤 판단을 했으며, 어떤 결과를 냈는지 구조화해 남기면 나중에 추적하기 쉽습니다. 단순 로그보다 섹션, 표, 링크가 있는 HTML 문서가 긴 작업 흐름을 확인하는 데 유리합니다.
넷째, 딥 리서치입니다. 출처, 주장, 비교표, 쟁점, 후속 질문을 한 문서 안에서 나누어 보여줄 수 있기 때문입니다. 리서치 결과는 길어지기 쉬우므로, 읽는 순서를 강제하지 않고 탐색할 수 있게 만드는 것이 중요합니다.
시작은 간단하게, 남용은 피하자
HTML 아티팩트를 만들기 위해 복잡한 지시가 꼭 필요한 것은 아닙니다. “HTML 파일을 만들어라” 또는 “HTML artifact를 만들어라” 같은 간단한 프롬프트로도 시작할 수 있습니다.1 Claude Code는 파일 시스템, MCP 연동, 브라우저 컨텍스트, Git 이력에서 정보를 가져와 HTML 보고서를 만들 수 있습니다.1
다만 모든 답변을 HTML로 만들 필요는 없습니다. 짧은 설명, 간단한 코드 조각, 터미널 출력에는 마크다운이 더 낫습니다. 실제로 HTML 아티팩트 스킬도 짧은 대화나 코드 전용 출력에는 HTML을 쓰지 않도록 예외를 둡니다.2
판단 기준은 단순합니다. 비교, 탐색, 검토, 공유, 조정이 필요하면 HTML이 유리합니다. 빠르게 읽고 끝낼 내용이면 마크다운이면 충분합니다.
AI 에이전트가 길고 복잡한 일을 맡을수록 출력 형식은 생산성의 일부가 됩니다. 좋은 HTML 아티팩트는 에이전트를 더 똑똑하게 만드는 것이 아니라, 사람이 결과를 더 잘 이해하고 검증하게 만듭니다.
1Using Claude Code: The unreasonable effectiveness of HTML | Claude
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.