콘텐츠로 이동

빠른 시작

클론부터 첫 디자인 산출물까지 5분.

1. 설치 (Claude Code)

git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai
cd ~/dev/design-ai
./install.sh

21개 스킬, 16개 공개 슬래시 명령어, 4개 리뷰 에이전트가 ~/.claude/ 아래에 심볼릭 링크로 설치돼요. Claude Code를 다시 시작(또는 새 세션 열기)하면 적용돼요.

확인:

./install.sh --status

21 skills, 4 agents, 16 public commands가 설치되었다고 나와야 해요.

design-ai doctor

설치 상태, runtime 전제 조건, symlink target이 의심될 때 이 명령으로 먼저 진단하세요. 경고가 design-ai symlink 누락뿐이라면 design-ai doctor --fix로 갱신하세요.

design-ai route "audit a Figma signup flow for Korean fintech" --explain
design-ai routes
design-ai prompt "audit a Figma signup flow for Korean fintech"
design-ai review-pack korean-fintech
design-ai review page.html --brief "한국 핀테크 설정 검토" --repo-url https://github.com/acme/settings --local-path /absolute/path/to/settings --review-pack korean-fintech --locale ko-KR --viewport mobile --viewport desktop --json
design-ai review-handoff review-workflow.json --recipient implementation-agent --json
design-ai review-handoff-verify review-handoff.json --consumer implementation-agent --json
design-ai review-intake review-handoff-receipt.json --target-root /absolute/path/to/settings --consumer implementation-agent --json
design-ai review-scope target-repo-intake.json --request implementation-scope-request.json --consumer implementation-agent --json
design-ai review-scope-approve implementation-scope-proposal.json --approver "product owner" --approval-ref "approved in task" --approved-at "2026-07-15T12:00:00.000Z" --yes --json
design-ai review-evidence implementation-scope-approval.json --request implementation-evidence-request.json --target-root /absolute/path/to/settings --consumer implementation-agent --json
design-ai inspect page.html --brief "한국 핀테크 설정 검토" --review-pack korean-fintech --locale ko-KR --viewport mobile --viewport desktop --json
design-ai benchmark --strict
design-ai pack "audit a Figma signup flow for Korean fintech" --max-bytes 80000
design-ai prompt --from-file product-brief.md --route design-review --out prompt.md
cat product-brief.md | design-ai pack --stdin --out prompt-pack.md
design-ai pack "audit a Figma signup flow for Korean fintech" --out audit-pack.md
design-ai check output.md --route component-spec --strict
design-ai check --examples --route design-from-brief --limit 1
design-ai check --examples --all-routes --issues-only
design-ai examples --route component-spec --limit 5
design-ai learn --remember "Prefer dense Korean product UI" --category korean
design-ai learn --feedback "Keep audit findings short and evidence-led" --outcome keep
cat feedback.md | design-ai learn --feedback --stdin --outcome improve --category workflow
design-ai learn --backup --json --out learning-backup.json
design-ai learn --redact --json --out learning-redacted.json
design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force
design-ai learn --verify --from-file learning-backup.json
design-ai learn --import --from-file learning-backup.json --dry-run
design-ai learn --list --category korean --limit 5
design-ai learn --list --query "keyboard accessibility" --explain --json
design-ai learn --audit
design-ai learn --audit --fix --dry-run
design-ai learn --stats --json
design-ai prompt "audit a Figma signup flow" --with-learning --learning-category korean --learning-limit 5
design-ai search Pretendard --dir knowledge --limit 5
design-ai show knowledge/PRINCIPLES.md:29

design-ai benchmark는 패키지에 포함된 네 전문화 사례를 실행하고 종합 품질 점수 없이 계약 유효성, 정확한 finding 비교, 권한 경계, 남은 미검증 위험을 보여줍니다. 제품 전문화 벤치마크를 참고하세요.

기존 HTML 산출물은 design-ai review에서 시작하는 것이 기본입니다. route와 design contract, static quality report를 함께 반환하고 문맥과 SHA-256 linkage를 증명한 뒤 browser verification과 구현 전에 멈춥니다. 품질 보고서만 필요할 때는 하위 수준의 inspect를 사용하세요. 표준 디자인 리뷰 워크플로우를 참고하세요.

승인한 selector만 구현한 뒤 commit 전에 design-ai review-evidence를 실행하세요. 승인 당시 기준점과 현재 Git 상태를 비교하고, 실행하지 않은 검증은 그대로 미실행으로 남기며, 선언한 증빙 파일만 해시로 확인합니다. 구현 증빙을 참고하세요.

수신 에이전트는 design-ai review-handoff-verify로 handoff 원본을 다시 검증하고 consumer receipt를 만듭니다. 이는 계약 검증만 증명하며 신원, 전송, 수락, 대상 저장소 확인, 구현은 여전히 미검증입니다. 리뷰 인계 검증 영수증을 참고하세요.

그다음 design-ai review-intake로 영수증에 선언된 경로와 remote가 실제 로컬 checkout과 같은지 확인하고 루트 project metadata와 Git 상태를 기록합니다. 애플리케이션 소스를 읽거나 구현을 허가하지 않습니다. 대상 저장소 사전 점검을 참고하세요.

다른 에이전트나 검토자가 리뷰를 이어받을 때는 design-ai review-handoff를 사용하세요. 원본 workflow JSON과 수신자를 보존하고 전송과 수신자 검증이 대기인 상태에서 멈춥니다. 정확한 브라우저 근거가 있을 때만 --quality-report와 --browser-verification을 함께 전달하세요. 리뷰 근거 인계를 참고하세요.

맞는 command, 재사용 가능한 agent prompt, portable context bundle, artifact QA, known-good reference, opt-in local preference, 정확한 knowledge file을 찾아야 할 때 CLI route + prompt + pack + check + examples + learn + search + show를 사용하세요. design-ai route --explain은 왜 해당 route가 매칭됐는지와 참조 파일이 몇 개 사용 가능한지 보여줘요. 생성된 prompt에는 선택된 route id, routing reason, reference examples, 읽을 파일 목록, 실행 규칙, 추천 design-ai check output.md --route <id> --strict 명령, route-aware verification checklist가 포함돼요. 생성된 pack에는 context summary와 truncated/unavailable file warning이 들어가고, 가능한 경우 선택된 reference example file까지 포함돼서 다른 agent에 보내기 전에 bundle이 충분한지 판단할 수 있어요. design-ai learn은 local preference entry를 저장하고, 명시적 --feedback을 durable keep/improve/avoid guidance로 바꾸며, inline text / --from-file / --stdin feedback, category/query/limit filtering, 전체 portable --backup --json, local profile 또는 portable JSON을 --redact --from-file / --redact --stdin으로 받아 공유용 redacted --redact --json 출력 생성, --out file JSON artifact 저장과 --force overwrite control, portable JSON --verify, --dry-run preview와 confirmed --yes merge를 포함한 portable import, cleanup suggestion을 포함하는 non-mutating --audit, 안전한 --audit --fix --dry-run preview와 confirmed --fix --yes cleanup, --stats summary, confirmed --forget/--clear control을 지원해요. learn --list --query --explain과 learn --export --query는 recency fallback 없이 query와 맞는 local preference를 보여주고, list 설명에는 score, matched token, selection reason이 포함돼요. prompt/pack --with-learning은 명시적으로 요청했을 때만 entry를 포함하며 현재 brief와의 relevance로 먼저 정렬한 뒤 recency로 보완하고, --learning-category와 --learning-limit으로 주입 범위를 좁히며, warning profile이 보이도록 learned-context audit summary를 함께 넣어요. design-ai check는 생성된 Markdown이 grounding, unresolved marker, accessibility, responsive, screen-reader, misuse guidance를 갖췄는지 검사하고, --route <id>를 주면 산출물 유형별 route-specific evidence도 함께 점검해요. --learn --yes를 추가하면 warn/fail check 결과를 local learning entry로 저장해요. design-ai check --examples --route <id>를 쓰면 같은 QA rule로 해당 workflow의 worked example도 검사할 수 있고, design-ai check --examples --all-routes --issues-only는 maintainer용 전체 example QA gap summary를 출력해요. design-ai examples --route <id>는 선택한 workflow에 맞는 worked output을 찾아줘요. 실제 product/design brief가 shell 한 줄보다 길면 --from-file 또는 --stdin을 사용하세요. 자동 routing이 거의 맞지만 특정 workflow를 고르고 싶다면 --route <id>를 사용하세요. id는 design-ai routes, design-ai route --list, 또는 design-ai route "..." --json에서 확인할 수 있어요.

2. 첫 번째 작업 세 가지

작업 1: 컴포넌트 스펙 만들기

/design-component-spec Banner

다음을 포함한 개발자용 스펙을 받아요: - 아나토미 (parts table) - API (props, types, defaults) - 상태 (default / hover / focus / active / disabled / loading / error) - 변형 (size, color, shape) - 사용된 토큰 - ARIA + 키보드 계약 - 엣지 케이스 (empty / overflow / RTL / 모션 감소) - 코드 예제 - Don't 섹션

자연어로 반복 작업: "닫을 수 있는 변형을 추가해줘", "한국어 카피는 어떻게 할까?"

작업 2: 디자인 리뷰

어떤 산출물(스크린샷, Figma 링크, URL)에 대해서든 UX + 접근성 + 디자인 비평을 병렬로 받아요:

/design-design-review [이미지 또는 URL 붙여넣기]

반환되는 것: 최우선 추천 사항, 크리티컬 이슈, 접근성 발견, 고려할 UX 패턴.

작업 3: 처음부터 만들기

/design-from-brief 프리랜서를 위한 한국 핀테크. 인보이스, 경비 추적, 세금 추정. 신뢰감 있고, 차분하고, 모바일 우선. Pretendard 타이포그래피, 블루 위주 팔레트.

완전한 디자인 시스템을 생성: 팔레트 + 파운데이션 + 컴포넌트 베이스라인 + 5개 컴포넌트 스타터 셋 + 핸드오프 문서.

3. 도메인 스킬 시도하기

v2 확장에서 7개 새 도메인을 추가했어요. 각각 슬래시 명령어가 있어요:

명령어 용도
/design-motion-design 모션 스펙 (CSS / Framer Motion / GSAP / Lottie)
/design-illustration 일러스트레이션 시스템 또는 단일 작업
/design-print 인쇄물 스펙 (명함, 브로슈어, 패키징)
/design-video 비디오 스펙 (마케팅, 소셜, 인앱)
/design-game-ui 게임 UI 스펙 (HUD, 메뉴, 인벤토리)
/design-conversational 챗봇, 음성 비서, AI 챗 스펙
/design-spatial VR / AR / Vision Pro 경험 스펙

예시:

/design-motion-design 한국 핀테크 랜딩 페이지 히어로 루프. Toss 스타일 절제. 8초. 모바일 + 데스크톱.

4. 지식 베이스 둘러보기

스킬이 컨텍스트가 필요하면 knowledge/를 읽어요. 직접 둘러봐도 좋아요:

5. 다른 에이전트에서

에이전트 방법
Codex CLI 이 폴더를 프로젝트 루트로 열어요. AGENTS.md가 자동 로드돼요.
Cursor 이 폴더를 열고 AGENTS.md를 .cursorrules로 심볼릭 링크.
Aider aider --read AGENTS.md
일반 프롬프트 어떤 skills/*/PLAYBOOK.md 본문이든 프롬프트에 붙여넣으세요.
Anthropic SDK PLAYBOOK.md를 시스템 프롬프트에 임베드; 관련 knowledge/*.md 파일 참조.

각 PLAYBOOK.md는 자기 완결적이고 통째로 붙여넣으면 작동해요 — 나머지 레포 없이도.

한국어 기본값

대상 사용자가 한국인이면: - 스킬은 B2C에 해요체, B2B / 뱅킹에 합쇼체를 자동 적용해요. - Pretendard 타이포그래피가 기본값. - 명함 90×50 (국제 85×55 아님). - KFDA / 표시광고법 / 정보통신망법 / 게임산업진흥법 컴플라이언스가 인쇄 / 비디오 / 게임 UI 스킬에 내장. - 본인인증 (PASS / NICE / KCB) 플로우는 인증 스킬에 포함. - 한국 주식 차트 빨간색=상승 (서양과 반대 — knowledge/i18n/에 인코딩).

스킬 입력에서 오버라이드: "글로벌 1순위, 영문 카피".

유지보수

# 유지보수자 전용: refs/ (gitignored 업스트림 소스) 재추출
./tools/extractors/run-all.sh

# 수동으로 검사 실행
design-ai audit --strict

# HTML 토큰 미리보기 렌더링
python3 tools/preview/render-tokens.py

CI는 모든 PR에서 8개 검사를 실행해요.

다음 단계

이슈

스킬이 잘못된 / 일반적인 / 환각 출력을 만들면: 그건 지식 격차예요. 스킬 이름 + 프롬프트 + 예상 vs 실제로 이슈를 열어주세요. 대부분의 수정은 knowledge/에 들어가요 (스킬 자체가 아니라) — 플레이북은 작게, 코퍼스는 크게.