AI가 만든 화면의 ‘티’를 규칙으로 잡는다: pbakaus/impeccable의 디자인 스킬 24개 명령·61개 결정론 검출기·에이전트 훅·Rust 엔진 심층 해부와 박스 실측

Claude Code나 Codex에 “랜딩 페이지 하나 만들어 줘”라고 하면 결과물이 묘하게 닮아 있다. Inter 글꼴, 보라에서 파랑으로 넘어가는 그라데이션, 제목 위의 작은 알약 모양 라벨, 카드 안에 또 카드, 한쪽에만 굵은 색 테두리를 두른 카드. 디자이너들은 이걸 ‘AI 슬롭(slop)’의 티라고 부른다. pbakaus/impeccable은 이 문제를 두 갈래로 다룬다. 하나는 코딩 에이전트에게 디자인 어휘와 절차를 가르치는 스킬(명령 24개)이고, 다른 하나는 LLM 없이 HTML·CSS·JSX와 렌더된 페이지를 검사하는 결정론적 검출기 61개 규칙이다. 둘은 Rust로 짠 단일 엔진 바이너리 위에서 묶이고, 에이전트가 파일을 고칠 때마다 도는 훅으로 이어진다. 오늘(2026-10-22) GitHub Trending Rust 일간 13위(+669)에 올랐다.

이 글은 기능 소개보다 도입 전에 판단할 거리를 다룬다. ① 텍스트 스킬과 Rust 엔진이 어떻게 나뉘는지(16개 크레이트 구조), ② 61개 규칙이 무엇을 잡고 정적 스캔과 브라우저 렌더 스캔이 어떻게 다른지, ③ 훅이 에이전트 문맥에 무엇을 주입하는지, ④ 설치·다운로드 검증·텔레메트리 같은 신뢰 경계를 본다. 그리고 박스(리눅스 x64 VM)에 격리 HOME, DO_NOT_TRACK=1·IMPECCABLE_NO_TELEMETRY=1, API 키 없음 조건으로 엔진 0.1.16 릴리스 바이너리를 받아 저장소 픽스처 227개 스캔, 직접 만든 ‘슬롭’ 페이지와 ‘정돈된’ 페이지의 정적·크롬 렌더·모바일 폭 비교, Claude Code 훅 입력을 흉내 낸 PostToolUse·Stop 훅 실행, 오프라인·온라인 설치를 직접 돌렸다. 수치는 2026-10-22 11:53~12:20 KST 실측이거나 GitHub·npm API와 저장소 문서에서 확인한 값이다.

한눈에 보기: 오늘 기준 스냅숏

무엇이 들어 있나: 스킬·검출기·훅·라이브 모드

README는 출발점을 숨기지 않는다. Anthropic의 frontend-design 스킬이 Claude에서 처음 널리 쓰인 디자인 스킬이었고, Impeccable은 거기서 시작했다고 적는다. 차이는 ‘글로 된 지침’에 ‘기계가 확인하는 규칙’을 붙였다는 데 있다. 모델에게 “Inter 쓰지 마”라고 쓰는 것만으로는 지켜진다는 보장이 없으니, 결과물을 다시 스캔해 어겼는지 확인하는 루프를 만든 것이다.

명령 24개는 네 묶음으로 보면 쉽다

/impeccable pin audit처럼 자주 쓰는 명령을 독립 단축 명령으로 고정할 수도 있다. 실무에서 의미 있는 것은 명령 이름이 곧 팀의 디자인 어휘가 된다는 점이다. “여기 좀 더 예쁘게”가 아니라 “이 섹션 quieter, 그다음 harden”처럼 지시가 짧고 재현 가능해진다.

아키텍처: 텍스트 스킬 + Rust 엔진 하나

원래 Node로 짠 CLI였던 것을 Rust로 다시 짠 결과, 지금 구조는 “스킬 폴더 안의 셸 런처 → 플랫폼별 정적 바이너리”다. 런처(scripts/impeccable, Windows는 impeccable.cmd)는 $IMPECCABLE_BIN → 옆에 놓인 바이너리 → ~/.impeccable/bin → 버전 고정 캐시 → PATH 순으로 엔진을 찾고, 없으면 GitHub 릴리스에서 내려받는다. 이때 .sha256 사이드카와 대조해 맞지 않거나 사이드카를 못 받으면 실행을 거부한다(fail closed). 각 동작의 관찰 가능한 결과는 docs/CLI-CONTRACT.md에 명세되어 있고 tests/oracle/의 골든 파일 1,219개로 바이트 단위까지 고정한다.

위 줄 수는 박스에서 각 크레이트 src/의 .rs 파일을 센 값으로, 합계 약 21만 줄이고 크레이트별 tests/에 약 2만 7천 줄이 더 있다. 디자인 “취향”을 다루는 도구치고는 상당히 무거운 엔지니어링이다. 특히 규칙 로직이 core 한 곳에 있고 정적 엔진(html)과 렌더 엔진(browser), 브라우저 확장(wasm)이 같은 규칙을 어댑터로 감싸 쓰는 구조라, 이론상 세 경로의 판정이 한 레지스트리에서 나온다. 다만 아래 실측에서 보듯 입력으로 받는 정보가 달라서 실제로 잡히는 규칙은 경로마다 다르다.

61개 규칙: ‘슬롭’ 31개와 ‘품질’ 30개

규칙 카탈로그(antipatterns.json)는 두 범주로 나뉜다. slop은 AI 생성 UI의 통계적 습관이고, quality는 사람이 만들었어도 문제인 일반 품질 항목이다. 일부는 advisory로 분류되어 목록에는 나오지만 실패 건수와 종료 코드에는 들어가지 않는다.

정적 스캔과 렌더 스캔은 다른 도구라고 생각하라

설치: 네 가지 경로와 각각이 건드리는 것

# 권장: 프로젝트 루트에서 (감지된 하네스에 스킬+훅 설치)
npx impeccable install                      # 대화형
npx impeccable install -y --providers=claude,codex --scope=project
npx impeccable update                       # 갱신

# 하네스 없이 검출기만
npx impeccable detect src/
npx impeccable detect --json . > findings.json      # CI용
npx impeccable detect https://example.com --viewport 390x844

# 텔레메트리 끄기 (아래 별도 설명)
npx impeccable telemetry off      # 또는 DO_NOT_TRACK=1 / IMPECCABLE_NO_TELEMETRY=1

원격 스킬 ZIP은 설치 전에 Ed25519 서명으로 검증된다(docs/BUNDLE-SIGNING.md). 서명은 ZIP의 SHA-256·바이트 길이·릴리스 버전·아티팩트 이름·키 ID를 묶고, 신뢰 키는 바이너리에 컴파일된 목록뿐이라 서명 파일이 새 키를 끌어들일 수 없다. 박스에서 네트워크를 끊고(unshare -rn) 설치하면 “Could not verify skill bundle … Nothing was installed”로 아무것도 쓰지 않고 멈췄다. 공급망 관점에서는 바람직한 동작이지만, 에어갭 환경에서는 서브모듈이나 수동 복사를 써야 한다는 뜻이기도 하다.

디자인 훅: 편집 직후 ‘즉시 계층’, 턴 끝에 ‘딥 패스’

훅은 이 프로젝트에서 가장 실무적인 부분이다. 규칙은 두 계층으로 나뉜다. 편집마다 도는 즉시 계층은 깨진 이미지, 넘침, 대비·가독성 실패, 그라데이션 글자, 글로 그림자, 디자인 시스템 이탈처럼 기계적이고 애매하지 않은 것만 보고한다. 문구 리듬, 팔레트·글꼴 취향, 배치 리듬은 Stop 이벤트의 딥 패스로 미뤄 세션 동안 건드린 UI 파일 전체에 한 번만 보고한다. 편집마다 취향 지적이 쏟아지면 에이전트가 원래 작업을 잃어버리기 때문이다.

박스에서 슬롭 페이지를 index.html로 둔 임시 git 프로젝트에 Claude·Codex용으로 설치한 뒤, Claude Code가 훅에 넘기는 형태의 JSON(hook_event_name, tool_name: Write, tool_input.file_path)을 표준 입력으로 넣어 런처를 직접 실행했다. 네트워크는 끊은 상태였다.

출력은 {"hookSpecificOutput":{"hookEventName":…,"additionalContext":"[impeccable@1] Design hook findings…"}} 형태로, 발견 사항이 모델 문맥에 직접 주입된다. 지시문은 “진짜 문제면 고치고, 확실한 오탐이나 승인된 예외면 가장 좁은 무시 규칙을 직접 남기고 밝혀라, 그리고 무엇을 고치고 무엇을 남겼는지 답에 적어라”다. Stop 패스는 이번 세션 전부터 있던 문제일 수 있는 항목에 ‘attribution unknown’을 붙여 에이전트가 범위를 넓히지 않도록 한다. 편집 전 기준선(baseline)이 확인된 경우에만 기존 문제를 걸러 낸다. 50ms대 실행이라 편집 루프 지연은 체감하기 어려운 수준이다.

박스 실측

① 공식 픽스처 227개 스캔

3회 반복 실행 시간은 1.14·1.127·1.124초였다(종료 코드 2). 눈여겨볼 점은 기본 실행과 --no-design-system 사이의 차이 1,128건이다. 픽스처 폴더에는 DESIGN.md가 없는데도, 검출기가 상위 디렉터리를 거슬러 올라가 저장소 루트의 DESIGN.md(Impeccable 사이트 자체의 디자인 시스템)를 읽고 픽스처 전체를 그 기준으로 평가했기 때문이다. 모노레포나 하위 폴더 단위로 스캔할 때 엉뚱한 디자인 시스템이 기준이 될 수 있다는 실무 함정이다. 카탈로그 61개 중 정적 스캔에서 한 번도 걸리지 않은 규칙은 15개였고, 대부분 넘침·가려짐·첫 화면 열 넘침·줄바꿈 낙오·스크립트 오류처럼 렌더해야 판단할 수 있는 것들이다.

② 직접 만든 ‘슬롭’ 페이지 vs ‘정돈된’ 페이지

슬롭 페이지에는 일부러 전형적인 티를 넣었다. Inter, 보라→파랑 그라데이션 제목(96px, 자간 −0.06em), 알약 라벨 “✨ Introducing Nimbus 2.0”, 보라 글로 버튼, 튕기는 cubic-bezier 이징, 왼쪽 4px 보라 테두리 카드 3개와 그 안의 중첩 카드, 그라데이션 아이콘 타일, 깜빡이는 초록 점, supercharge·seamless·enterprise-grade 같은 문구와 줄표. 정돈된 페이지는 세리프 본문·68ch 줄 길이·짙은 녹색 버튼 하나·구체적인 문구로 만들었다.

결과는 세 가지로 요약된다. 첫째, 슬롭은 확실히 잡는다. 정적 18건, 렌더 22건으로 의도한 티 대부분이 걸렸고, 대비 계산은 “2.2:1 (need 4.5:1) — text #6b7280 on #452f7a”처럼 그라데이션 배경의 대표색까지 풀어 근거를 댔다. 둘째, 정적과 렌더가 잡는 규칙이 다르다. 중첩 카드·튕기는 이징·줄바꿈 낙오는 렌더에서만, 과다 사용 글꼴·마케팅 상투어·색 배경 위 회색은 정적에서만 나왔다. 렌더 스캔에서 Inter가 빠진 것은 박스에 Inter가 설치되어 있지 않아 대체 글꼴로 계산된 영향으로 보인다(추정). 모바일 폭(390×844)에서는 96px 제목이 text-overflow로 새로 걸렸다. 셋째, 정돈된 페이지도 크림 배경(#f6f4ef) 하나로 cream-palette 경고를 받아 종료 코드 2였다. 이걸 CI 게이트로 그대로 쓰면 의도한 브랜드 선택도 실패로 처리되니 무시 규칙 운영이 필수다. 렌더 스캔 시간은 슬롭 4,673ms, 정돈 2,470ms였다.

반대로 놓친 것도 있다. 아이콘 타일(icon-tile-stack), 거대한 h1(oversized-h1), 짓눌린 자간(extreme-negative-tracking), 줄표 남발(em-dash-overuse)은 어느 경로에서도 걸리지 않았다. 규칙마다 임계값이 있어(예: 줄표는 일정 밀도 이상) 짧은 데모 페이지에서는 조건을 채우지 못했을 수 있다. “검출기가 조용하다 = 슬롭이 없다”가 아니라는 점은 README도 “깨끗한 결과는 증거이지 증명이 아니다”라고 적어 두었다.

③ 문서와 릴리스의 어긋남, 그리고 표준 입력

README는 detect --list-rules(규칙 카탈로그 출력)와 --github(GitHub Actions 주석) 옵션을 안내하지만, 현재 릴리스 엔진 0.1.16의 detect --help에는 둘 다 없다. 커밋 기록을 보면 두 기능은 각각 2026-10-22 04:43 KST, 05:47 KST에 main에 들어갔고, 엔진 0.1.16은 그보다 앞선 2026-10-20 02:30 KST에 나왔다. 즉 README가 다음 릴리스를 앞서 설명하는 상태다. 또 0.1.16에서 대상 없이 --list-rules를 주고 표준 입력을 열어 두면 엔진이 표준 입력을 기다리며 멈췄다. 스크립트나 CI에서 부를 때는 </dev/null로 표준 입력을 닫거나 대상을 명시하는 습관이 안전하다.

텔레메트리와 네트워크 표면

박스에서 impeccable telemetry status는 “telemetry: off (DO_NOT_TRACK is set). Rolls still work; the roll API is told not to record them”을 출력했다. 핵심은 검출기와 훅은 오프라인에서도 완결되고, 서버 통신은 설치·갱신과 ‘새 디자인 방향 고르기’ 흐름에 몰려 있다는 점이다. 사내 정책상 외부 통신이 민감하다면 검출기 중심으로 쓰고 "telemetry": false를 프로젝트 .impeccable/config.json에 커밋해 팀 전체를 끄는 방법이 문서화되어 있다.

보안·운영 체크포인트

비슷한 도구와 비교

현실적인 조합은 axe-core 같은 접근성 엔진을 기준선으로 두고, Impeccable 검출기를 ‘AI 습관 린터’로 얹는 것이다. 대비·제목 단계는 둘이 겹치므로 CI에서 두 번 실패하지 않게 한쪽을 advisory로 내리는 정리가 필요하다.

도입 판단: 이런 팀에 맞고, 이렇게 시작하라

# 1) 먼저 검출기만: 현재 상태를 기록
npx impeccable detect --json --no-design-system src/ > baseline.json </dev/null

# 2) 의도한 선택은 예외로 남기기
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-file "src/legacy/**"

# 3) 렌더 기준으로 한 번 더 (모바일 폭 포함)
npx impeccable detect http://localhost:3000 --viewport 390x844

# 4) 에이전트 훅 설치 (Codex는 이후 /hooks 에서 승인)
npx impeccable install -y --providers=claude,codex --scope=project

정리하면 Impeccable의 가치는 “AI가 디자인을 잘하게 만든다”는 큰 약속보다 “AI가 반복하는 실수를 기계적으로 짚어 다시 고치게 만든다”는 좁고 검증 가능한 루프에 있다. 박스 실측에서 그 루프는 빠르고(훅 50ms대, 픽스처 227개 1.1초) 오프라인에서도 돌았으며, 서명·해시 검증도 실패하면 멈추는 쪽으로 짜여 있었다. 반면 규칙의 상당수는 의견이고, 정적·렌더 경로가 서로 다른 것을 잡으며, 상위 DESIGN.md를 끌어오는 동작과 문서–릴리스 어긋남 같은 운영상의 모서리가 있다. 도입한다면 검출기를 먼저 기록용으로 돌려 팀의 예외 목록을 만든 뒤 훅과 게이트로 넓히는 순서를 권한다.