huashu-design 딥다이브
— 채팅 한 줄로 받아보는 "납품 가능한" 디자인

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

먼저 Agent Skill (에이전트 스킬)이라는 개념부터 잡고 가야 합니다. 스킬은 한마디로 AI 에이전트에게 읽히는 업무 매뉴얼 폴더입니다. 폴더 안에 "이런 요청이 오면 이렇게 일해라"라고 적힌 마크다운 문서(SKILL.md), 깊이 들어갈 때 펼쳐 보는 참고 문서들(references/), 그리고 재사용 부품(assets/)과 도구 스크립트(scripts/)가 들어 있습니다. 에이전트는 작업을 시작할 때 이 매뉴얼을 읽고, 거기 적힌 절차·금지사항·품질 기준대로 움직입니다.

그래서 이 레포의 정체는 "디자인 툴 소프트웨어"가 아니라 잘 짜인 디자인 프로세스 그 자체를 글로 박제한 것입니다. 좋은 디자이너가 일하는 방식 — 요구사항을 캐묻고, 가정을 먼저 보여주고, 변형안 여러 개를 내놓고, 브랜드 자산을 확인하고, 납품 전 검수하는 — 그 절차를 에이전트가 강제로 따르게 만든 631줄의 지시문이 본체입니다. 산출물은 전부 HTML이고, 거기서 MP4·GIF·PPTX·PDF로 변환하는 스크립트가 따라붙습니다.

2왜 주목받는가

트렌딩 이유 · 경쟁 대비 장점.

출발 스토리부터 화제성이 있습니다. 제작자 화수는 Anthropic이 디자인 도구 "Claude Design"을 발표한 날 새벽 4시까지 써 봤는데, 며칠 뒤 깨달았답니다 — "제품이 나빠서가 아니라, 나는 GUI를 열기 싫은 사람이구나." 그래서 에이전트를 시켜 Claude Design 자체(커뮤니티에 유출된 시스템 프롬프트 포함)를 분석·증류해서, 터미널 안에서 돌아가는 스킬로 다시 빚어냈습니다. README에서 이를 "오픈소스 문화의 AI 시대 신형태인 2차 창작"이라고 당당히 밝히는 점도 흥미롭습니다.

2026년 4월 19일에 만들어진 레포가 두 달도 안 돼 별 16,000개를 넘긴 데에는 몇 가지 뚜렷한 이유가 있습니다. ① 5월 14일 라이선스를 "개인 무료·상업 유료"에서 MIT(완전 자유)로 전환하면서 진입 장벽이 사라졌고, ② Claude Code 전용이 아니라 agent-agnostic (에이전트 불문) — Cursor, Codex, Gemini CLI 등 어디서나 돌아가며, ③ 제작자가 전 플랫폼 팔로워 30만의 인플루언서라 확산이 빨랐습니다. 그리고 무엇보다 ④ README의 모든 데모 영상이 이 스킬 스스로 만든 것이라는 점이 강력한 증명이 됐습니다.

기술적으로 가장 차별화된 부분은 "AI가 만든 티 나는 디자인"과의 전쟁입니다. 스킬 곳곳에 그 흔한 보라색 그라데이션, 아이콘 도배, 둥근 모서리+왼쪽 색 띠 카드 같은 패턴을 명시적으로 금지하는 규칙이 박혀 있습니다.

또 하나의 신뢰 포인트: 제작자는 브랜드 자산 프로토콜을 넣기 전후로 에이전트 6개씩 돌리는 A/B 테스트를 했고, 규칙 도입 후 결과물 품질의 들쭉날쭉함(분산)이 5배 줄었다고 공개했습니다. 스킬을 감(感)이 아니라 측정으로 다듬는다는 거죠.

3기술 스택 전체 지도

"코드 없는 레포"의 스택은 어떻게 생겼나.

보통 레포라면 여기서 프론트엔드 프레임워크와 백엔드 서버를 나열하겠지만, huashu-design은 구조가 다릅니다. 본체는 마크다운 문서이고, 실행 코드는 전부 "산출물을 다른 포맷으로 바꿔주는 변환 도구"입니다. 층을 나눠 보면 이렇게 됩니다.

package.json을 열어 보면 의존성이 딱 4개뿐입니다 — playwright, pptxgenjs, pdf-lib, sharp. 나머지는 전부 문서와 미디어 에셋이라, 레포 용량의 대부분은 BGM mp3와 데모 파일이 차지합니다. "로직은 자연어로, 코드는 변환기만"이라는 분업이 스택 표에 그대로 드러나는 셈입니다.

4아키텍처 심화 분석

한 문장 요청이 완성된 디자인이 되기까지.

먼저 독수리 시점에서 전체 그림을 봅시다. 이 시스템의 "실행 엔진"은 에이전트(예: Claude Code) 자신이고, huashu-design은 그 위에 얹히는 절차서입니다. 요청이 들어오면 SKILL.md가 교통정리(라우팅)를 하고, 상황에 따라 두 갈래 길 중 하나로 보냅니다.

이제 흐름 한 줄기를 끝까지 따라가 봅시다. "AI 심리학 발표 PPT 만들어줘"라고 입력했다고 치면:

① SKILL.md의 원칙 #0이 먼저 발동합니다 — "AI 심리학"에 구체적 제품·버전 정보가 얽혀 있으면 기억으로 단정하지 말고 웹검색으로 사실부터 확인하라는 규칙입니다. ② 스타일 참조를 안 줬으므로 어드바이저 경로로 빠져, 요구사항을 200자 이상으로 되새김(리스테이트)하고 500자 이상의 디자인 명세서(spec)를 만듭니다. ③ 내용에 이미지가 필수인지 판단해 필요하면 scripts/fetch_images.py로 무료 이미지를 먼저 확보합니다 — "소재 다 모은 뒤 디자인 시작"이 철칙입니다. ④ 서브에이전트 3개가 같은 spec을 받아 서로를 못 보는 상태로 각자 시안을 만듭니다(닮은꼴 방지). ⑤ 사용자가 시안을 고르면 페이지마다 독립 HTML로 슬라이드를 만들고 deck_index.html 외형(키보드 넘김+3D 전체보기)에 끼웁니다. ⑥ 끝나면 자동으로 PDF를 뽑고, 원하면 html2pptx.js로 PPTX까지 변환합니다.

마지막으로 html2pptx.js(약 1,300줄, 이 레포에서 가장 큰 실행 코드)의 원리도 짚어 둘 만합니다. HTML을 이미지로 찍어 PPT에 붙이는 꼼수가 아니라, Playwright로 페이지를 연 뒤 요소 하나하나의 계산된 스타일(computedStyle)을 읽어 PowerPoint 객체로 번역합니다. 그래서 나온 PPTX는 텍스트 상자를 더블클릭해 글자를 고칠 수 있는 "진짜" 파워포인트 파일입니다.

5디렉토리 구조 해부

어떤 폴더가 무슨 일을 하나.

구조에서 눈여겨볼 점: SKILL.md는 얇게 유지하고 디테일은 references/로 밀어내는 Progressive Disclosure (점진적 공개) 패턴입니다. 에이전트의 컨텍스트 창(한 번에 읽을 수 있는 분량)은 유한한 자원이라, 매번 7,300줄을 다 읽히는 대신 목차만 항상 읽히고 본문은 작업 유형에 맞는 것만 펼치게 한 거죠. 스킬을 직접 만들 때 가장 먼저 배워갈 설계입니다.

6학습 포인트 (기술별)

이 레포에서 배울 만한 것 + 어디를 보면 되는지.

코드 한 조각만 감을 잡아 봅시다. 무료 이미지 수집기를 쓰는 명령인데, 따옴표 안 검색어만 바꾸면 그대로 재사용할 수 있습니다 (복사만 하면 OK):

# "커피"와 "라떼아트" 사진을 1600px 폭으로 2장씩 받아 assets/img에 저장
python3 scripts/fetch_images.py \
  --query "coffee beans" "latte art" \
  --out my-project/assets/img --count 2 --width 1600

이 한 줄 뒤에는 "장식용 가짜 이미지 말고, 그 이미지를 빼면 정보가 사라지는 진짜 소재만 쓰라"는 철학이 붙어 있습니다. 스크립트조차 디자인 원칙의 집행 도구인 셈입니다.

7시스템 요구사항

돌리려면 무엇이 필요한가.

중요한 건 GPU도 디자인 소프트웨어도 필요 없다는 점입니다. 비용은 에이전트가 쓰는 LLM API 토큰이 전부고, 무거운 작업(영상 인코딩)은 ffmpeg가 CPU로 처리합니다. 서브에이전트 3개를 병렬로 돌리는 어드바이저 모드에서는 토큰 소모가 3배가 되니, 데모 한두 번은 가볍게, 본격 사용은 비용을 보며 조절하는 게 좋습니다.

8직접 해볼 수 있는 실습 과제

난이도별로 손에 익히는 단계.

9관련 기술 심화 학습 로드맵

한 주씩 따라가는 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: alchaincyf/huashu-design
• 실전 데모 (앵무새 진화사 사이트): huasheng.ai/parrots
• 실전 데모 (13페이지 발표 deck): skill-huasheng.vercel.app
• 제작자 사이트: huasheng.ai
• 스킬 설치 생태계: skills.sh