Impeccable — AI 코딩 에이전트용 프론트엔드 디자인 스킬

개요

Impeccable은 AI 코딩 에이전트가 웹 프론트엔드의 시각적·UX 품질을 개선하도록 디자인 어휘, 명령 체계, 결정론적 안티패턴 검사, 브라우저 기반 반복 기능을 묶은 오픈소스 스킬 패키지다. README의 현재 설명은 1 skill, 23 commands, live browser iteration, 59 deterministic detector rules다.

이 저장소는 처음부터 새 모델을 학습시키는 프로젝트라기보다, Claude Code·Codex·Cursor 등 여러 하네스에 동일한 디자인 실행면을 배포하는 스킬 + CLI + provider-native hook 프로젝트로 보는 편이 정확하다.

공식 확인

초기화 중심 워크플로우: npx impeccable install 후 /impeccable init을 실행한다. init은 프로젝트가 brand surface인지 product surface인지 묻고, 제품·대상·브랜드·목소리·색·타이포그래피·컴포넌트 맥락을 PRODUCT.md에 기록하며 DESIGN.md 생성을 제안한다.
23개 통합 명령: craft, shape, init, document, extract, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live를 /impeccable <command> <target> 형식으로 사용한다.
평가와 정제의 분리: critique는 UX 디자인 리뷰, audit는 접근성·성능·반응형 등 기술 품질 점검, polish는 출시 전 최종 정제, harden은 오류·국제화·엣지 케이스를 다룬다. bolder/quieter와 distill은 시각적 강도와 복잡도를 조정한다.
결정론적 detector: CLI와 브라우저 확장은 LLM이나 API 키 없이 결정론적 규칙을 실행할 수 있다. README는 AI-generated frontend의 반복 패턴과 일반 품질 문제를 합쳐 59개 규칙을 제공한다고 설명한다.
브라우저 반복: live는 브라우저에서 요소를 선택해 시각적 변형을 만들고 비교하는 모드다. 저장소에는 브라우저 DOM·세션·스크린샷 관련 스크립트가 포함되어 있다.
하네스 확장: 기본 설치기는 Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, Grok Build 등을 감지하고 provider별 skill/hook을 설치한다. README에는 OpenCode, Pi, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, Google Antigravity도 지원 대상으로 열거되어 있다.
provider-native hook: Claude Code·GitHub Copilot·Codex·Cursor·Grok Build에 UI 파일 편집 후 detector를 실행하는 hook manifest를 설치할 수 있다. Codex는 설치 후 /hooks에서 프로젝트 hook 승인이 필요하다고 안내한다.
현재 패키지: package.json 기준 버전은 3.5.0, 라이선스는 Apache-2.0, CLI 바이너리는 impeccable, Node 요구 버전은 >=22.18.0이다.

기본 사용 흐름

# 프로젝트 루트에서
npx impeccable install
 
# 각 AI 코딩 하네스 세션에서
/impeccable init
/impeccable audit checkout
/impeccable polish checkout

기존 설치 갱신은 npx impeccable update를 사용한다. 스크립트 환경에서는 --providers=claude,codex,cursor,grok와 --scope=project|global로 설치 대상을 고정할 수 있다. 독립 detector만 사용하려면 다음처럼 실행한다.

npx impeccable detect src/
npx impeccable detect --json .
npx impeccable ignores list

디자인 원칙과 안티패턴

저장소가 문제 삼는 전형적인 AI UI 패턴은 Inter·시스템 폰트의 반복, 보라색-파란색 그라디언트, 카드 안의 카드, 색 배경 위 회색 텍스트, 모든 제목 위의 둥근 아이콘 타일 등이다. 일반 규칙에는 과도한 카드 래핑, 순수 검정/회색, bounce·elastic easing, 작은 터치 영역, 잘못된 헤딩 구조 등이 포함된다.

스킬 원문은 네 가지 visitor mode를 구분한다.

Persuade: 랜딩·마케팅처럼 방문자의 결정과 행동이 목표인 화면
Operate: 대시보드·에디터·설정처럼 작업 완료와 스캔 가능성이 중요한 화면
Read: 문서·가이드처럼 이해와 체류가 목표인 화면
Experience: 포트폴리오·갤러리처럼 작업물 자체가 앞에 서는 화면

GitHub 실측 스냅샷 (2026-08-05)

항목	값
Stars / forks	55,162 / 3,335
Open issues	44
생성 / 최근 push	2025-11-16 / 2026-08-04
라이선스	Apache-2.0
GitHub primary language	JavaScript
default branch	`main`
GitHub topics	없음
archived	아니오

균형 잡힌 평가와 주의점

59개 detector 규칙은 반복 가능한 품질 신호를 제공하지만, 좋은 디자인의 맥락·브랜드 적합성·제품 전략까지 자동 판정하지는 않는다. UX 리뷰와 미감 판단은 여전히 연결된 모델과 프로젝트 맥락에 의존한다.
“AI harness를 더 디자인 잘하게 한다”는 프로젝트 포지셔닝이다. 이 저장 세션에서는 여러 하네스에서 실제 UI를 생성하고 전후 품질을 측정하는 독립 벤치마크를 수행하지 않았다.
provider별 generated skill/hook 디렉터리가 많아 설치·업데이트 시 파일 충돌과 버전 동기화 비용이 생길 수 있다. npx impeccable update와 Codex hook 승인 절차를 운영 규칙에 포함해야 한다.
Node >=22.18.0 요구사항과 브라우저 live mode는 구형 런타임·헤드리스 환경·도구별 hook 정책에서 제약이 될 수 있다.
기존 위키 메모의 npx skills add pbakaus/impeccable 안내보다 현재 README의 표준 경로인 npx impeccable install이 우선이다. 이 저장에서는 그 차이를 최신화했다.

출처 및 검증

canonical source: https://github.com/pbakaus/impeccable
raw capture: raw source: github-pbakaus-impeccable
캡처 브랜치: main (default_branch를 GitHub REST API에서 확인)
raw body SHA-256: f3a80d07ab531105f1ebdcc933f85c71a92b734da97a06d639c0bab2c2f8edb
선택 파일: skill/SKILL.src.md, package.json, .github/hooks/impeccable.json
pointer repair: 기존 capture: pointer raw stub을 같은 파일명으로 현재 공식 캡처로 복구했다.
검증 범위: 저장소 메타데이터, default branch README, 스킬 원문, 패키지 설정, GitHub hook 설정, 내부 위키 링크와 raw body 해시. 실제 하네스별 설치·UI 품질 벤치마크는 이 저장 세션에서 수행하지 않았다.

description	AI 코딩 에이전트에 디자인 어휘·23개 명령·브라우저 반복·결정론적 안티패턴 검사를 제공하는 오픈소스 스킬 패키지.
tags	ai-coding, dev-tools, open-source, automation

LLM Wiki

탐색기