Claude Code를 활용한 HTML 리포트 워크플로우 구축: 비디자이너를 위한 구현 가이드

Claude Code가 출력하는 200행의 Markdown 리포트는 승인 여부조차 한눈에 파악하기 어렵습니다. 본 기사는 HTML/CSS를 작성할 수 없는 비디자이너가, claude.ai의 「Design」 기능을 통해 「확정 사항과 검토 경위를 색온도로 구분한」 HTML 리포트 템플릿을 만들고, 이를 Claude Code를 경유하여 편집 회의를 자동화하는 자체 제작 슬래시 커맨드 /editorial (Claude Code의 커스텀 커맨드. 기획·구성·SEO 전략을 대화로 확정하는 필자의 워크플로우)에 통합하기까지의 구현 절차를, 재현 가능한 5단계와 공개 중인 실례와 함께 해설합니다.

본 기사는 AI에게 HTML을 직접 생성하게 하는 「부당한 유효성」을 Markdown과 비교한 전작(이론편)의 구현·실증편입니다. 이론적 배경과 Markdown / HTML의 역할 분담은 전작에서 상세히 다루었습니다.

본 기사는 Claude Code로 멀티 에이전트 워크플로우(/editorial 등)를 운용하고 있으며, 전작에서 HTML 출력에 흥미를 느꼈으나 HTML/CSS는 작성할 수 없는 비디자이너를 대상으로 합니다.

왜 Markdown 리포트로는 한계가 있는가

결론부터 말하자면: Markdown은 「좁은 캔버스」이며, 내용이 길어질수록 인간이 소비하기 어려워집니다. AI 에이전트가 양산하는 리포트는 바로 이러한 「길어지는」 성질을 가지고 있습니다.

필자의 워크플로우에서는 /editorial (편집 회의), /analytics, /review가 각각 기획서, GA 요약, 리뷰 결론을 모두 Markdown으로 출력합니다. 200행의 Markdown 리포트를 마주했을 때, 「결국 이 기획은 승인된 것인가」, 「어느 섹션의 볼륨이 무거운가」를 스크롤을 내려도 머릿속에 들어오지 않습니다. 승인 상태도 볼륨감도 텍스트의 행렬 속에 파묻혀 버립니다. 이것이 소비 효율(Consumability)의 결여입니다. Markdown이 취약한 요소들——공간 레이아웃, 신호등 같은 상태 표현, 볼륨을 면적으로 나타내는 바(bar)——를 텍스트라는 1차원으로 대용하고 있기 때문에 발생합니다.

Anthropic의 Claude Code 팀 엔지니어인 Thariq Shihipar 씨는, Claude Code가 「Markdown의 벽」 대신 20개의 자기 완결형 .html 파일을 만들게 한 사례를 공개하며 다음과 같이 말했습니다.

Twenty self-contained .html files an agent produced instead of a wall of markdown. Each one trades a document you'd skim for one you'd actually read.

(Markdown의 벽 대신 에이전트가 생성한 20개의 자기 완결형 .html 파일. 그 각각은 대충 훑어보는 문서 대신 실제로 읽게 되는 문서로 교체해 준다.)

같은 시기, Andrej Karpathy 씨 또한 「AI로의 입력은 음성이 편리하지만, 출력은 시각이 압도적으로 효율적이다」, 「시각은 뇌로 향하는 10차선 정보 슈퍼하이웨이다」라는 취지의 제안을 했습니다. 참고로 「10차선 고속도로」는 해당 인물의 비유를 2차 정보를 통해 요약한 것입니다 (출처: Quasa에 의한 Karpathy 해설, dsebastien.net 2026-05-12).

이론편을 공개한 후, 독자들로부터 가장 많이 돌아온 「다음 질문」은 이것이었습니다.

이론은 알겠다. 그런데 디자인을 못 하는 나는 어떻게 만드는가?

본 기사는 그 질문에 대해, 실제로 작동하고 있는 워크플로우로 답합니다.

비디자이너는 Claude에게 무엇을 요청했는가

결론부터 말하자면: 디자인을 「그리는」 것이 아니라, 정보 구조와 보여주는 방식의 의도를 언어화하여 전달하는 것만으로도 템플릿의 초안(기틀)을 생성할 수 있습니다. 나머지는 시행착오와 미세 조정을 통해 완성합니다. 비디자이너에게 필요한 것은 CSS 지식이 아니라 「무엇을 어떻게 보여주고 싶은가」에 대한 해상도입니다.

필자가 claude.ai의 Design 기능에 전달한 요구사항은 크게 3가지 방향으로 구성했습니다.

페르소나와 문맥 부여: 「당신은 편집 회의의 의사결정을 지원하는 정보 디자이너입니다」라고 역할을 부여하여, 누가·어떤 상황에서·무엇을 판단하기 위해 읽는지를 명시함
수치 기반의 구체적 지시: 「적당히 좋게」가 아니라, 확정 사항과 검토 경위의 차이를 「배경색·테두리 실선/점선·불투명도」라는 구체적인 시각적 속성으로 지정함
구성의 블록화: 리포트를 10개의 블록(A~J)으로 분할하고, 각 블록에 「무엇을 담을 것인가」와 「권장하는 시각 효과」를 표로 전달함

특히 세 번째가 핵심이었습니다. 방대한 지시를 한 번에 전달하면 AI의 출력 정밀도가 떨어집니다. 「10개 블록을 A~J로 구조화하고, 블록마다 시각 효과를 지정한다」는 분할 정복 (Divide and Conquer) 방식을 통해 각 블록의 완성도를 하나씩 높여갈 수 있습니다. 실제로 전달한 구성표는 다음과 같습니다.

ID	섹션	권장되는 시각 효과
A	요약 / 승인	대제목, 히어로 카드 (Hero Card), 필형 배지 (Pill-shaped Badge), 신호등형 상태 칩 (승인/조건부/재검토)
B	타겟 독자	페르소나 카드. 「과제」 부분만 경고색 액센트로 강조
C	구성안	아웃라인 트리 (Outline Tree, 들여쓰기+연결선), 볼륨 바 (Volume Bar, 추정 글자 수), 코드/도표 마커
D	SEO 전략	키워드 클라우드 (중요도별 크기), 검색창 스타일 UI, URL 바 스타일의 슬러그 (Slug) 표시
E	소구 포인트	3컬럼 가치 제안 (Value Proposition), Before→After 대비
F	라이브러리언 조사	동심원 형태의 관련도 맵, 차이 대비 테이블, 회수 포인트 인용 카드
G	GA 데이터 분석 (선택 사항)	KPI 스코어카드, 일간 꺾은선 그래프, 유입 도넛 차트, 키워드 히트맵
H	연재 판단	판정 배너 (체크리스트 방식의 판단 기준), 마일스톤 형식의 로드맵
I	의사결정 프로세스	세로형 스테퍼 (Stepper, 채택안=강조, 기각안=연한 색상으로 투명성 확보)
J	결과물 / 다음 액션	링크 버튼 그룹, `/draft #N` CTA 박스

이 표 자체가 「비디자이너가 claude.ai의 Design 기능에 전달한 사양서」입니다. 「동심원 형태의 관련도 맵을 SVG로」「신호등 비유를 사용하여 상태를 최상단에 고정해줘」와 같이 의도만을 언어화하면, 구현(CSS의 border-radius, SVG의 좌표 계산, @media print)은 claude.ai의 Design 기능이 담당합니다. 디자인 기술이 아니라 정보를 구조로 파악하는 능력이 결과물의 질을 결정한다—이것이 디자인 민주화의 실체입니다.

HTML 리포트를 「색온도」로 설계하기—확정 사항과 검토 경위의 분리

결론부터 말하자면: 이 템플릿의 핵심은 「색온도에 의한 정보의 분리」입니다. 확정 사항은 진한 색상과 실선, 검토 경위는 연한 색상과 점선, GA 데이터는 별도의 레이어로 구성합니다. 독자는 색온도만으로 「결정된 것」, 「생각한 경위」, 「데이터 근거」를 즉시 구분할 수 있습니다. 참고로 본 기사에서 말하는 「색온도」란 배경색의 농담, 테두리의 실선/점선, 불투명도를 통칭한 시각적 온도 차이의 비유입니다.

편집 회의 리포트에는 두 종류의 정보가 혼재합니다. 하나는 「제목은 A안으로 확정」과 같은 결론입니다. 다른 하나는 「당초 안은 B였으나, 자기 잠식 (Cannibalization, 전작과 검색 키워드가 겹치는 현상) 리스크로 인해 기각함」과 같은 검토 경위입니다. Markdown에서는 이 두 가지가 동일한 굵기의 텍스트로 나열되기 때문에, 독자는 매번 「이것이 결정 사항인가, 아니면 도중에 사라진 안인가」를 문맥을 통해 판단해야 합니다.

그래서 Claude에게 이 구분을 CSS 디자인 토큰 (Design Token)으로 고정하도록 요청했습니다. 실제로 생성된 스타일 정의의 핵심 부분은 다음과 같습니다.

:root {
--bg-card: #ffffff; /* 확정 사항: 불투명한 흰색 카드 */
--bg-process: #faf8f4; /* 검토 경위: 연한 배경 */
...

승인 상태는 신호등 비유를 사용하여 최상단에 고정하고, 속성 하나만으로 색상이 바뀌도록 했습니다. 이를 통해 「현재 조건부 승인인지, 재검토 중인지」를 페이지를 열자마자 0.5초 만에 전달할 수 있습니다.

.status-chip[data-status="approved"] { --chip-fg: var(--ok); --chip-bg: var(--ok-bg); } /* 녹색: 승인 */
.status-chip[data-status="conditional"] { --chip-fg: var(--warn); --chip-bg: var(--warn-bg); } /* 호박색: 조건부 */
.status-chip[data-status="rejected"] { --chip-fg: var(--bad); --chip-bg: var(--bad-bg); } /* 적색: 재검토 */

그리고 의사결정 프로세스 블록에서는, 기각된 안을 굳이 지우지 않고 남겨두도록 지시했습니다. 채택된 안은 실선과 진한 색상으로, 기각된 안은 점선과 취소선으로 표현합니다.

.opt.chosen { border-style: solid; border-color: var(--ink); background: var(--bg-card); }
.opt.rejected { border-style: dashed; text-decoration: line-through; opacity: 0.7; } /* 투명성을 위해 삭제하지 않음 */

「기각안을 남기는 것」은 단순한 장식이 아닙니다. 왜 그 기획이 되었는지, 어떤 선택지를 버렸는지를 제3자(편집장·미래의 자신)가 추적할 수 있게 하여 의사결정의 투명성을 보장합니다. 확정 사항의 원본성과 검토 경위의 투명성을 색온도라는 하나의 축으로 양립시키는 것——이것이 비디자이너가 찾아낸 설계의 답이었습니다.

/editorial 워크플로우에 어떻게 통합했는가

결론부터 말씀드리면: 템플릿을 /editorial의 최종 출력 레이어(Phase 4.5)에 포함시켜, 편집 회의가 완료될 때 Issue / Markdown / HTML의 3가지 아웃풋이 동시에 생성되도록 했습니다. 전작에서 「통합안」으로 예고했던 구상을 여기서 실증합니다.

/editorial 완료 시 생성되는 세 가지 성과물은 각각 「다음에 누가 읽는가」에 따라 역할이 나뉩니다.

HTML을 생성하는 LLM(Large Language Model)에는 데이터를 올바르게 배치하기 위한 「분석 브리프 (Analysis Brief)」를 전달합니다. 이는 「어떤 데이터를 10개 블록 중 어디에, 어떻게 변환하여 배치할 것인가」를 명세화한 지시 세트입니다.

스크랩 분석: 테마·기술 스택·요점을 추출하여 구성 트리(블록 C)의 출발점으로 매핑
라이브러리언 조사: 기존 기사와의 관련성을 직접/강함/간접의 세 단계로 분류하여 동심원 맵(F)에 배치
GA 데이터 분석 (선택 사항): 실제 데이터가 있다면 KPI 스코어카드·히트맵(G)으로. 없다면 <section id="sec-g">를 통째로 삭제
대화형 제안: AskUserQuestion의 모든 단계를 유지하며, 채택/기각안을 구분하여 세로형 스테퍼(I)에 배치
편집장 승인: 최종 판정을 최상단의 신호등 칩(A)에 최우선으로 반영하고, 승인 인장(I)과 반드시 연동

구현상으로는 index.html / styles.css / script.js의 3개 파일 구성으로 하되, CDN이나 빌드 도구 등의 **외부 의존성을 전혀 갖지 않는 자기 완결형 (Self-contained)**으로 만들었습니다. 여기서 「자기 완결형」이란 단일 물리 파일이라는 의미가 아니라, 외부 의존성 없이 그대로 작동한다는 의미입니다. index.html을 더블 클릭하는 것만으로 작동하며, 로컬에서 즉시 프리뷰할 수 있고 배포도 용이합니다. 이 설계는 Claude Code 공식 문서가 「브라우저에서 열 수 있는 인터랙티브한 자기 완결형 HTML 파일을 생성하도록 시키는 것」을 베스트 프랙티스로 권장하는 방향과 일치합니다.

또한, 이 워크플로우는 /editorial(편집 회의)에 국한된 것이 아니라, GA4 월간 리포트·제안서·조사 요약 등 임의의 정기적인 Markdown 리포트에도 전용할 수 있습니다. /editorial을 12개 에이전트 체제로 운용하게 된 경위는 「1주일 만에 최강의 편집 팀을 만든 이야기」에서 상세히 다루고 있습니다.

참고로 /editorial

/editorial의 「다중 에이전트에 의한 협조」를 Agent Teams로 실행할 경우, Agent Teams는 실험적 기능으로 기본적으로 비활성화되어 있으며 (2026년 5월 기준), CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 활성화와 Claude Code v2.1.32 이후 버전이 필요합니다 (Orchestrate teams of Claude Code sessions). 본 템플릿 자체는 서브 에이전트 단독으로도, Agent Teams로도 생성할 수 있습니다.

비디자이너가 오늘부터 시작하는 5단계

결론부터 말씀드리면: 기존의 Markdown 출력 워크플로우를 HTML화 하는 데 필요한 것은 기획 → 템플릿 작성 → 통합 → 브리프 (Brief) 주입 → 지속적 개선의 5단계뿐입니다. 디자인 기술은 필요하지 않습니다.

Step 1: 기획 및 요구사항 정의

대상을 하나로 좁힙니다. 필자는 「편집 회의 (/editorial)의 결과물」을 선택했습니다. 다음으로 과제를 언어화합니다 —— "길고 긴 Markdown 속에서 승인 상태가 묻혀버린다", "볼륨감을 알 수 없다". 마지막으로 목표를 "확정 사항과 검토 경위를 색온도로 분리하여 한눈에 파악할 수 있는 대시보드"로 정의합니다. 여기까지는 단 한 글자의 CSS도 쓰지 않습니다.

Step 2: Claude를 이용한 템플릿 작성

전장에서 다룬 「10 블록 구성표」와 「색온도 수치 지정」을 claude.ai의 「Design」 기능에 전달하여 템플릿 초안을 생성하게 합니다. 이 부분이 이 워크플로우의 핵심이며, 디자인의 실제 작업은 모두 claude.ai의 Design 기능이 담당합니다. 요구사항 제시 → 프리뷰 확인 → 미세 조정의 루프를 몇 차례 반복하는 것이 요령입니다. AI에게 한 번 부탁해서 완성되는 것이 아닙니다. 시도 횟수와 인간의 최종 조정을 전제로 하십시오. 완성된 초안을 report_templates/editorial/ 하위에 가져오며, 유지보수성을 위해 HTML·CSS·JS는 독립된 파일로 나누되, CDN 등의 외부 의존성은 갖지 않습니다 (앞서 언급한 자기 완결형 방식).

Step 3: 워크플로우로의 통합

기존의 스킬/명령어 정의 (.claude/commands/editorial.md)에 결과물 생성의 필수 공정으로서 "HTML 리포트 작성 (Phase 4.5)"를 추가합니다. 출력 위치는 슬러그 (slug) 기반으로 일관되게 유지합니다 (editorial-reports/<slug>/). 이로써 "평소처럼 실행하면 HTML도 함께 따라오는" 상태가 됩니다.

Step 4: 분석 브리프 (Context) 주입

AI가 데이터를 올바르게 배치하기 위한 "사양서"를 작성합니다. 스크랩, 라이브러리언 조사, GA (Google Analytics) 데이터, 대화 로그를 템플릿의 A~J 중 어디에 둘지 구체화하고, 조건 분기 (GA가 없으면 G 블록 삭제, 단발성이라면 연재 UI 삭제)도 명시합니다. 전장에서 작성한 브리프가 그대로 템플릿이 됩니다.

Step 5: 적용 및 지속적 개선

평소처럼 /editorial <scrap_path>를 실행하고, 생성된 index.html을 각 디바이스의 실기기에서 확인합니다. 레이아웃 깨짐이나 모바일 미지원 문제가 발생할 수 있으므로, 생성물은 "초안"으로 간주하고 CSS나 브리프의 지시 사항을 미세 조정합니다. 마지막으로 생성된 리포트를 라이브러리 목록과 연동하여 리포지토리 전체의 가시성을 높이면 지적 자산이 됩니다.

실제로 이 워크플로우로 생성 및 공개하고 있는 리포트 사례를 2가지 들겠습니다. 두 사례 모두 200행이 넘는 검토 경위가 스크롤 없이도 "승인 상태·구성 볼륨·기각안"까지 한눈에 파악됩니다. 꼭 실물로 확인해 보시기 바랍니다.

사례 1: 본 블로그에서 가장 많이 읽히는 기사의 편집 회의 리포트

Anthropic의 5가지 패턴으로 Claude Code 에이전트 설계를 분류하는 글은 본 블로그에서 압도적으로 접속이 많은 코너스톤 (cornerstone) 기사입니다. 그 기획이 어떻게 결정되었는지 —— 페르소나·구성·SEO 전략·편집장의 승인 판단까지의 모든 프로세스가 이 HTML 리포트에 응축되어 있습니다.

사례 2: 지금 읽고 있는 "이 기사" 자체의 편집 회의 리포트

이 기사 또한 바로 이 워크플로우를 통해 기획되었습니다. 여러분이 지금 읽고 있는 기사가 어떤 대화를 거쳐, 어떤 안을 기각하며 탄생했는지—그 의사결정 프로세스가 그대로 HTML화 되어 있습니다. 기사와 편집 회의 리포트를 비교해 보면, '색온도에 의한 분리'가 실제 데이터상에서 어떻게 기능하는지 체감할 수 있습니다.

요약: Markdown과 HTML의 내구성 계층화

본 기사에서는 비디자이너가 claude.ai의 「Design」 기능에 '정보 구조와 보여주는 방식의 의도'만을 전달하여 템플릿을 만들고, 색온도를 통해 확정 사항과 검토 경위를 분리한 HTML 리포트를 Claude Code를 통해 /editorial의 Phase 4.5에 통합하는 과정을 실증했습니다.

좁은 캔버스 문제: Markdown은 길어질수록 소비되지 않는다 -
의도의 언어화: 10개 블록 구성표와 수치 지정으로 디자인 기술 없이도 품질을 끌어낸다 -
색온도 분리: 확정=진한 색·실선, 검토=연한 색·점선, GA=별도 레이어 -
3가지 출력물 통합: Issue / Markdown / HTML을 '다음에 누가 읽는가'에 따라 구분하여 사용한다

여기서 서두의 '장문 HTML 패러독스'를 회수하겠습니다. 본 기사는 Markdown으로 작성되었고 꽤 깁니다—하지만, 그래도 괜찮습니다. laiso 씨의 '내구성 계층화(Durability Stratification)' 프레임(출처: AI 시대의 리치 텍스트 형식. 이론적 배경은 전작 'AI에게 HTML을 직접 생성시키는 것은 왜 효과적인가'에서 해당 프레임을 Zenn 워크플로우에 적용하여 정리하고 있습니다)을 빌리자면 답은 명확합니다.

내구성	용도	포맷
6개월 이상	Zenn 기사·제품 문서 (흔들리지 않는 원본)	Markdown
몇 시간~며칠	편집 회의 의사결정 지원·사내 공유	HTML (자기 완결형)

역으로 말하면, HTML화는 공짜가 아닙니다. 템플릿 유지보수 비용, 생성 시의 토큰 증가, Git diff를 통한 리뷰나 전체 grep의 어려움과 같은 부채를 동반합니다. 빈번한 차이점(diff) 리뷰·전체 검색·원본성이 최우선인 결과물은 Markdown 상태로 유지해야 하며, HTML이 가치를 발휘하는 것은 '인간이 한눈에 의사결정하는' 국면에 한정됩니다.

Zenn 기사는 '영구 원본' 계층이므로 Markdown 상태가 정답입니다. 반면, 매번 업데이트되며 소비 효율이 요구되는 편집 회의 리포트는 HTML 계층에 둡니다. 'Markdown은 너무 길어서 읽히지 않는다'라는 본 기사의 주장에 대한 증거는 기사의 글자 수가 아니라, 방금 링크한 2개의 실제 HTML 사례가 방대한 검토 경위를 한눈에 소비 가능하게 만들고 있다는 사실 그 자체입니다. 두 방식은 대립하지 않습니다. 원본성은 Markdown이, 소비 효율은 HTML이 담당한다—이 역할 분담이야말로 결론입니다.

서두의 질문으로 돌아가겠습니다. 승인되었는지조차 한눈에 알 수 없었던 200줄의 Markdown 리포트는, 색온도와 신호등 칩을 얻어 열리는 순간 의사결정을 할 수 있는 대시보드로 변했습니다. HTML/CSS를 쓸 줄 모르더라도, '무엇을 어떻게 보여주고 싶은가'를 언어화할 수 있다면 그 변환은 오늘부터 시작할 수 있습니다.

끝까지 읽어주셔서 감사합니다. 본 기사가 여러분의 워크플로우에서 발생하는 '읽히지 않는 리포트 문제'를 해결하는 데 도움이 되기를 바랍니다.