Claude Code나 Claude Artifacts로 사내용 자료(검토 자료, ADR, 회의록)를 만들면 텍스트는 깔끔하게 나온다.

하지만 스크린샷이나 그림을 한 장 넣는 순간 파탄 난다.

Notion의 HTML 임베드(HTML embed) 블록에 붙여넣으면, 이미지만 링크가 깨지기 때문이다.

이 기사에서는 그 원인과, data: URI(Base64 임베딩) + 플레이스홀더(Placeholder) 주입이라는 회피책을 다룬다.

마지막으로 이 절차를 자동으로 수행해 주는 Claude Code 스킬도 소개한다.

Claude Artifacts, 그리고 Notion의 HTML 임베드를 포함한 많은 샌드박스(Sandbox) 환경은

외부 호스트의 이미지 URL을 불러올 수 없다.

• CSP(Content Security Policy)로 인해 외부 이미지 및 CDN으로의 요청이 차단된다.
• 설령 불러올 수 있다 하더라도, 사내 이미지 저장소 URL은 언젠가 링크가 깨지게(rot) 된다.

즉 <img src="https://...">는 처음부터 선택지에 없다.

남은 유일한 수단은 이미지 자체를 파일에 임베딩하는 data: URI(Base64)다.

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...(수십만 자)..." alt="로그인 화면">

이렇게 하면 외부 의존성은 제로가 되며, 단일 HTML 파일로서 완전히 자기 완결적(Self-contained)이 된다.

하지만 Base64를 처음부터 <img에 직접 작성하면 다른 문제가 발생한다.

이미지 한 장에 수십만 자. 몇 장 넣으면 HTML은 수백 KB ~ 1MB 가까이 불어난다. 이 상태에서는:

• 에디터의 문자열 치환(Claude의 Edit 툴 등)은 거대한 Base64를 포함하는 행의 매칭이 불안정해진다.
• 파일 전체를 읽어오는 작업은 토큰을 대량으로 소비하여 사실상 불가능해진다.

즉 "이미지를 넣는 순간, 이후의 문장 및 레이아웃 편집이 지옥이 된다".

포인트는 편집의 무게와 이미지의 무게를 분리하는 것이다.

절차는 다음과 같다.

1. HTML 본체에는 플레이스홀더만 작성한다

src에 Base64를 직접 쓰지 않고, 고유한 문자열을 배치한다.

<img src="data:image/png;base64,{img_01_login}" alt="로그인 화면">

이렇게 하면 HTML은 수십 KB의 보기 좋은 크기를 유지하면서, 구조·레이아웃·문장을 먼저 완성할 수 있다.

2. 각 이미지를 Base64 텍스트로 변환해 둔다

base64 -i shots/01-login.png -o shots/01-login.png.b64

3. 마지막에 딱 한 번, 기계적 치환으로 실제 데이터를 주입한다

from pathlib import Path
html_path = Path("doc.html")
html = html_path.read_text()
...

텍스트 편집은 모두 "가벼운 플레이스홀더 버전"에 대해 수행하고, 실제 데이터 주입은 마지막 Python 치환 1회로 끝낸다. 이것이 핵심이다.

4. 주입 후에는 태그 밸런스를 기계적으로 체크한다

치환 후의 HTML은 육안 확인이 어려우므로, 여닫는 태그 수의 일치 여부만 기계적으로 확인해 둔다.

import re
html = open("doc.html").read()
for tag in ("div", "section", "table"):
...

이미지 문제를 해결하더라도 자료의 모습이 제각각이면 결국 읽히지 않는다.

정보가 많은 자료일수록 읽는 사람은 전부 읽지 않으므로, 색상을 제한하는 것이 효과적이다.

• 검은색 글자 × 흰색 배경을 베이스로, 노란색 마커는 딱 1색만 사용한다. 마커를 칠하는 곳은 "결론·숫자·기한"으로 한정한다 (한 단락당 1곳까지).
• 표가 길다면 표 ↔ 카드 전환, 행 클릭 시 상세 전개 등 훑어보기용 인터랙션(Interaction)을 넣는다.

이렇게 하면 훑어보는 것만으로도 의사결정에 필요한 정보를 얻을 수 있는 자료가 된다.

위의 "디자인 시스템 + Base64 주입"을 매번 수동으로 하는 것은 번거로우므로, Claude Code의 Agent Skill로서 공개했다 (MIT / OSS).

Claude Code에 다음과 같이 요청하기만 하면 된다:

• "이 툴 도입을 위한 검토 자료를 만들어줘"
• "이 결정을 ADR로 정리해줘"
• "회의록을 깔끔하게 정리해줘"

검토 자료·코드 해설·ADR·회의록의 4가지 템플릿과 위의 Base64 주입 절차가 포함되어 있다.

# 일본어판·영어판 모두
npx skills add rikuto125/team-doc-design
# 일본어판만
...

Claude Code의 공식 플러그인으로도 포함된다.

/plugin marketplace add rikuto125/team-doc-design
/plugin install team-doc-design@team-doc-design

data:

URI 자체는 성숙한 기술(mature technology)이지만, "플레이스홀더(placeholder)로 구조를 먼저 만든 뒤, 실제 데이터는 마지막에 주입한다"라는 분리 단계를 거치면 Claude/LLM과의 궁합이 단번에 좋아진다는 것이 개인적인 발견이었다.

똑같이 "Notion 이미지 링크 깨짐" 문제로 고생하고 있는 분들에게 도움이 되길 바란다.

Star / Issue / 개선 PR 환영합니다 🙏