Claude Code의 긴 결과를 비개발자에게 보여줄 때는 터미널을 캡처하지 마세요. 완전한 단일 HTML 파일로 만들게 한 뒤 로컬에서 검토하고 HTML2WEB에 올리면, 상대는 링크 하나로 같은 리포트를 볼 수 있습니다.

Claude Code 결과에 HTML이 잘 맞는 이유

Anthropic의 Using Claude Code: The unreasonable effectiveness of HTML은 긴 Markdown보다 HTML이 색상, 다이어그램, 시각화와 읽기 경험을 풍부하게 만들 수 있다는 실제 사용 사례를 소개합니다.

모든 결과를 HTML로 받아야 한다는 뜻은 아닙니다. 다음처럼 “사람이 읽고 판단하는 것”이 목적일 때 특히 유용합니다.

  • 코드 감사와 보안 점검 결과
  • 시장·경쟁 분석
  • 프로젝트 계획과 마일스톤
  • 성능 비교와 벤치마크 리포트
  • PM·디자이너·고객용 UI 목업

PR 설명이나 계속 편집할 기술 문서라면 Markdown이 더 낫습니다. 읽는 경험과 시각적 비교가 핵심일 때 HTML을 선택합니다.

바로 공유하는 3단계

1. 누가 어떤 결정을 내릴지 먼저 정합니다

“예쁜 HTML을 만들어줘”보다 독자와 결정을 먼저 알려주는 편이 결과가 좋습니다.

예를 들어 코드 감사라면 첫 화면에 다음 내용을 배치합니다.

  1. 감사 범위와 제외 범위
  2. 발견 사항의 심각도 분포
  3. 지금 해야 할 일 세 가지
  4. 각 주장에 대한 파일경로:줄번호
  5. 확인하지 못한 가정과 제한

시각적 완성도가 사실 검증을 대신하지는 않습니다. 잘 꾸며진 리포트일수록 근거가 없는 단정이 더 믿음직해 보일 수 있으므로 출처를 명시합니다.

2. 완전한 단일 HTML을 요청합니다

아래 프롬프트를 Claude Code에 복사하고 대괄호 부분만 바꾸세요.

[대상: 이 저장소의 src 디렉터리]에 대한 코드 감사 리포트를
audit-report.html이라는 단일 HTML 파일로 만들어줘.

[내용]
- 맨 위에 핵심 요약: 발견 사항 수, 심각도 분포, 당장 할 일 3개.
- 감사 범위와 방법, 보지 않은 영역을 명시할 것.
- 발견 사항마다 제목, 근거, 영향, 권고 조치를 적을 것.
- 코드 근거는 파일경로:줄번호, 외부 근거는 실제 링크로 표시할 것.
- 확인하지 못한 것은 "미확인", 근거 없는 계획은 "가정"으로 표시할 것.
- 전문 용어는 처음 나올 때 비개발자도 이해할 한 문장으로 풀어쓸 것.

[형식]
- <!doctype html>부터 </html>까지 완전한 문서 하나.
- CSS는 <style>, 꼭 필요한 작은 JavaScript는 <script>에 인라인.
- 외부 CSS·JavaScript·웹폰트·빌드 도구를 사용하지 말 것.
- header, nav, main, section, article, footer를 의미에 맞게 사용할 것.
- 표에는 caption과 th scope를 포함할 것.
- 360px 모바일 너비에서도 읽을 수 있게 만들 것.
- html lang="ko", 의미 있는 title, 키보드 포커스, 이미지 alt를 포함할 것.
- 시스템 폰트를 사용하고 전체 파일은 1MB 이하로 유지할 것.

[보안]
- API 키, 토큰, 비밀번호, 접속 문자열, 개인정보, 고객 데이터,
  내부 호스트명과 사내 URL을 넣지 말 것.
- 꼭 필요한 예시는 <redacted>로 가리고 가공했다고 표시할 것.
- 기존 소스 파일은 수정하지 말고 audit-report.html만 새로 만들 것.
- 완성 후 비밀정보 후보와 외부 자산 경로가 남았는지 다시 검사할 것.

프로젝트 계획 리포트라면 [내용]만 아래처럼 바꿉니다.

- 맨 위에 목표, 기간, 가장 큰 리스크 한 가지를 요약.
- 마일스톤 표: 이름, 기간, 산출물, 담당, 선행 조건.
- 의존 관계는 외부 차트 라이브러리 없이 CSS나 인라인 SVG로 표현.
- 리스크마다 가능성, 영향, 완화 방안, 조기 경보 신호를 표시.
- 열린 질문마다 누가 언제까지 결정해야 하는지 명시.

같은 형식을 자주 쓴다면 저장소의 CLAUDE.md에 산출물 규칙을 넣을 수 있습니다. 설정과 권한은 Claude Code 공식 문서를 기준으로 확인하세요.

3. 로컬에서 확인한 뒤 임시 링크로 발행합니다

macOS에서는 생성된 파일을 이렇게 엽니다.

open audit-report.html

fetch()나 모듈 스크립트를 사용했다면 file:// 환경에서 동작이 달라질 수 있습니다. 그때만 로컬 서버로 확인하고 끝나면 반드시 종료합니다.

python3 -m http.server 8000
# http://localhost:8000/audit-report.html 확인 후 Ctrl+C

다음 명령은 빠른 후보 검색일 뿐, 사람의 검토를 대신하지 않습니다.

ls -lh audit-report.html
grep -nEi 'api[_-]?key|secret|token|password|bearer|-----BEGIN' audit-report.html
grep -nEo '(src|href)="[^"]+"' audit-report.html

브라우저에서 다음까지 확인합니다.

  • 개발자 도구 콘솔에 오류가 없는가?
  • 폭 360px에서 본문과 표를 읽을 수 있는가?
  • 모든 외부 링크가 실제 근거로 연결되는가?
  • 로컬 경로와 비밀정보가 남아 있지 않은가?
  • 시크릿 창에서도 같은 화면이 보이는가?

파일이 준비됐다면 HTML2WEB의 HTML-to-URL 도구에 업로드하거나 코드를 붙여넣습니다. 로그인 없는 무료 경로는 1MB까지 지원하며 만료는 30분·1시간·24시간 중에서 선택합니다. 기본은 1시간이고 공유 결과물은 기본 noindex입니다.

공유 뒤 깨지는 원인

로컬 상대 경로

./assets/chart.png는 작성자의 컴퓨터에만 있습니다. HTML2WEB은 단일 파일을 게시하므로 옆 폴더의 이미지와 CSS가 따라가지 않습니다. 공개 HTTPS URL, 작은 인라인 SVG 또는 HTML 안에 포함된 스타일을 사용합니다.

CDN과 웹폰트

Chart.js, Tailwind CDN, Google Fonts가 회사 네트워크에서 차단되면 리포트가 다르게 보일 수 있습니다. 첫 검토본은 외부 의존성 없이 자립하게 만드는 편이 견고합니다.

Base64 이미지로 인한 용량 초과

스크린샷 여러 장을 data URL로 넣으면 1MB를 빠르게 넘을 수 있습니다. 비교에 꼭 필요한 이미지만 남기고, 단순한 차트는 표·CSS·인라인 SVG로 바꿉니다.

로컬 데이터를 읽는 스크립트

별도 JSON 파일을 fetch()하는 코드는 게시 뒤 파일을 찾지 못합니다. 검토용 데이터는 민감정보를 제거한 뒤 HTML 내부에 넣습니다.

Markdown이 더 나은 경우

  • PR, 이슈, 위키 본문으로 바로 옮길 때
  • 줄 단위 diff와 버전 관리가 필요할 때
  • 상대가 내용을 복사해 계속 편집할 때
  • 내용이 짧고 텍스트와 목록만 있을 때

간단한 기준은 읽고 판단할 결과는 HTML, 편집하고 추적할 원본은 Markdown입니다. 두 형식의 선택 기준은 AI 결과물은 Markdown과 HTML 중 무엇으로 받아야 할까?에서 더 자세히 비교합니다.

임시 링크와 정식 배포의 경계

코드 감사 초안, 회의 자료, 목업처럼 오늘 의견을 받을 산출물에는 임시 링크가 잘 맞습니다. 고정 주소, 검색 노출, 사용자 입력, 지속적인 업데이트가 필요하면 정식 호스팅으로 옮깁니다.

비밀번호를 걸어도 API 키와 개인정보를 게시하면 안 됩니다. 공유 링크를 받은 사람은 내용을 저장하거나 전달할 수 있습니다. 비밀정보 제거가 첫 번째 방어선입니다.

자주 묻는 질문

Claude Code가 파일을 여러 개로 만들었습니다

“CSS와 JavaScript를 인라인한 완전한 단일 HTML 파일 하나로 합쳐줘”라고 다시 요청합니다. 프롬프트 첫 단계에서 조건을 넣는 편이 더 빠릅니다.

복잡한 차트는 어떻게 넣나요?

간단한 막대·도넛·타임라인은 CSS나 인라인 SVG로 충분합니다. 외부 데이터를 계속 불러오는 인터랙티브 대시보드라면 임시 공유보다 정식 배포가 더 맞습니다.

링크가 만료되면 원본도 없어지나요?

공유 링크만 접근할 수 없게 됩니다. 로컬의 audit-report.html은 별도로 보관해야 합니다.

Claude의 Artifact 공유와 무엇이 다른가요?

대화의 Artifact를 그대로 공유하려면 Claude의 내장 공유 기능이 편할 수 있습니다. 독립된 .html 파일을 여러 도구에서 만들고, 만료와 비밀번호를 선택해 임시 검토하려면 HTML2WEB 흐름이 맞습니다. Claude HTML 공유 가이드에서 두 흐름을 확인할 수 있습니다.