Codex와 Claude Code에서 Impeccable 사용하는 방법.

Impeccable은 코딩 에이전트에게 디자인 어휘를 줍니다. bolder, quieter, critique, polish 같은 명령과, 모델을 호출하지 않고 AI가 만든 패턴을 찾아내는 디텍터입니다. 이미 있는 인터페이스에 가장 잘 맞습니다. 이 튜토리얼은 Codex와 Claude Code에 설치하는 방법, 프로젝트용 설정, 먼저 익힐 만한 명령, 전부 켜기 전에 확인할 설정을 다룹니다.

2026년 11월 6일 업데이트 · 8분 분량

Impeccable이란

Impeccable은 Paul Bakaus가 만든 오픈소스 디자인 스킬(Apache 2.0)입니다. Anthropic의 frontend-design 스킬에서 출발해 두 가지로 성장했습니다. bolder, quieter 같은 디자인 동작부터 critique, audit 같은 검토까지 이름이 붙은 24개 명령, 그리고 AI 티와 품질 문제를 잡는 62개 규칙의 결정론적 디텍터입니다. 버전 4.8은 Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI와 그 밖의 많은 에이전트에서 작동합니다.

설치하기

프로젝트 루트 폴더에서 실행하세요.

npx impeccable install

설치 프로그램은 사용 중인 코딩 도구를 찾아, 이 프로젝트에만 설치할지 모든 프로젝트에 설치할지 묻고, 에이전트가 수정하는 모든 UI 파일을 점검하는 디자인 훅을 설치할지 제안합니다. 끝난 뒤에는 도구를 다시 불러오세요.

Codex: /hooks를 열어 프로젝트 훅을 승인하세요. 승인하지 않으면 실행되지 않습니다. 훅이 바뀌는 업데이트 뒤에도 다시 승인해야 합니다. Codex에서는 슬래시 명령 대신 $impeccable(또는 /skills)로 스킬을 호출합니다.
Claude Code: 설치 프로그램이 여기서도 작동합니다. 또는 /plugin marketplace add pbakaus/impeccable로 플러그인을 추가한 다음 /plugin에서 Impeccable을 설치하세요.

Node는 npx를 실행할 때만 필요합니다. 스킬은 ~/.impeccable/bin/에 한 번 내려받는 작은 엔진을 실행합니다. 업데이트하려면 npx impeccable update를 실행하세요.

프로젝트에 맞게 설정하기

프로젝트마다 init을 한 번 실행하세요.

$impeccable init      # Codex
/impeccable init      # Claude Code and most other agents

init은 코드를 읽고 스스로 알아낼 수 없는 것만 묻습니다. 제품이 누구를 위한 것인지, 무엇을 해야 하는지, 제약 조건이 무엇인지입니다. 그리고 PRODUCT.md를 작성합니다. 이후의 모든 명령이 이 파일을 읽습니다. 앱에 이미 시각적 스타일이 있다면 다음으로 document를 실행해 DESIGN.md에 담아 두세요. 그러면 이후 변경도 브랜드에서 벗어나지 않습니다. 두 파일 모두 저장소에 보관하세요.

컴포넌트 하나로 시작하기

Impeccable은 좁은 대상에서 가장 잘 작동합니다. 페이지 전체를 훑어보는 것보다 한 섹션을 꼼꼼히 검토하는 편이 낫습니다. 명령과 대상을 지정하세요.

/impeccable critique the pricing cards
/impeccable quieter the landing page hero
/impeccable typeset the settings page
/impeccable polish checkout

Codex에서는 /impeccable 대신 $impeccable을 쓰세요. “이 히어로 섹션 다시 해 줘”처럼 원하는 것을 그냥 설명해도 됩니다.

먼저 익힐 만한 명령

그룹	명령	용도
방향 잡기	`bolder`, `quieter`, `distill`, `colorize`, `typeset`, `layout`, `animate`, `delight`, `overdrive`	디자인의 한 부분을 분명한 방향으로 밀어붙이기
검토	`critique`, `audit`	점수가 매겨진 UX 리뷰, 또는 P0부터 P3까지 순위를 매긴 기술 보고서 받기
마무리	`polish`, `harden`, `clarify`, `adapt`, `optimize`, `onboard`	최종 점검, 예외 상황, 카피, 화면 크기, 속도, 첫 실행 상태
반복	`live`, `generate`	브라우저에서 요소의 여러 변형 시도하기
설정	`shape`, `init`, `document`, `extract`	UX 계획, 컨텍스트 파일 작성, 반복되는 패턴을 시스템으로 추출

좋은 첫 루프는 이렇습니다. 화면 하나를 critique하고, quieter나 typeset 같은 방향 명령으로 가장 큰 문제를 고친 다음, polish합니다. /impeccable만 입력하면 에이전트에서 전체 목록을 볼 수 있고, 자주 쓰는 명령은 /impeccable pin audit으로 고정할 수 있습니다.

AI 티 디텍터 실행하기

디텍터는 31개의 AI 티 규칙과 31개의 품질 규칙, 모두 62개 규칙을 점검하며 모델이나 API 키가 필요 없습니다.

npx impeccable detect src/                   # scan your source files
npx impeccable detect http://localhost:5173  # scan a rendered page in Chrome or Edge
npx impeccable detect --github src/          # annotations for GitHub Actions
npx impeccable detect --list-rules           # list every rule

소스 파일에는 패턴 규칙이 적용됩니다. 낮은 대비나 너무 작은 글씨처럼 렌더링된 페이지가 필요한 규칙은 URL을 스캔할 때만 실행되므로, 개발 서버도 함께 가리키세요. 문제를 발견하면 종료 코드 2로 끝나므로 CI 검사를 실패시키기 쉽습니다. 브랜드 폰트가 과다 사용 폰트 목록에 있다면 npx impeccable ignores add-value overused-font Inter --reason "Brand font"로 허용하세요.

먼저 확인할 설정

Claude Code에서는 훅이 모델 승인과 무관하게 실행됩니다. 설치된 훅은 모델의 명령을 거부해도 실행되므로 첫 수정에서 엔진을 내려받을 수 있습니다. 사람이 지켜보지 않는 실행 전에 훅을 검토하세요.
라이브 모드는 승인 없이 에이전트를 실행할 수 있습니다. live 모드에서 수정을 적용할 때 듣고 있는 채팅 세션이 없으면 승인과 샌드박스를 끈 채 codex나 claude CLI를 시작합니다. 라이브 모드를 시작하기 전에 IMPECCABLE_LIVE_COPY_AGENT=chat을 설정하면 채팅 안에 머물고, off로 설정하면 이 기능이 꺼집니다.
텔레메트리. 새 디자인은 impeccable.style 카탈로그에서 시각적 방향을 가져옵니다. 텔레메트리를 끄면(npx impeccable telemetry off 또는 DO_NOT_TRACK=1) 어떤 방향을 골랐는지에 대한 익명 기록은 멈추지만, 그 요청 자체는 멈추지 않습니다.
뭔가 고장 났나요? /impeccable doctor가 오래된 컨텍스트 파일과 망가진 훅을 찾아 줍니다.

자주 묻는 질문

Impeccable은 무료인가요?

네. Apache 2.0 라이선스의 오픈소스입니다.

Impeccable은 Codex에서 작동하나요?

네. npx impeccable install을 실행하고, /hooks에서 프로젝트 훅을 승인한 뒤, $impeccable로 호출하세요.

Impeccable로 모바일 앱도 디자인할 수 있나요?

네. 웹사이트뿐 아니라 앱 화면도 다루며 iOS와 Android 레퍼런스가 있습니다. 다른 선택지와 나란히 비교한 내용은 Taste Skill vs Impeccable vs UI UX Pro Max를 참고하세요.