Claude Code에게 문서를 맡기면 보통 Markdown 파일이 나옵니다. 간단한 메모, 체크리스트, README에는 Markdown이 여전히 가장 편합니다. 그런데 스펙, 코드 리뷰, 디자인 비교처럼 사람이 훑고 판단해야 하는 결과물에서는 Markdown이 금방 답답해집니다.
GeekNews에 소개된 글 ↗은 이 지점을 잘 짚습니다. Claude Code에서 Markdown 대신 HTML을 출력 형식으로 쓰면 색상, 다이어그램, 인터랙션, SVG, 표, 이미지, 캔버스까지 활용할 수 있고, 결과적으로 사람이 실제로 읽고 검토할 가능성이 높아진다는 주장입니다.
Claude Code의 컨텍스트 관리 자체는 Claude Code Memory에서, 여러 에이전트 협업은 Claude Code Agent Teams에서 다뤘습니다. 이 글은 그 다음 단계로, 에이전트가 만든 결과물을 어떤 형식으로 사람에게 전달할 것인가에 집중합니다.
핵심은 “문서”가 아니라 “검토 화면”입니다
Markdown은 선형 문서에 강합니다. 위에서 아래로 읽는 설명, 코드 블록, 목록, 간단한 표에는 충분합니다. 하지만 코드 구조, 디자인 후보, PR diff, 복잡한 계획처럼 시각적 배치가 중요한 정보는 Markdown 안에서 금방 납작해집니다.
HTML은 문서라기보다 작은 검토 화면에 가깝습니다. html-effectiveness 예시 페이지 ↗도 Exploration & Planning, Code Review, Design, Prototyping, Reports, Custom Editors처럼 “문서를 대체하는 HTML 파일”을 작업 유형별로 보여줍니다.
flowchart LR
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 — 에이전트 협업 구조