TL;DR
- 개념·코드를 그림 위주 단일 HTML 한 파일로 바꿔 준다.
- 강점은 그림 우선·독자 먼저·슬롭 차단·쉬운 말이다.
- OAuth 2.0로 직접 돌려 1라운드 PASS가 나왔다.
- 쓰는 동안 규칙이 스스로 늘어났다.
- 핵심은 “글이 아니라 검증된 그림”이다.
설명을 글이 아니라 그림으로 옮긴다
대부분의 AI는 설명을 시키면 ‘글’을 쏟아낸다. html-explainer-harness는 다르다. 설명을 ‘그림’으로 옮기는 것을 첫 번째 사고로 강제하는 Claude Code 스킬이다. 같은 개념이라도 단락을 쌓는 대신 “이걸 어떤 그림으로 보여 줄까”부터 묻는다.
두 단어를 먼저 풀어 둔다. 인포그래픽은 정보를 그림·도표로 정리해 한눈에 보이게 만든 자료다. 스킬은 Claude Code 같은 AI 코딩 도구에 특정 작업 절차를 미리 심어 둔 확장 묶음을 말한다. 그러니까 이 글은 “정보를 그림으로 옮기는 절차를 AI에 심어 둔 도구”에 대한 소개다.
AI에게 설명 문서를 맡기면 보통 무엇이 잘못되는가
강점을 말하기 전에, 이 스킬이 막으려는 실패부터 세워 보자. AI에게 설명 문서를 통째로 맡기면 결과물은 보통 네 갈래로 어긋난다.
첫째, 글의 벽이다. 텍스트 단락만 쌓여 한눈에 들어오지 않는다. 둘째, AI 슬롭이다. AI 슬롭은 어디에 붙여도 그럴듯하지만 영혼은 없는 기본 디자인을 가리킨다. 전형적인 모습이 세 가지 있다 — 보라색 그라데이션 배경, 이모지로 시작하는 불릿, 그리고 똑같이 생긴 카드 세 개다. 셋째, 어려운 전문어를 그대로 쏟는다. 풀어 주지 않으면 설명서가 또 다른 암호가 된다. 넷째, 독자 무시다. 누구한테 설명하는지 모른 채 일반론만 늘어놓는다.
뿌리는 하나로 모인다. AI에게 긴 작업을 통째로 맡기면 자기 글을 자기가 칭찬하는 편향, 중간에 빨리 끝내려는 조급함, 그리고 슬롭으로 미끄러지는 경향이 함께 나타난다. 그래서 “그림 우선·독자 먼저·슬롭 차단·쉬운 말”을 강제로 잡아 주는 장치가 필요하다.
무엇이 특별한가 — 여섯 가지 강점
이 글의 무게중심이다. 강점은 여섯 개이고, 각각이 앞서 본 실패 하나씩을 겨냥한다.
- 인포그래픽 우선. 작성 AI의 첫 생각은 “이 개념을 어떤 그림으로 옮길까”다. 글 단락은 마지막 수단으로 밀린다. 변환 후보는 마인드맵, 순서도, 차트, 웹툰·만화 서사, 도식, 시퀀스 다이어그램, 그리고 주제 고유 발명형 시각화까지 열려 있다. 왜 좋은가 — 그림은 글보다 한눈에 들어오기 때문이다. ‘글의 벽’을 정면으로 막는다.
- 독자 먼저 질의. HTML 한 줄을 쓰기 전에 셋을 묻는다. 누구(역할), 어느 업무 도메인(비유 소재), 어느 수준(입문·중급·전문가). 답에 맞춰 어휘·비유·깊이·시각화 복잡도가 전부 달라진다. 독자를 임의로 지어내는 것은 금지된다. 왜 좋은가 — ‘독자 무시’가 원천적으로 불가능해지기 때문이다.
- Anti-slop(슬롭 차단). 금지어 목록으로 거르지 않는다. 좋은 예와 나쁜 예를 나란히 보여 주는 few-shot 대비로 판정한다. few-shot은 AI에게 정답 예시 몇 개를 보여 주어 기준을 잡게 하는 방식이다. 핵심 질문은 하나다 — “주제 단어를 빼도 아무 주제에나 붙는 디자인인가.” 그렇다면 슬롭이다. 왜 좋은가 — ‘AI 슬롭’을 단어가 아니라 디자인의 보편성으로 잡아내기 때문이다.
- 쉬운 말 게이트. 어려운 전문어가 첫 등장 즉시 일상어로 풀리지 않으면 탈락이다. 기준은 금지어 스캔이 아니라 “이 독자라면 풀이가 필요한가”다. 왜 좋은가 — ‘전문어를 그대로 쏟는’ 실패를 통과 조건으로 막기 때문이다.
- 필수 인간 시각 체크포인트. 브라우저로 렌더하고, 스크린샷을 찍고, 사람이 레이아웃·대비·여백·느낌을 직접 확인해 승인해야 통과한다. 이 단계는 모델이 더 좋아져도 사라지지 않는다. 미감은 능력의 한계가 아니라 감각 채널의 부재이기 때문이다 — AI는 글을 읽을 수 있어도 ‘예쁨’을 볼 수는 없다. 왜 좋은가 — 모델이 못 보는 미감을 사람이 대신 봐 주기 때문이다.
- 단일 자족 HTML. 빌드 과정 없이 브라우저에서 바로 열리는 HTML 한 파일이다. HTML·CSS·SVG·Canvas·JS가 한 파일에 들어간다. 외부 CDN은 허용하지만 필수는 아니다. 왜 좋은가 — 외부 의존성이 0이라 파일 하나만 주고받으면 팀 누구나 바로 열기 때문이다.
여섯 강점은 흩어진 기능 목록이 아니다. 모두 하나의 중심 — “검증된 시각 설명” — 에서 뻗어 나온다. 아래 마인드맵이 그 관계를 보여 준다.
어떻게 품질을 보증하나
이 스킬의 진짜 차별점은 ‘예쁜 자동생성’이 아니다. 검증을 구조에 박아 넣은 설계다. 두 개의 게이트가 그 핵심이다 — 하나는 사람이 렌더 결과의 미감을 직접 승인해야만 통과하는 인간 시각 체크포인트(강점 ⑤), 다른 하나는 글을 만드는 AI와 채점하는 AI를 서로 다른 일꾼으로 분리해 ‘자기 글 자기 칭찬’을 막은 이중 분리다. 후자를 자세히 보자.
세 역할이 등장한다. 설계하는 Planner, 작성하는 Generator, 채점하는 Evaluator다. 셋은 각각 서로 다른 subagent다. subagent는 AI가 작업을 위해 따로 띄우는 독립 AI 일꾼을 말한다. 만드는 일꾼과 채점하는 일꾼이 다른 사람이니, 자기가 쓴 글을 자기가 칭찬하는 편향이 구조적으로 차단된다.
채점은 다섯 축짜리 루브릭으로 한다. 루브릭은 점수를 매기는 기준표다. 다섯 축과 가중치는 다음과 같다.
| 기준 | 측정 대상 | 가중 |
|---|---|---|
| C1 인포그래픽 풍부도 | 개념이 다양하고 적합한 그림으로 변환됐는가 | 2× |
| C2 시각 가독성 | 위계·스캔 경로·여백이 한눈에 잡히는가 | 2× |
| C3 슬롭 차단 | 주제 고유의 디자인인가, 어디에나 붙는 슬롭인가 | 2× |
| C4 학습 효과·쉬운 말 | 비유·예시가 이해를 쌓고 전문어를 풀었는가 | 1× |
| C5 정확성 | 사실·개념·코드가 정확하고 검증 가능한가 | 1× |
앞 세 축(C1·C2·C3)에 2배 가중을 둔 이유가 핵심이다. 압박이 없을 때 모델이 가장 약해지는 곳이 바로 거기이기 때문이다. 인포그래픽 풍부도·가독성·슬롭 차단은 강한 모델도 방심하면 흘러내린다.
이 모든 구조 — 역할 분리, 파일로만 소통, 루브릭 채점, 컨텍스트 불안 방지 — 를 묶는 틀을 하네스라고 부른다. 하네스는 AI가 긴 작업을 끝까지 잘 해내도록 잡아 주는 작업 틀이다. 원리의 출처는 Anthropic의 “Harness Design for Long-Running Application Development”(Prithvi Rajasekaran, 2026)다. 덧붙이면, 이 스킬 자체도 메타-하네스인 skill-wizard-harness로 만들어졌다 — 검증을 구조에 박는 설계 철학이 스킬을 만드는 단계에서부터 적용됐다는 한 줄 근거다.
실제로 써봤다 — OAuth 2.0 라이브 테스트
말로만 좋다고 하면 또 다른 슬롭이다. 실제로 한 번 돌려 봤다. 주제는 OAuth다. OAuth는 비밀번호를 직접 넘기지 않고도 다른 앱에 권한을 빌려주는 방식이다.
독자 삼각부터 정했다 — 신입 개발자 / 커머스(이커머스) 도메인 / 입문, 한국어다. 강점 ②(독자 먼저 질의)가 실제로 작동한 증거다. 산출물은 단일 HTML 약 80KB, 외부 의존성 0이었다. 강점 ⑥(단일 자족 HTML)이 그대로 실증됐다.
시각화 밀도는 11개 시각화에 9종이었다. 목표였던 7개 이상·5종 이상을 모두 넘겼고, 글만 있는 섹션은 0개였다. 강점 ①(인포그래픽 우선)이 수치로 증명된 셈이다. 본문에서는 이 밀도를 N=11, M=9로 표기한다.
주제 고유 모티프는 “발렛 주차 + 주문·송장 전표(傳票)”였다. 보라 그라데이션도, 이모지 불릿도 없었다. 헤더부터 제네릭 히어로가 아니라 네 역할을 색으로 나눈 전표 형태였다. 강점 ③(슬롭 차단)이 살아 있었다는 뜻이다. 인터랙티브 요소는 “장바구니 대행 결제 토큰 발권 워크스루”였다 — 인가 코드 그랜트를 한 클릭씩 진행하면 전표가 역할 사이를 이동하고, “앱이 본 내 비밀번호: 없음(0회)” 카운터가 돌고, 인가코드와 토큰을 혼동하면 거절 분기로 빠지고, 스코프 토글로 성공·거절이 갈리며, 앞단과 뒷단(서버끼리 통신)이 레인으로 구분됐다.
쉬운 말도 실증됐다. OAuth 용어 11개 전부가 첫 등장 시 커머스 비유로 풀렸다. 다섯 쌍만 옮기면 다음과 같다.
| OAuth 용어 | 커머스 비유 |
|---|---|
| 액세스 토큰 | 출입증 |
| 인가 코드 | 교환권 겸 번호표 |
| 인가 서버 | 발권 창구 |
| 리소스 서버 | 주문 창고 |
| 스코프 | 권한 체크리스트 |
작은 클라이맥스도 있었다. 작성 AI가 자가검증을 하던 중 실제 콘솔 버그를 발견했다. classList.add("")처럼 빈 문자열을 넣는 줄이 다음 에러를 던지고 있었다.
// 빈 문자열을 클래스로 추가하려던 죽은 줄
element.classList.add("");
// 콘솔 출력:
// SyntaxError: Failed to execute 'add' on 'DOMTokenList'죽은 줄을 삭제하고 전체 플로우를 다시 실행하니 콘솔 에러가 0이 됐다. 코드를 눈으로만 읽었다면 절대 못 잡았을 버그다. 강점 ⑤(인간 시각 체크포인트)가 떠받치는 “실제로 그려 보는 검증”의 가치가 여기서 드러난다 — 렌더하고 돌려 봐야 보이는 것이 있다.
채점 결과는 깔끔했다. Evaluator가 독립적으로 다시 렌더한 뒤 1라운드 만에 PASS를 줬다. 루브릭 점수는 C1=5, C2=4, C3=5, C4=5, C5=5였다. 여섯 개 probe 전부 통과, 정확성 제약 여덟 개도 전부 통과였다. 아래 막대 차트가 다섯 축 점수를 한눈에 보여 준다.
쓰면서 똑똑해진다 — 자기개선
한 번 더 흥미로운 일이 같은 실행 안에서 일어났다. 강점 ⑤(인간 시각 체크포인트)가 단발 검증으로 끝나지 않고 스킬을 영구히 개선시킨 사례다.
발단은 작은 지적이었다. 인간 시각 체크포인트에서 사용자가 디테일 하나를 짚었다 — “카드와 카드 사이를 잇는 연결 시각 컴포넌트가 카드에 가려져 안 보인다. 이런 디테일을 챙겨야 한다.” 특정 문서 하나를 고치라는 말이 아니라, 외부 예시로 품질 기준을 가르친 것이다.
이 지적은 스킬 세 파일에 영구 규칙으로 들어갔다.
infographic-patterns.md에 “Part C — 시각 디테일 규칙”이 추가됐다. 그리는 순서·z축 순서·간격·넘침 같은 규칙이다.generator-prompt.md의 안티패턴 목록에 “가려진 연결선”이 추가됐고, 렌더 후 연결선 가시성을 확인하는 절차가 붙었다.evaluator-prompt.md의 probe에 “가림 체크”가 추가됐다. 이제 가려진 연결선은 통과를 막는 항목이다.
결말이 좋다. 같은 라이브 런에서, 방금 개선된 Evaluator가 바로 그 체크를 수행해 OAuth 문서의 연결선이 깨끗함을 확인했다. 한 번 쓴 스킬이 사용 도중에 스스로 더 똑똑해진 살아 있는 사례다. 덧붙이면, 지금 이 글에 실린 그림들도 똑같은 규칙으로 연결선 가림을 확인한 뒤 게재했다.
언제 쓰면 좋은가
좋은 도구라도 아무 데나 쓰면 과하다. 정직하게 선을 그어 보자.
적합한 경우 — 강의 자료, 코드 리뷰 문서, 팀 공유용 개념 설명처럼 여러 섹션으로 이뤄지고 한눈에 들어와야 하는 문서다. 읽는 사람이 여럿이고, 한 번 잘 만들어 두면 두고두고 쓰는 자료일수록 값어치가 크다.
부적합한 경우 — 짧은 1회성 메모다. 시각화와 검증 절차가 오히려 과해져서 손이 더 든다. 한두 문장으로 끝날 일에 하네스를 돌릴 이유는 없다.
여섯 강점을 다시 모으면 이렇다 — 인포그래픽 우선, 독자 먼저, 슬롭 차단, 쉬운 말 게이트, 인간 시각 체크포인트, 단일 자족 HTML. html-explainer-harness는 ‘예쁜 척하는 자동 생성’이 아니라 ‘검증된 시각 설명’을 만드는 스킬이다. 글의 벽 대신 그림으로 옮기고, 사람이 직접 확인해 통과시킨다. 그래서 결과물은 또 하나의 암호가 아니라, 팀 누구나 파일 하나만 열어 한눈에 읽는 문서가 된다.
소스 코드
이 스킬은 오픈소스로 공개돼 있다. SKILL.md·Planner/Generator/Evaluator 프롬프트·루브릭·시각 패턴 규칙까지 전체 구성을 GitHub에서 직접 볼 수 있다 — github.com/greeun/html-explainer-harness. 이 글에 실린 다섯 인포그래픽도 같은 스킬의 시각 디테일 규칙을 따라 만들었다.