impeccable — AI 없이 돌리는 프론트엔드 디자인 lint, 24개 안티패턴 탐지기

AI가 만들어주는 UI, 근데 다 비슷하게 생겼다

Claude나 Cursor로 프론트엔드를 만들다 보면 묘하게 익숙한 결과물이 나온다. Inter 폰트, 보라-파랑 그라디언트, 카드 안에 카드, 컬러 배경 위 회색 텍스트. 모델이 같은 SaaS 템플릿 데이터로 훈련됐으니 비슷한 패턴을 반복하는 건 자연스럽다.

문제는 이걸 잡는 방법이 마땅치 않다는 거다. 디자이너가 직접 리뷰하거나, AI한테 다시 물어보거나. 두 방법 모두 매 커밋마다 적용하기 어렵다.

impeccable이 푸는 문제

impeccable은 Claude Code용 디자인 스킬이다. 하지만 이 도구의 진짜 차별점은 스킬 자체보다 같이 딸려오는 CLI 안티패턴 탐지기에 있다.

npx impeccable detect를 실행하면 API 키도, LLM도 없이 HTML/CSS/JS 코드나 URL을 스캔해서 24개 디자인 이슈를 찾아낸다. 결정론적 룰 기반이라 출력이 매번 같고, CI 파이프라인에 그대로 넣을 수 있다.

탐지 범주는 크게 두 가지다:

• AI slop: side-tab border, 보라 그라디언트, bounce easing, dark glow — 모델이 자주 내뱉는 클리셰
• 일반 품질: 줄 길이 초과, 좁은 패딩, 작은 터치 타겟, 헤딩 순서 건너뜀

핵심 동작 원리

CLI는 두 가지 모드로 작동한다.

결정론적 모드 (기본): 정규식과 CSS 파싱으로 27개 룰을 체크한다. LLM 호출 없음.

LLM 크리틱 패스: Claude Code 안에서 /impeccable critique 또는 /impeccable audit 명령어를 쓰면 12개 추가 룰로 의미 수준 검토가 붙는다. 계층 구조, 감성 톤, 접근성 등 정규식으로 잡기 어려운 것들.

두 레이어를 분리한 게 핵심 설계다. CI에는 결정론적 모드, 개발 중에는 LLM 패스.

설치 / 시작 가이드

Claude Code 기준:

# 프로젝트 단위
cp -r dist/claude-code/.claude your-project/

# 전역 설치 (모든 프로젝트에 적용)
cp -r dist/claude-code/.claude/* ~/.claude/

CLI만 먼저 써보고 싶다면 설치 없이:

npx impeccable detect src/                   # 디렉터리 스캔
npx impeccable detect index.html             # HTML 파일 스캔
npx impeccable detect https://example.com    # URL 스캔 (Puppeteer)
npx impeccable detect --fast --json .        # 정규식 전용, JSON 출력

실전 예

시나리오 1 — CI 연동

GitHub Actions에 디자인 lint를 넣는다:

# .github/workflows/design-lint.yml 일부
- name: Design lint
  run: npx impeccable detect --fast --json src/ > design-report.json

--fast 플래그는 Puppeteer 없이 정규식만 쓰는 모드라 CI 환경에서 빠르다. --json 출력으로 결과를 파싱해서 PR 코멘트로 붙이거나 Slack으로 보내는 것도 가능하다.

시나리오 2 — Claude Code 안에서 배포 전 검토

/impeccable polish settings      # 세팅 페이지 최종 패스
/impeccable harden checkout      # 체크아웃 에러 처리 + 엣지케이스
/impeccable audit blog           # 블로그 허브 + 포스트 페이지 기술 검토

/impeccable pin audit 로 자주 쓰는 명령어를 /audit 단축키로 만들 수 있다.

언제 쓰면 안 되는가

CLI 탐지기는 결정론적이라 의도된 예외를 구분하지 못한다. 브랜드 컬러가 보라-파랑 그라디언트인 경우 false positive가 나온다. 룰별로 suppress 옵션이 있는지는 현재 문서에 명시되어 있지 않으므로, 팀 컨벤션과 충돌하는 룰은 사전에 확인이 필요하다.

또한 LLM 크리틱 패스 12개 룰은 Claude Code 세션 안에서만 작동한다. CLI 단독으로는 의미 수준 검토가 안 된다.

디자인 토큰이나 컴포넌트 라이브러리를 처음부터 구축하는 작업에는 /impeccable teach 또는 /impeccable extract 가 더 적합하다. CLI는 기존 코드베이스의 품질 게이트 용도에 맞다.

같은 카테고리 대안 비교

도구	특징	한계
Anthropic frontend-design skill	impeccable의 원본	안티패턴 룰, CLI 없음
Stylelint	CSS 문법/컨벤션 lint	디자인 품질 룰 없음
impeccable	디자인 안티패턴 특화, CLI + 스킬	룰 커스터마이징 제한적

Stylelint와 함께 쓰는 게 자연스럽다. Stylelint가 문법과 컨벤션을 잡고, impeccable이 디자인 품질을 잡는다.

마무리

impeccable의 핵심은 '더 좋은 AI 프롬프트'가 아니라 '코드베이스에 심는 디자인 품질 게이트'다. CLI로 PR마다 결정론적 체크를 걸고, Claude Code 세션에서 /impeccable audit 으로 LLM 패스를 더하면 두 레이어가 서로 다른 것을 잡는다.

AI 생성 UI를 많이 쓰는 팀이라면 CLI 탐지기부터 먼저 돌려보는 게 진입 비용이 낮다. npx impeccable detect src/ 한 번이면 현재 코드베이스에 AI 클리셰가 얼마나 섞여 있는지 바로 보인다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: AI 인사이트
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독