AI 코딩 에이전트에게 화면을 맡기면 동작은 금방 갖춰지지만, 결과물이 어딘가 비슷비슷하고 "AI가 만든 티"가 나는 경우가 많아요. Impeccable은 이 지점을 겨냥한 디자인 품질 도구예요. 에이전트 채팅에서 원하는 결과를 말하면, Impeccable이 프로젝트의 사용자·디자인 규칙을 읽고 방향을 제안한 뒤 만들고 검토까지 해 줘요.
이 글은 공식 문서(Docs, Install & first steps)를 바탕으로, 개념을 먼저 잡고 첫 작업까지 직접 적용해 볼 수 있게 정리했어요.
출처: https://impeccable.style (Paul Bakaus, GitHub pbakaus/impeccable)
Impeccable은 무엇인가
공식 문서는 Impeccable을 "머릿속에 있는 인터페이스를 만들거나, 지금 있는 인터페이스를 개선하는" 도구로 소개해요. 핵심은 특별한 명령을 몰라도 된다는 점이에요. 채팅에 결과를 설명하면 되고, 명령은 변경의 종류를 이미 알 때 쓰는 집중 도구에 가까워요.
동작 방식은 크게 세 가지 축으로 이해하면 쉬워요.
- 프로젝트 맥락: 사용자와 목표는
PRODUCT.md, 시각 규칙은DESIGN.md에 기록하고 디자인 작업 전에 읽음 - 스킬(명령):
polish,critique,audit등 목적별 명령 24개 - 자동 점검(hooks): 에이전트가 UI를 고칠 때마다 detector가 검사하고 결과를 에이전트에게 되돌려 줌
지원 도구는 Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Kiro 등 다양해요. 도구마다 붙는 통합 기능은 조금씩 달라요.
| 도구 | 통합 방식 |
|---|---|
| Claude Code | hooks + subagent |
| Cursor | pre-edit hook |
| Gemini CLI, Codex CLI | 모델별 디자인 가이드 |
| GitHub Copilot 앱 | 기본 내장 (Settings → Experimental) |
1단계: 설치
준비물은 코딩 도구, 프로젝트 폴더, Node.js 18.19 이상이에요. 빈 프로젝트나 막 스캐폴딩한 앱도 괜찮아요. 프로젝트 폴더에서 설치 프로그램을 실행하면 사용할 도구와 설치 범위(이 프로젝트만 / 모든 프로젝트)를 고를 수 있어요.
npx impeccable install설치가 끝나면 코딩 도구를 한 번 다시 불러와야(reload) 해요. 다시 불러온 뒤에도 보이지 않으면 설치 프로그램을 다시 실행하고 도구와 설치 범위를 확인해 보세요.
다른 설치 경로도 있어요.
# Claude Code 채팅에서 실행 → /plugin → Discover → Impeccable 설치
/plugin marketplace add pbakaus/impeccable
# 공용 스킬만 설치 (도구별 통합은 위 설치 프로그램 권장)
npx skills add pbakaus/impeccableGitHub Copilot 앱은 Impeccable이 내장되어 있어서 Settings → Experimental에서 켜기만 하면 돼요.
팀 단위로 버전 고정하기
팀이 같은 버전을 쓰게 하려면 Git submodule로 소스를 넣고 링크하는 방법이 있어요. claude,cursor는 팀이 쓰는 도구로 바꾸면 돼요.
git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor.gitmodules, submodule 참조, 생성된 링크를 커밋하면 팀원은 아래 명령 하나로 받아요.
git submodule update --init --recursive새 버전을 반영할 때는 submodule을 갱신하고 다시 링크한 뒤 새 참조를 검토·커밋해요.
git submodule update --remote vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor단, link는 스킬만 설치하고 디자인 hook은 설치하지 않아요. 기존 스킬 폴더는 --force를 주지 않는 한 그대로 남아요.
2단계: 프로젝트 맥락 주기와 hooks 켜기
여기서부터는 터미널이 아니라 에이전트 채팅에 입력해요.
출처: impeccable.style
/impeccable init
/impeccable hooks oninit을 실행하면 Impeccable이 프로젝트를 읽고, 빈 부분을 질문으로 채워요. 이때 누가 쓰고 무엇을 해야 하는지를 설명하는 게 중요해요. 공식 예시는 이래요.
Our customers reorder the same supplies every week. They need to find their usual items and check out quickly, often on a phone.
기존 제품명이나 접근성 요구처럼 꼭 지켜야 할 조건도 함께 알려 주세요. 색상·폰트는 디자인 작업 단계로 미뤄도 돼요. 합의된 내용은 PRODUCT.md에 저장되고 이후 명령이 모두 이 파일을 참고하므로, 한 번 읽어 보고 잘못 이해한 부분을 고쳐 두는 게 좋아요.
hooks on은 자동 점검을 켜는 명령이에요. 다만 코딩 도구 쪽에서도 hook 실행을 허용해야 점검이 돌아가요. Codex라면 앱의 Settings → Hooks나 CLI의 /hooks에서 Impeccable의 PostToolUse, Stop hook을 검토하고 신뢰해야 하고, 그 전까지는 실행되지 않아요.
출처: impeccable.style
왼쪽 화면처럼 Impeccable은 tokens.css, tailwind.config.ts, 컴포넌트 폴더, DESIGN.md를 훑어 기존 디자인 규칙을 그대로 따라요. 이미 디자인 시스템이 있다면 빌드 전에 아래 명령으로 색상·타이포그래피·컴포넌트 규칙을 DESIGN.md에 기록해 두세요. 스타일이 없는 스캐폴드라면 건너뛰어도 돼요.
/impeccable document시안 먼저 vs 바로 코드로
init은 새 디자인을 어떻게 시작할지 기본값을 물어볼 수 있어요. 나중에 디자인 선택기에서 바꿀 수 있으니 부담 없이 골라도 돼요.
| 방식 | 특징 |
|---|---|
| Mockup first (comp-led) | 더 과감한 시각 방향, 이미지를 코드로 옮기며 디테일 손실, 여러 번의 프롬프트·검토 필요 |
| Build directly (code-led) | 첫 구현의 일관성이 높음, 시각적 과감함은 덜함 |
시안 방식은 코딩 도구의 이미지 생성 기능이나 OpenAI API 키가 필요하고, 생성 시간과 사용량이 늘어요. 이미지 접근이 없으면 Impeccable은 자동으로 코드부터 만들어요.
3단계: 첫 작업 고르기
평소 말투로 요청하면 충분해요. 길은 두 가지예요.
새로 만들기
/impeccable design a signup page for our monthly book club. Help visitors understand the next event and reserve a seat.
Impeccable은 빠진 정보를 채우고, 고르고 조정할 수 있는 방향을 제안한 다음, 인터페이스를 만들고 검토해요. 시안 방식이라면 구현 전에 구도를 먼저 승인하게 되고, 이미 자리 잡은 제품 안의 새 페이지라면 그 제품의 시각 체계를 따라요. 구현 전에 계획(디자인 브리프)에서 멈추고 싶다면 shape를 쓰면 돼요.
기존 화면 다듬기
출처: impeccable.style
/impeccable polish the pricing page. Keep our colors, plan names, and monthly/yearly switch.
polish는 기존 디자인 안에서 간격, 타이포그래피, 라벨, 상호작용 상태를 다듬어요. 위 예시처럼 지켜야 할 것을 요청에 함께 적으면 그 범위 안에서만 바뀌어요. 무엇을 고쳐야 할지 모르겠다면 먼저 critique로 진단을 받고, 결과를 읽은 뒤 손볼 항목을 고르면 돼요.
/impeccable critique the pricing page
4단계: 결과 검토
결과가 나오면 페이지를 열고 핵심 작업(좌석 예약, 요금제 비교 후 선택 등)을 직접 해 보세요. 좁은 화면도 확인하고 코드 변경도 검토하는 게 좋아요. 그다음 유지할 것과 고칠 것을 구체적으로 말해 주면 돼요.
The plan comparison is easier to read now. Keep that, but restore the monthly/yearly switch above it.
전체 디자인 방향 자체가 마음에 들지 않는다면 polish를 반복하기보다 redesign을 요청하세요. polish는 기존 디자인을 다듬을 뿐 방향을 바꾸지는 않기 때문이에요.
명령 한눈에 보기
명령은 목적별로 여섯 묶음, 총 24개예요.
| 묶음 | 명령 | 용도 |
|---|---|---|
| Create | impeccable, shape | 원하는 결과 설명, 아이디어를 디자인 브리프로 전환 |
| Evaluate | audit, critique | 구현 문제 찾기와 우선순위, 디자인의 약점 진단 |
| Refine | animate, bolder, colorize, delight, layout, overdrive, quieter, typeset | 모션, 존재감, 색, 즐거운 순간, 배치, 과감함, 소음 줄이기, 가독성 |
| Simplify | adapt, clarify, distill | 다른 화면·기기 대응, 상황 안내 문구, 군더더기 제거 |
| Harden | harden, onboard, optimize, polish | 오류·빈 데이터 대응, 첫 사용 경험, 성능 측정·개선, 마무리 손질 |
| System | document, extract, generate, init, live | 시각 체계 기록, 공용 컴포넌트 추출, 변형 비교, 맥락 설정, 브라우저에서 실시간 변형 |
배포 전에는 audit로 접근성, 성능, 반응형 동작 같은 구현 문제를 점검할 수 있어요.
/impeccable audit the pricing page
업데이트
설치 방식에 따라 업데이트 방법이 달라요. 업데이트한 뒤에도 코딩 도구를 다시 불러와야 해요.
npx impeccable update # npx impeccable install로 설치한 경우
npx skills update impeccable # npx skills add로 설치한 경우Claude Code 플러그인 마켓플레이스로 설치했다면 /plugin 메뉴에서 업데이트해요.
마치며
Impeccable을 잘 쓰는 요령은 명령을 외우는 것보다 맥락을 잘 주는 것에 있어요. PRODUCT.md에 사용자와 목표를, DESIGN.md에 시각 규칙을 적어 두면 이후의 polish, audit, layout이 모두 그 기준으로 움직여요. 처음이라면 설치 → init → 기존 페이지 하나에 critique와 polish 순서로 시작해 보세요. 결과가 일관되게 쌓이기 시작하면 디자인 시스템 기록(document)과 변형 비교(generate, live)로 범위를 넓히면 돼요.