🎨 Atelier

터미널 안의 아틀리에 — 아이디어 한 줄을 넣으면, 개발에 넘길 디자인 인계 패키지가 통째로 나온다.

An atelier in your terminal — one prompt forges an idea into a dev-ready design hand-off: PRD, clickable wireframes, design tokens, hi-fi screens.

Atelier(아틀리에)는 아이디어를 받아 PRD → 와이어프레임 → 디자인 시스템 → 하이파이 → 인계 패키지까지 짓는 작업장이다. 완성본은 인계 패키지(hand-off.md)로 묶여 다른 Claude Code 프로젝트(앱 레포)에 넘어간다.

여기서 만드는 건 "최종 앱 코드"가 아니라 개발에 넘길 기획·디자인 산출물이다.

⚙️ 설치 (30초)

npx @hb-kit/atelier init my-atelier   # 새 작업장 스캐폴드 (폴더명 생략 시 현재 폴더)
cd my-atelier
npm install && npx playwright install chromium
claude                                # Claude Code 세션에서 → /forge

필요한 건 Claude Code·Node.js 18+뿐. 빌드도 서버도 없고, 외부 계정·로그인 없이 전부 로컬에서 돈다. 설치부터 첫 handoff까지 단계별 가이드는 GETTING-STARTED.md.

⚡ 메인 무대 — /forge (무인)

아틀리에는 /forge 한 번으로 돈다. 시작에서 딱 한 번 질문(타깃·플랫폼·톤·MVP 경계)에 답하면, 그 뒤로 사람 게이트 없이 PRD부터 인계 패키지까지 자동으로 짓는다.

/forge ─시작 1회 질문─▶ PRD ─▶ 와이어 ─▶ 검증 ─▶ 디자인 시스템 ─▶ 하이파이 ─▶ 트렌드 감정 ─▶ handoff
                       └────────── 사람은 시작에서 한 번만. 나머지는 전부 자동 ──────────┘

/forge는 마법이 아니다 — 자동 게이트로 품질 바닥을 깔고, 사람 판단의 빈자리를 근거로 메운다:

| 그대로 유지 — 자동 게이트(품질 바닥) | 사람 판단의 빈자리를 메우는 장치 | |---|---| | lint-prd — PRD 11섹션 완결성 | 시작 1회 인테이크 — 추측하면 어긋나는 전제를 자세히 한 번에 | | Playwright 1·2층 — 내비·기능·죽은 컨트롤 0 | 가정 원장 — 대신 내린 결정을 PRD.md §11에 명시 | | a11y — 토큰 대비비 + 렌더 axe | 시장조사 에이전트(웹검색) → plan 질문을 근거화(plan-decisions.md) | | lint-handoff — 인계 패키지 완결성 | 디자인 트렌드 전문가(웹검색) → 미달 시 자동 리디자인 1회(design-critique.md) |

⚠️ 정직한 한계. 동작·접근성·트렌드 부합·인계 완결성은 자동 통과하지만, "옳은 제품인가·최종 미감" 은 사람 미검수다. /forge는 결과를 줄 때 이걸 명시한다 — 마음에 안 들면 가정만 고쳐 다시 /forge, 또는 아래 수동 모드로 갈아탄다(같은 폴더·STATUS 호환).

끝나면 projects/<name>/handoff/index.html(최종 화면 임베드)·hand-off.md(인계 프롬프트)가 생긴다 — 그게 결과물이다.

🔧 직접 몰고 싶다면 — /plan · /design

/forge가 내부에서 굴리는 두 공정을, 손으로 단계별로 몰 수도 있다. 단계마다 멈춰 직접 보고 합의하고 싶을 때 쓰는 — /forge의 수동 모드다(곁가지가 아니라 같은 공정의 다른 운전석).

| 스킬 | 언제 부르나 | 역할 | |---|---|---| | /plan | 전제를 직접 캐묻고 싶을 때 | 아이디어 → PRD.md (25년차 PM처럼 질문) | | /design | PRD가 있고 단계마다 직접 OK하고 싶을 때 | PRD.md → 디자인 산출물 + handoff |

• /plan — 바로 기획서를 쓰지 않는다. 모호한 말("깔끔하게")을 되묻고, "다 중요"를 거절하고, 각 기능을 사용자 문제 + 데이터 관점으로 검증한다. 7단계로 PRD를 굳힌다(문제정의→목표·지표→타깃→핵심기능·MVP→데이터 모델→흐름·화면→제약→체크리스트). 끝에 lint-prd green.
• /design — PRD를 받아 인테이크 → 클릭되고 상태가 변하는 와이어 → 3층 검증 → 디자인 시스템 → 하이파이 →(선택)리디자인→ 인터랙션 검증 → handoff. 단계마다 사용자 OK.

/forge와 수동 모드는 같은 산출물·STATUS·검증을 공유한다. /forge로 뽑은 1차 결과를 /design으로 이어 사람이 다듬을 수도, /plan으로 PRD만 손으로 굳힌 뒤 나머지를 /forge에 맡길 수도 있다. 무인은 일방통행이 아니다.

🧪 공통 토대 — 단계마다 자동으로 검증한다

/forge든 수동이든, 아래 검증은 코드로 박혀 매번 돈다(scripts/):

• 검증은 3층 — 내비게이션(자동)·화면이 책임지는 기능 완결성(자동, 죽은 컨트롤 0)·느낌과 "옳은 흐름인가"(사람). 자동 2층은 Playwright로 green까지 루프, 반복 로직은 scripts/lib/에 골격으로 박혀 매 프로젝트 재발명하지 않는다.
• a11y도 자동 — 토큰 대비비(값 차원) + 렌더 화면 axe(대비·역할·포커스).
• 경계마다 린트 게이트 — lint-prd+lint-prd-review(plan→design: 형식 + 독립 비평 확인) · lint-verify(하이파이: 독립 검증 확인) · lint-handoff(design→dev: self-contained 완결성).
• 와이어는 진짜 클릭된다 — 페이지끼리 <a href>로 잇고, 선택·토글·카운터 같은 상태도 실제로 변한다(인라인 JS 허용). 느낌만 하이파이 몫.
• 에이전트 동적 편성 — 생성량 많은 단계는 빌더를 병렬로 띄우고, 만들지 않은 독립 에이전트가 적대적으로 검증한다.

/forge에선 3층 중 사람 몫(느낌·옳은 흐름) 을 시작 1회 인테이크·가정 원장·전문가 에이전트가 대신한다. 수동 모드에선 사람이 직접 본다.

🗂️ 구조

Atelier는 단일 프로젝트가 아니라 여러 프로젝트를 담는 작업장이다.

atelier/                            # (레포. 로컬 폴더명은 달라도 무관)
├── CLAUDE.md                       # 작업장 공통 규칙 (형식·품질의 원본)
├── .claude/skills/
│   ├── forge/                      # ⚡ /forge  — 무인 오케스트레이터 (메인 무대)
│   ├── plan/                       #   /plan    — 기획 (→ PRD)         ← forge가 내부 구동 / 수동도 가능
│   └── design/                     #   /design  — 디자인 (PRD → handoff) ← forge가 내부 구동 / 수동도 가능
├── .claude/agents/                 # 서브에이전트 (시장조사·PRD 비평·화면 빌더·렌더러·독립 검증·트렌드 감정)
├── .claude/workflows/              # forge-plan.js · forge-design.js — 무인 구간 결정론적 오케스트레이션
├── scripts/                        # 검증 도구
│   ├── test-project.js             #   프로젝트별 Playwright 실행기(증빙 라우팅)
│   ├── shoot.js                    #   hi-fi 헤드리스 렌더 → PNG (검증·트렌드가 픽셀을 봄)
│   ├── lint-prd.js · lint-prd-review.js    # PRD 형식 + 독립 비평 게이트 (plan→design)
│   ├── lint-verify.js              #   하이파이 독립 검증 게이트
│   ├── pack-handoff.js · lint-handoff.js   # handoff self-contained 패키징 + 완결성 게이트 (design→dev)
│   └── lib/                        #   재사용 검증 골격(crawl·controls·selectors·a11y)
└── projects/                        # 프로젝트마다 폴더 하나 (서로 독립)
    └── my-first-app/
        ├── PRD.md                  # 기획 산출물 (= 디자인 입력)
        ├── plan-decisions.md       # (/forge) 시장조사가 plan 질문에 답한 근거·출처
        ├── prd-review.md           # PRD 독립 비평 (별도 에이전트의 8차원 판정)
        ├── STATUS.md               # 지금 어느 단계인지 (0 기획 ~ 7 handoff)
        ├── 00-flow.md              # 화면·플로우 합의본
        ├── wireframe/              # 클릭되는 lo-fi (*.html)
        ├── foundation/             # tokens.css + colors/typography
        ├── components/             # *.html
        ├── screens/                # 하이파이 (*.html)  ·  screens-<variant>/ = 리디자인 후보
        ├── design-verify.md        # 하이파이 독립 검증 (별도 에이전트의 render-check 판정)
        ├── design-critique.md      # (/forge) 트렌드 전문가 감정 점수·지적
        └── handoff/                # ★ 최종 인계 패키지 (hand-off.md + 비주얼 문서·매핑표·인벤토리)

• 프로젝트는 서로 독립. 토큰·산출물을 공유하지 않는다.
• STATUS.md가 프로젝트의 현재 위치. 0 기획 → … → 7 handoff를 한 줄로 추적한다. /forge든 수동이든 멈춘 단계부터 이어간다.

단일 출처: 이 README는 사람용 요약이다. 공정 절차의 원본은 .claude/skills/{forge,plan,design}/SKILL.md, 형식·품질 규칙의 원본은 CLAUDE.md. 규칙을 바꿀 땐 원본 한 곳만 고친다.

🚀 쓰는 법

처음이라면 GETTING-STARTED.md — 설치부터 첫 /forge, 검증, handoff까지 단계별 가이드.

작업장 폴더에서 Claude Code 세션을 열고:

/forge     # ⚡ 메인 — 시작 1회 질문 → 인계 패키지까지 통째로 (사람 게이트 0)

# 손으로 단계별로 몰고 싶을 때:
/plan      # 아이디어 → PRD (캐묻는 기획)
/design    # PRD → 와이어 → 디자인시스템 → 하이파이 → handoff (단계마다 OK)

• 세 스킬 모두 먼저 어느 프로젝트인지 고른다 — projects/의 각 STATUS.md를 대시보드로 보여주고, 멈춘 단계부터 이어간다. 폴더만 보고 추측하지 않는다.
• 처음이면 → 새 프로젝트 생성부터 안내한다.

📐 산출물 형식

• 화면·컴포넌트마다 외부 의존성 없는 독립 실행 HTML 1개. 브라우저로 바로 열린다. (상태 변화용 인라인 JS는 허용 — 금지는 외부 라이브러리지 JS가 아니다.)
• 디자인 토큰은 foundation/tokens.css에 표준 2단으로: primitive(--blue-500·중립 램프) → semantic 역할(--color-primary·--color-text…). 컴포넌트는 semantic만 참조.
• 각 파일 첫 줄에 카드 마커: <!-- @dsCard group="Wireframe|Foundation|Components|Screens" --> — 산출물을 그룹별로 분류·탐색한다.

✅ 품질 기준 (render-check)

산출물을 만들 때마다 스스로 점검하고, 걸리면 통과할 때까지 고친다(자동 편성 단계에선 독립 검증 에이전트가 본다):

| 항목 | 본다 | |---|---| | thin | 내용이 빈약한가 (상태·variant·실데이터가 충분한가) | | bad | 레이아웃이 깨졌나 (정렬·간격·오버플로우·반응형) | | variantsIdentical | variant·화면이 사실상 똑같아 보이나 | | off-brief | 00-flow.md/PRD에서 벗어났나 | | deadControl | 인터랙티브한데 와이어드 안 됨(범위 밖 라벨도 없음) | | stateInert | 눌렀는데 상태가 안 변함 | | wireframey | (하이파이) 렌더가 "와이어 + 색" 수준인가 — 깊이·여백·타이포 위계·인터랙션 부재. 렌더 스크린샷(픽셀)으로 본다(소스로는 못 잡음) |

하이파이 검증은 scripts/shoot.js로 화면을 실제 렌더한 PNG를 검증·트렌드 에이전트에게 넘겨 픽셀을 보게 한다(소스만 보던 픽셀맹 해소).

📦 handoff — 앱 레포로 넘기기

파이프라인의 최종 산출물이다. atelier는 코드를 직접 짜지 않는다 — 대신 디자인 패키지 + 인계 프롬프트를 만들고, 받는 쪽 Claude Code가 그걸 보고 자기 컨벤션으로 구현한다(특정 프레임워크·아키텍처에 안 묶임):

1. handoff/ 패키지 — 비주얼 문서(화면 임베드·흐름맵·화면별 스펙)·토큰 매핑표·컴포넌트 인벤토리, 그리고 인계에 필요한 소스(PRD·00-flow·화면·토큰)를 폴더 안에 복사한다.
2. hand-off.md — 받는 쪽에 붙여넣는 브리프: 어떤 파일을 참고하고 / 무엇을 지키고(흐름·기능·데이터 계약) / 무엇을 만들지. 경로는 전부 ./ 상대.
3. 토큰은 대상의 토큰 시스템에 매핑한다(통째 복붙 금지).

handoff/는 self-contained — 그 폴더 하나만 떼서 대상 프로젝트에 넘겨도 PRD(DB 설계 근거)·흐름·화면·토큰이 전부 들어 있다(프로젝트 루트를 함께 줄 필요 없음). node scripts/pack-handoff.js <name>가 소스를 복사하고 경로를 ./로 고친 뒤, node scripts/lint-handoff.js <name>가 완결성+self-contained를 자동 검사한다 — chosen 화면이 다 실렸나·토큰/컴포넌트가 다 있나·placeholder 안 남았나·필요 소스가 handoff/에 복사됐고 패키지가 밖을 참조 안 하나. green 없이 "완료" 없다. (/forge는 이 게이트까지 자동으로 통과시킨다.)