Claude Code에게 문서를 맡기면 보통 Markdown 파일이 나옵니다. 간단한 메모, 체크리스트, README에는 Markdown이 여전히 가장 편합니다. 하지만 스펙, 코드 리뷰, 디자인 비교처럼 사람이 훑고 판단해야 하는 결과물은 Markdown으로 표현하기 어렵습니다.
GeekNews에 소개된 글 ↗은 Claude Code의 출력 형식으로 Markdown 대신 HTML을 쓰자고 제안합니다. HTML에서는 색상, 다이어그램, 인터랙션, SVG, 표, 이미지, 캔버스를 쓸 수 있습니다. 글쓴이는 그 결과 사람이 결과물을 실제로 읽고 검토할 가능성이 높아진다고 주장합니다.
Claude Code의 컨텍스트 관리 자체는 Claude Code Memory에서, 여러 에이전트 협업은 Claude Code Agent Teams에서 다뤘습니다. 이 글은 에이전트가 만든 결과물을 어떤 형식으로 사람에게 전달할 것인가를 다룹니다.
HTML은 문서보다 검토 화면에 가깝습니다
Markdown은 선형 문서에 맞습니다. 위에서 아래로 읽는 설명, 코드 블록, 목록, 간단한 표에는 충분합니다. 하지만 코드 구조, 디자인 후보, PR diff, 복잡한 계획처럼 시각적 배치가 필요한 정보는 Markdown에서 구조가 사라집니다.
HTML 파일은 작은 검토 화면 역할을 합니다. html-effectiveness 예시 페이지 ↗는 “문서를 대체하는 HTML 파일”을 작업 유형별로 보여줍니다. 유형은 Exploration & Planning, Code Review, Design, Prototyping, Reports, Custom Editors입니다.
flowchart TD
A[Claude Code가<br/>프로젝트 맥락 수집] --> B{결과물 목적}
B -->|읽고 기록| C[Markdown]
B -->|비교·탐색·검토| D[HTML Artifact]
D --> E[시각화]
D --> F[상호작용]
D --> G[공유 가능한 단일 파일]HTML은 CSS로 밀도와 색상을 조정하고, SVG로 흐름을 그리고, JavaScript로 탭·필터·슬라이더 같은 조작을 붙일 수 있습니다. 같은 정보가 읽어야 하는 문서에서 눌러보며 판단하는 화면으로 바뀝니다.
언제 HTML을 요청하면 좋은가
모든 결과물을 HTML로 만들 필요는 없습니다. 습관적으로 HTML을 요구하면 생성 시간이 늘고 diff도 읽기 어려워집니다. GeekNews 요약에서도 HTML은 Markdown보다 생성이 2~4배 더 오래 걸리고, 버전 관리가 어렵다는 한계를 함께 언급합니다.
HTML이 맞는 경우는 다음과 같습니다.
| 상황 | HTML이 유리한 이유 | 예시 요청 |
|---|---|---|
| 스펙·계획 탐색 | 여러 후보를 나란히 비교하기 좋음 | “세 가지 구현안을 카드 형태 HTML로 비교해줘” |
| 코드 리뷰 | diff, 주석, 심각도, 흐름도를 한 화면에 배치 가능 | “이 PR을 리뷰용 HTML 리포트로 만들어줘” |
| 디자인·프로토타입 | 실제 UI에 가까운 밀도와 인터랙션 표현 가능 | “온보딩 화면 6안을 반응형 HTML로 만들어줘” |
| 리서치·보고서 | 긴 내용을 접기/탭/타임라인으로 정리 가능 | “조사 결과를 임원 보고용 HTML로 요약해줘” |
| 일회용 편집기 | 사람이 조작한 결과를 JSON이나 prompt로 다시 내보낼 수 있음 | “이 설정을 편집하는 단일 HTML UI를 만들어줘” |
반대로 짧은 결정 기록, 팀 규칙, README, 커밋 전후 비교처럼 텍스트 자체가 원본이어야 하는 문서는 Markdown이 더 낫습니다.
실전 프롬프트 패턴
HTML artifact를 요청할 때는 디자인보다 사용 방식을 알려줍니다. Claude Code가 읽을 정보, 도울 판단, 마지막에 내보낼 형태를 적습니다.
현재 브랜치의 변경 내용을 읽고, 리뷰어가 5분 안에 이해할 수 있는 단일 HTML 리포트를 만들어줘.
포함할 것:
- 변경 파일 그룹화
- 핵심 diff 요약
- 위험도별 리뷰 코멘트
- 데이터 흐름 Mermaid 또는 SVG 다이어그램
- 마지막에 “리뷰 코멘트만 Markdown으로 복사” 버튼
출력:
- review-report.html 파일 하나
- 외부 의존성 없이 로컬 브라우저에서 열 수 있게 작성이 패턴은 Claude Code Auto Mode처럼 긴 작업을 자동화할 때도 쓸 수 있습니다. 에이전트가 많은 파일을 읽고 정리한 뒤, 사람은 HTML 결과물만 열어 핵심 판단을 하면 됩니다.
“copy as JSON”, “copy as Markdown”, “copy as prompt” 같은 내보내기 버튼도 요청합니다. 사람이 UI에서 정렬하거나 값을 조정한 뒤, 그 결과를 다시 Claude Code에 붙여넣어 다음 작업으로 이어갈 수 있습니다.
버전 관리와 보안은 조심해야 합니다
HTML에는 부작용도 있습니다. Markdown보다 노이즈가 많아 코드 리뷰 diff가 읽기 어려워집니다. 스타일·스크립트까지 들어가면 장기 보관 문서로 관리하기 어렵습니다.
보안도 확인합니다. Claude Code가 만든 HTML에는 프로젝트 파일, 외부 페이지, 이슈 트래커 내용이 섞일 수 있습니다. 외부 데이터를 포함한 HTML은 스크립트를 최소화하고, 가능하면 로컬에서만 엽니다. 민감한 정보가 들어가지 않았는지도 확인합니다.
실무에서는 다음 기준을 추천합니다.
- 임시 검토용이면
tmp/,.claude/artifacts/같은 무시되는 경로에 둡니다. - 공유용이면 민감한 경로, 토큰, 내부 URL이 없는지 먼저 검사합니다.
- 저장용이면 원본은 Markdown/JSON으로 남기고 HTML은 렌더링 결과로 취급합니다.
- 상호작용이 필요 없으면 JavaScript 없이 CSS와 SVG만 사용합니다.
마무리
기본 형식은 Markdown으로 둡니다. 빠르고, diff를 읽기 쉽고, 저장하기 편합니다. Claude Code가 만들 결과물이 검토·비교·조작을 위한 화면이라면 HTML을 요청합니다.
형식은 다음 기준으로 고릅니다.
- 기록이 목적이면 Markdown
- 판단이 목적이면 HTML
- 재사용 데이터가 목적이면 JSON
- 팀 공유가 목적이면 Markdown 원본 + HTML preview
사람이 결과를 빨리 이해할 수 있는 형식을 고르면, 모델을 더 오래 돌리지 않아도 Claude Code 작업이 빨라집니다.
참고 자료
- GeekNews: 클로드 코드 사용하기: HTML의 놀라운 효율성 ↗ — 원문 요약과 주요 활용 방식
- The unreasonable effectiveness of HTML — examples ↗ — HTML artifact 예시 모음
- Claude Code Memory — Claude Code 컨텍스트 관리
- Claude Code Agent Teams — 에이전트 협업 구조