AI가 만든 화면의 뻔한 티를 62가지 규칙으로 잡는다, 별 8만 8천 개 Impeccable

frontend-design 스킬은 모델에게 “뻔한 디자인으로 몰리지 마라”고 말해 두는 지침 문서이고, Impeccable은 거기에 그 말이 지켜졌는지 코드에서 직접 세어 보는 62개 규칙을 얹은 도구입니다. 지침은 모델의 기분에 따라 읽히지만 규칙은 편집할 때마다 같은 방식으로 돕니다. AI에게 랜딩 페이지를 맡기면 어느 프로젝트에서나 모든 글자는 Inter, 배경은 보라에서 파랑으로 가는 그라데이션, 카드 안에 또 카드, 제목마다 둥근 사각형 아이콘이 나오는데, 이런 흔적을 “AI가 만든 티”로 규정하고 잡아내는 것이 이 프로젝트의 일입니다.

GitHub의 pbakaus/impeccable은 2026-10-27 UTC 기준 별 88,889개, 포크 5.3k, 커밋 2,574개이고 보관(archived) 상태가 아닌 Apache-2.0 오픈소스입니다. 저장소는 2025년 11월 16일에 만들어졌고 제작자는 Paul Bakaus로 README에 적혀 있습니다. 이 글은 소개 대신 부품을 뜯어 보는 순서로 갑니다. 설치가 프로젝트에 놓는 겹을 바깥부터 한 겹씩 벗기고, 규칙이 도는 세 가지 방식과 훅이 에이전트에게 말을 거는 시점, 밖으로 나가는 요청까지 확인하면 설치할지, 훅을 켤지를 스스로 정할 수 있습니다.

설치 한 줄이 프로젝트에 놓는 네 겹

프로젝트 루트에서 설치기를 부르면 시작됩니다. 설치기는 ~/.claude, ~/.codex, ~/.grok, 프로젝트의 .cursor 같은 에이전트 폴더를 찾아 어느 도구에 넣을지, 이 프로젝트에만 넣을지 전역에 넣을지 묻습니다. 스크립트에서 돌릴 때는 --providers=claude,cursor, --scope=project|global로 질문을 건너뜁니다.

npx impeccable install    # 도구와 범위를 고르고, 훅 설치 여부에 답한다
npx impeccable update     # 갱신

설치 길은 여러 개입니다. Claude Code에서는 /plugin marketplace add pbakaus/impeccable 뒤에 /plugin에서 골라 넣을 수 있고, 팀이 버전을 고정하고 싶다면 깃 서브모듈로 .impeccable에 넣고 npx impeccable link --source=.impeccable --providers=claude,cursor로 도구 폴더에 연결합니다. Grok Build에는 grok plugin install pbakaus/impeccable#plugin --trust가 따로 있습니다. VS Code의 GitHub Copilot에는 renaissance-geek.impeccable 확장이 있는데, 이쪽은 스킬만 넣고 자동 훅은 설치하지 않습니다. 어느 길이든 설치 뒤에는 에이전트를 다시 불러와야 새 스킬이 보입니다. 훅을 지원하는 도구(Claude Code, Cursor, Codex, GitHub Copilot, Grok Build)에서는 설치기가 훅의 역할을 설명하고 설치할지 묻습니다. 기본값은 예이고, 고른 답은 커밋되지 않는 .impeccable/config.local.json에 기억되어 다음에 다시 묻지 않습니다.

설치가 끝나면 첫 실행은 /impeccable init입니다. 프로젝트를 먼저 읽고 비어 있는 사실만 물어 PRODUCT.md를 씁니다. 이 파일은 사람이 고쳐도 되므로 추측이 틀렸다면 직접 바로잡습니다. 설정이 낡았다는 느낌이 들면 /impeccable doctor가 훅 경로와 설정 키, 오래된 파일 형식을 점검합니다.

이렇게 놓인 것들은 네 겹으로 나뉩니다. 바깥에서 안으로, 이 글의 목차도 이 순서입니다.

• 명령 층/impeccable 하나에 하위 명령 24개. 대상을 뒤에 붙여 범위를 좁히고, 자주 쓰는 명령은 pin으로 단축 명령화
• 맥락 기록 층PRODUCT.md(누구를 위한 제품인가), DESIGN.md(시각 체계), .impeccable/surfaces/*.md(화면별 브리프)
• 탐지 엔진 층스킬 옆에 두거나 첫 실행에 ~/.impeccable/bin/으로 내려받는 자체 완결형 바이너리. 스킬과 훅에는 Node가 필요 없고 npx 설치기만 Node 18.19 이상을 쓴다
• 연결 층도구별 훅 설정 파일, 터미널의 detect CLI, 렌더된 페이지를 검사하는 브라우저 확장

바깥 겹: 명령 24개를 용도로 묶기

README의 표를 용도로 묶으면 24개가 한 장에 들어옵니다. 대부분 “이미 있는 화면을 어느 방향으로 손볼까”를 이름으로 고르는 명령이라, 이름을 몰라도 “이 히어로 영역을 다시 만들어 줘”처럼 말해도 됩니다.

하고 싶은 일	명령
만들기 전에 설계	shape(구현 없이 설계 브리프까지), craft(설계에서 구현, 시각 반복까지)
맥락 기록	init(PRODUCT.md), document(DESIGN.md), extract(반복되는 UI를 공용 컴포넌트·토큰으로)
점검	critique(위계·명확성·분위기 리뷰), audit(접근성·성능·반응형), harden(오류 처리·i18n·글자 넘침)
방향 조절	bolder, quieter, distill(본질만 남기기), overdrive(기술적으로 야심찬 효과), delight
부분 손질	typeset, layout, colorize, animate, clarify(문구), adapt(기기별), optimize, onboard(첫 실행·빈 화면)
마무리	polish(디자인 체계 정렬과 출시 준비)
브라우저에서 반복	live(요소를 집어 변형 비교), generate(이름 붙인 요소의 변형 생성)

대상을 뒤에 붙이면 범위가 좁아집니다. /impeccable audit blog는 블로그 목록과 글 페이지를, /impeccable polish settings는 설정 화면을 다룹니다. /impeccable pin audit을 해 두면 이후 /audit으로 부를 수 있습니다.

같은 명령이라도 화면이 무슨 일을 하는 곳이냐에 따라 접근이 달라집니다. 명령은 대상 화면의 목적을 읽어 네 가지 성격 중 하나로 정하고 그 결과를 해당 화면의 브리프에 적습니다. 방문자를 결정하게 만드는 랜딩·요금 페이지는 Persuade, 과업을 끝내려는 대시보드·설정·편집기는 Operate, 문서·가이드는 Read, 포트폴리오·갤러리처럼 작품을 둘러보는 곳은 Experience입니다. 개발자 도구의 랜딩은 Persuade이고 같은 제품의 문서는 Read가 되는 식이라 한 제품 안에서도 성격이 갈리고, 목적이 애매하면 방문자가 거기서 무엇을 해야 하는지 말해 주면 됩니다.

새 화면을 처음부터 만들 때는 경로가 한 번 갈립니다. 이미지 생성이 가능한 도구에서는 목업을 먼저 만들고 그에 맞춰 짓는 comp가 기본이고, 코드로 바로 짓는 code도 있습니다. comp는 코딩 모델이 평소 만들던 범위를 넘는 대담한 구성을 노릴 수 있는 대신 이미지에서 코드로 옮기며 세부가 달라져 몇 번의 검토가 필요하고 시간이 더 듭니다. code는 첫 구현이 정돈되어 나오지만 모델의 자연스러운 범위 안이라 덜 야심차게 끝나기 쉽습니다. 앱 화면과 문서는 두 경로 모두 코드 먼저로 짓습니다. 선택은 .impeccable/config.json의 buildPath에 "comp" 또는 "code"로 저장되고, 이미지 생성이 없는 도구에서 팀 설정을 내 컴퓨터에서만 덮으려면 커밋되지 않는 config.local.json에 씁니다.

가운데 겹: 파일로 남는 맥락과 git에 넣을 것

명령을 아무리 늘려도 매번 같은 질문을 되풀이하면 소용이 없으니, 이 도구는 맥락을 파일로 남깁니다. PRODUCT.md는 누가 쓰고 무엇을 하는 제품인지, 말투와 제약이 무엇인지 같은 오래 가는 사실만 적고 시각 방향은 적지 않습니다. DESIGN.md는 이미 굳어진 화면의 글꼴·색·모서리 둥글기를 document 명령이 기존 코드에서 읽어 기록하는 곳입니다. 화면별 브리프인 .impeccable/surfaces/*.md에는 그 화면의 성격(앞의 네 모드)과 방향이 들어갑니다. 지침 문서가 “분위기를 정하라”고만 하던 자리를 이 세 파일이 채우는 셈이고, 규칙 검사기도 DESIGN.md가 있으면 그 안의 글꼴·색·반경·글자 크기를 기준으로 “문서에 없는 값”을 찾습니다.

문제는 이 파일들이 .impeccable/ 폴더에 다른 부산물과 섞여 쌓인다는 점입니다. 실행하면 비평·마감 스크린샷, 라이브 모드의 세션과 미리보기, 캐시, 개인별 설정이 생기는데, README는 임시 파일은 .gitignore에 넣고 공유할 산출물은 남기라고 안내합니다.

# impeccable-ignore-start
**/.impeccable/config.local.json
**/.impeccable/hook.cache.json
**/.impeccable/hook.pending.json
**/.impeccable/*.png
**/.impeccable/review/
**/.impeccable/live/server.json
**/.impeccable/live/sessions/
# ...README에는 live 하위 항목이 더 이어진다
# impeccable-ignore-end

커밋 대상으로 남길 것은 config.json, live/config.json, design.json, surfaces/*.md, critique/*.md입니다. 임시 파일을 이미 커밋해 버렸다면 .gitignore를 추가해도 추적이 끊기지 않으므로 git rm --cached <경로>를 따로 실행합니다. 결정 라운드가 만드는 questions/와 mocks/worlds/ 폴더는 스스로 .gitignore를 들고 있어서 위 블록이 없는 프로젝트에서도 새 파일이 커밋에 끼지 않습니다.

엔진 한 개, 입구 세 개, 눈 세 종류

가장 안쪽의 엔진은 자체 완결형 바이너리 하나이고, 훅·CLI·브라우저 확장이 모두 같은 규칙을 이 엔진으로 돌립니다. 사이트의 규칙 카탈로그는 규칙마다 “AI 슬롭”(AI가 습관처럼 만드는 티)인지 “품질”(쓰기 어렵게 만드는 문제)인지, 그리고 어떤 눈으로 보는지를 표시합니다. 눈은 세 종류입니다. 소스 코드의 CSS와 마크업을 읽는 눈, 실제로 그려진 페이지의 레이아웃을 재는 눈, 모델이 목적을 읽고 판단하는 설계 리뷰입니다.

아래 그림은 입구가 어느 눈으로 이어지고 어느 쪽이 LLM 없이 도는지 보여 줍니다. 위쪽 초록 영역의 두 눈은 모델도 API 키도 쓰지 않습니다.

그림 1. 입구 세 개가 눈 세 종류로 갈린다. 카탈로그 항목의 눈 구분은 사이트 카탈로그 페이지에 나열된 67개를 편집부가 센 값

같은 문제라도 어디서 보이느냐가 다르기 때문에 눈을 나눈 것입니다. 글꼴 이름과 그라데이션 글자는 CSS만 읽어도 알지만, 글이 상자 밖으로 넘치거나 메뉴가 잘리거나 줄이 너무 긴 것은 실제로 그려 봐야 알고, “같은 카드가 줄줄이 반복된다”는 인상은 화면의 목적을 아는 눈이 필요합니다. 그래서 카탈로그에 나열된 67개 가운데 소스가 50개, 브라우저가 11개이고 설계 리뷰가 6개입니다. 사이트 카탈로그의 총계 표기는 탐지기 62개에 설계 리뷰 6개를 더한 68개입니다.

카탈로그 67칸의 분포

카탈로그는 아홉 묶음으로 정리되어 있습니다. 칸이 가장 두꺼운 곳은 글자(13개)와 레이아웃(12개)이고, 이름 붙은 디자인 시스템 검사는 4개로 가장 얇은 축에 듭니다.

그림 2. 묶음별 항목 수(사이트 카탈로그 페이지 기준, 편집부 집계)

묶음마다 무엇을 보는지는 대표 규칙을 보면 감이 옵니다. 이름은 카탈로그의 표기를 풀어 쓴 것입니다.

묶음	눈에 띄는 규칙
타이포그래피	흔한 글꼴(Inter 등), 제목 위 작은 라벨, 제목 위 배지, 한 단어만 남은 마지막 줄, 꼬리 줄이 짧은 제목, 뭉개진 자간, 본문 전체를 대문자로 쓴 글
레이아웃과 여백	카드 속 카드, 단조로운 여백, 상자 밖으로 넘친 내용, 잘린 메뉴·팝오버, 너무 긴 줄, 다른 요소에 가려진 글자
색과 대비	보라 그라데이션과 AI 팔레트, 그라데이션 글자, 어두운 배경의 빛나는 강조색, 반사적으로 고른 크림·베이지, 색 배경 위 회색 글자
시각 세부	한쪽만 굵은 옆 테두리, 장식용 격자, 1px 테두리에 넓은 그림자를 겹친 카드
모션	바운스·탄성 이징, 맥동하는 상태 점, 자동으로 흐르는 로고 줄, 장식용 깜박이는 커서
문구	문장마다 낀 줄표, “supercharge” 같은 일반 홍보 문구, 슬로건처럼 반복되는 강제 대비
이미지	자리표시 같은 도형 일러스트, 거의 불투명한 오버레이에 가린 이미지, 깨진 src
일반 품질	로드 때 JS 오류, WCAG AA에 못 미치는 대비, 건너뛴 제목 단계, 지나치게 작은 본문
디자인 시스템	DESIGN.md에 없는 글꼴·색·반경·글자 크기

설계 리뷰 쪽 여섯 항목은 코드로 못 잡아 critique가 맡는 패턴입니다. 어디에나 깔린 유리 효과, 카드에 과하게 준 둥근 모서리, 거친 SVG 일러스트, 글꼴 하나로 전부 해결하기, 히어로의 큰 숫자 배치, 똑같은 카드 격자가 거기 들어갑니다. 이 중 마지막 둘은 소스 몇 줄로 판정할 수 없는 “느낌”에 가까워서 모델의 눈에 맡긴다는 것이 이 도구의 분업 방식입니다. 한 가지 더, v4.7.0은 타이포그래피에 straggler와 unbalanced-heading 검사를 추가해 마지막 줄에 단어 하나만 남는 문단과 꼬리가 짧은 제목도 걸러 냅니다.

detect 한 번 돌렸을 때 나오는 것

설치한 에이전트 없이 규칙만 돌리는 길이 detect입니다. 모두 읽기 전용 점검이라 소스를 고치지 않습니다.

npx impeccable detect src/                               # 폴더의 코드와 스타일
npx impeccable detect http://localhost:3000              # 렌더된 페이지(Chrome·Chromium·Edge 필요)
npx impeccable detect --viewport 390x844 http://localhost:3000   # 모바일 폭으로
npx impeccable detect --scope type,layout src/           # 타이포·레이아웃 규칙만
npx impeccable detect --json src/ > findings.json        # 스크립트·CI용
npx impeccable detect --list-rules                       # 규칙 목록만(스캔 안 함)

폴더를 대상으로 하면 지원하는 UI·스타일 파일(.tsx, .jsx, .html, .vue, .svelte, .astro, .css, .scss 등)을 찾고, 서버 템플릿(Blade, ERB 등)은 detector.extensions에 확장자를 적으면 포함됩니다. 주소를 주면 렌더된 DOM과 계산된 레이아웃, 접근 가능한 스타일시트를 보지만 다른 출처의 CSS는 CORS 허용이 없으면 브라우저 보안상 읽지 못하고, 소스에는 아무것도 쓰지 않습니다. 사람이 읽는 결과는 표준 오류로, JSON은 표준 출력으로 나옵니다.

아래 터미널은 공식 문서가 실제 스캔에서 가져온 결과 한 건의 모양, 종료 코드, 예외 한 줄을 이어 붙인 것입니다. 결과 한 건은 규칙 이름과 줄 번호, 그 줄의 문제 조건으로 이뤄지고, 문서의 카드에는 어떻게 다시 생각해 볼지 안내가 붙습니다.

그림 3. 결과 한 건과 종료 코드. 출력 모양은 공식 detector 문서의 예시를 따랐다

종료 코드로 자동화에 연결합니다.

종료 코드	뜻
0	스캔이 끝났고 주된 문제 없음(조언은 있을 수 있음)
2	스캔이 끝났고 주된 문제 있음
1	대상 중 하나 이상을 스캔하지 못함. 일부 대상에서 문제가 나왔어도 실패로 취급

조언(advisory)은 따로 센 참고 의견이라 스캔을 실패로 만들지 않습니다. 4px 이상 밀린 선명한 그림자는 의도된 네오브루탈리즘일 수 있어서 v4.7.1부터 실패가 아닌 조언으로 나오고, 그 요소에 data-impeccable-ignore="hard-offset-shadow"를 달면 조용해집니다. 문서가 스스로 강조하듯 깨끗하게 끝난 스캔은 증거일 뿐 시각·접근성 품질의 증명이 아니므로, 여러 폭에서 실제 화면을 열어 보는 일은 남습니다.

팀 저장소에서는 풀 리퀘스트마다 npx impeccable detect --github src/를 GitHub Actions에서 돌리면 문제가 원인이 된 줄에 주석으로 달립니다. 다만 GitHub는 한 단계에 종류별 10개, 한 작업에 50개까지만 주석으로 보여 주고 나머지는 로그에 남으며, HTML 엔진의 결과는 줄 번호가 없을 수 있어 파일에 주석이 붙습니다. 브랜드 글꼴이 Inter라서 계속 걸린다면 규칙 전체를 끄지 말고 값만 예외로 적습니다(그림 3의 마지막 명령). 예외는 기본적으로 커밋되는 .impeccable/config.json에 들어가 팀 전체에 적용되고, --local을 붙이면 커밋되지 않는 config.local.json에만 들어갑니다. 파일 하나에만 적용하려면 --file로 좁히거나 파일 안에 impeccable-disable 주석을 남기며, 이 주석의 이유는 사람이 읽으라고 쓰는 것이고 스캐너는 버립니다. 규칙 무시 설정은 수동 스캔과 훅이 같이 읽고, 훅을 끄는 것은 수동 스캔에 영향을 주지 않습니다.

데스크톱 앱도 길이 있습니다. v4.7.0부터 디버깅 포트를 연 Electron, NW.js, CEF, WebView2 앱을 npx impeccable detect --cdp 9222로 검사하며, 지금 열려 있는 창을 건드리지 않고 읽고 창이 여럿이면 --target으로 고릅니다. 운영 중인 웹 사이트는 주소를 주거나 브라우저 확장을 쓰는 쪽이고, 라이브 모드를 운영 사이트에 주입하는 것은 지원하지 않습니다.

규칙 밖은 audit과 critique의 몫

탐지기는 “이 줄이 규칙에 걸린다”까지만 말합니다. 그 바깥은 두 명령이 나눠 맡습니다. audit은 접근성·성능·테마·반응형·구현 일관성 다섯 영역을 영역마다 0~4점으로 매겨 합 20점 만점의 보고서를 쓰고 코드는 고치지 않습니다. 공식 문서가 보여 주는 한 줄은 이런 모양입니다.

/impeccable audit the checkout flow
P1 · 결제 버튼에 눈에 보이는 키보드 초점 표시가 없음. 탭으로 닿지만 선택됐다는 표시가 없다.

위 두 번째 줄은 문서의 보고서 형식을 한국어로 옮긴 예시 문장입니다. 보고서의 등급은 이렇게 읽습니다.

등급	뜻	고치는 때
P0 · 막힘	누군가 과업을 끝낼 수 없음	바로
P1 · 중대	큰 불편이나 접근성 실패	출시 전
P2 · 사소	우회할 길이 있는 문제	다음 개선 때
P3 · 다듬기	사용에 거의 영향 없는 작은 점	위가 끝난 뒤

점수가 높아도 막힘 하나가 숨어 있을 수 있어서 합계보다 개별 항목을 읽으라는 것이 문서의 안내입니다. critique는 반대로 화면이 의뢰서의 목적에 맞는지, 위계가 약하지는 않은지, 어떤 분위기를 주는지를 판단하고 보고서를 .impeccable/critique/에 저장합니다. 이어지는 polish는 거기 적힌 우선순위를 이어받습니다.

그래서 출시 전날 결제 화면을 다룬다면 이런 순서가 됩니다. 화면이 왠지 밋밋한데 이유를 모르겠으면 critique, 막힘과 접근성은 audit, 빠진 상태와 예외는 harden, 느림은 optimize, 마지막 정리는 polish, 그리고 고친 뒤 audit을 다시 돌려 확인합니다. 순서는 편집부가 공식 문서의 명령 설명을 이어 붙여 만든 예이고, 규칙 62개는 이 흐름 어디서든 편집 때마다 뒤에서 돕니다.

훅은 편집 직후와 턴 끝, 언제 말하나

훅은 에이전트가 UI 파일을 고칠 때 탐지기를 돌려 결과를 에이전트의 작업 흐름으로 돌려보내는 연결 층입니다. 에이전트가 방금 쓴 코드를 아직 기억할 때 문제를 알려 주는 것이 핵심이고, 도구마다 말을 거는 시점이 다릅니다. 한 번의 턴 안에서 편집이 세 번 일어났다고 놓고 보면 이렇게 갈립니다.

그림 4. 파란 점과 초록 점은 에이전트에게 닿는 시점, 속이 빈 점은 스캔만 하고 턴이 끝날 때까지 쥐고 있는 시점

Claude Code와 Codex는 편집 직후에 즉시 눈에 띄는 문제(깨진 이미지, 넘침, 가독성, 그라데이션 글자, 글로우, 디자인 시스템 이탈)만 빠르게 알리고, 에이전트가 응답을 마치는 순간 그 세션에서 만진 파일 전체를 더 넓은 규칙으로 봅니다. 한창 만드는 중에 매번 잔소리를 하지 않으려는 설계이고, 편집마다 전체 규칙이 필요하면 hook.perEditRules를 "all"로 바꿉니다. Cursor와 Copilot은 편집 뒤에 전체 규칙을 돌립니다. Grok Build는 편집 중에 스캔해 두기만 하고 결과는 턴이 끝날 때 한 번에 전달합니다. Cursor는 v3.6.0 때 제안된 쓰기를 반영 전에 검토하는 방식이었지만 README와 v4.7.1 변경 기록은 쓴 직후 검사하는 방식으로 옮겼다고 적고, 이전 설정은 npx impeccable update가 새 방식으로 옮겨 줍니다.

턴 끝의 넓은 검사는 같은 말을 되풀이하지 않도록 이미 보고한 것을 거릅니다. 한 가지 더 있습니다. 편집 전의 기준선이 확인될 때(현재 Claude의 Edit·Write 결과를 쓰는 텍스트 스캔) 이미 있던 문제는 숨기고, 그 외의 결과에는 새 문제인지 출처를 모르는 문제인지가 표시됩니다. 출처를 모른다는 표시가 곧 이번 세션이 만든 문제라는 뜻은 아니라는 것이 README의 설명입니다.

훅이 놓이는 곳과 신뢰 절차는 도구마다 다릅니다.

도구	설정 위치	켜기 전에 할 일
Claude Code	.claude/settings.local.json(커밋되지 않는 로컬 설정)	작업 폴더 신뢰 수락 후 /hooks에서 PostToolUse·Stop 훅 확인
GitHub Copilot	.github/hooks/impeccable.json(커밋되어 팀 공유)	기본 브랜치에 올라가야 Copilot CLI와 클라우드 에이전트가 사용
Cursor	.cursor/hooks.json	파일이 바뀌면 다시 읽음
Codex	.codex/hooks.json	설치 뒤 /hooks에서 한 번 승인, 정의가 바뀌는 업데이트 뒤 다시 승인
Grok Build	.grok/hooks/impeccable.json	/hooks-trust 또는 --trust 없이는 실행되지 않음

상태는 /impeccable hooks status로 보고 /impeccable hooks on, /impeccable hooks off로 켜고 끕니다. 아무 말이 없다고 문제가 없다는 뜻은 아닙니다. 깨끗한 편집이거나, 조용한 모드이거나, 훅이 꺼져 있을 수 있어서 /impeccable doctor가 훅 스크립트 경로와 설치 상태·켜짐 상태의 불일치를 찾아 줍니다. 훅은 웹 코드만 검사하고 PRODUCT.md가 ios·android·adaptive를 선언한 프로젝트는 건너뜁니다. 디버깅이 필요하면 .impeccable/config.json의 hook.auditLog에 경로를 적어 호출마다 한 줄씩 기록을 남길 수 있습니다.

훅을 켜기 전에 읽을 것. Claude Code에서 설치된 훅 명령은 모델의 도구 승인과 별개로 실행됩니다. 그래서 첫 편집이나 종료 시점에 엔진 바이너리를 내려받아 ~/.impeccable/bin/에 둘 수 있고, 세션에서 모델의 명령을 거부했어도 마찬가지라고 README가 밝힙니다. 무인으로 돌리기 전에 훅 내용을 읽어 보고, 끄려면 /impeccable hooks off나 환경 변수 IMPECCABLE_HOOK_DISABLED, 설치 때 --no-hooks를 씁니다. Claude Code는 한 번의 실행만 --settings '{"disableAllHooks": true}'로 모든 훅을 끌 수도 있습니다.

밖으로 나가는 요청 네 가지와 로컬에 쌓이는 것

프로젝트 파일과 검사 결과는 Impeccable 서버에 올라가지 않는다고 개인정보 처리방침에 적혀 있습니다. 탐지기와 훅은 로컬에서 돌고 결과를 에이전트에게만 돌려주며, 코딩 도구가 AI 제공사로 보내는 프롬프트와 파일은 그 도구의 설정과 약관을 따릅니다. 바깥으로 나가는 것은 네 가지입니다.

1. 하루에 한 번 정도의 새 버전 확인. IMPECCABLE_NO_UPDATE_CHECK=1로 끕니다.
2. 새 디자인을 시작할 때 impeccable.style의 롤 API에 “시각 세계” 후보를 달라는 요청. 이것이 기능 자체라서 끌 수 없습니다.
3. 어떤 후보가 보였고 무엇이 선택됐는지에 대한 익명 기록. 끌 수 있습니다.
4. 설치와 엔진 내려받기. npm이나 GitHub에서 받습니다.

선택 기록은 무작위 롤 키, 후보의 종류와 위치, 버전, 선택이 결정 화면에서 나왔는지 에이전트에게서 나왔는지 같은 값으로 이뤄지고 프로젝트 이름·파일·코드·PRODUCT.md, 에이전트가 지은 방향 이름은 보내지 않는다고 합니다. 커밋되는 화면 브리프에는 롤 키 자체가 아니라 ~/.impeccable/seed-salt의 임의 값을 섞은 해시만 남습니다. 서버는 IP 주소나 기기 식별자를 기록하지 않는다고 밝히지만 이 기록에는 고정된 삭제 기한이 없고, 개인을 식별하지 않아 한 사람의 기록만 찾아 지울 수는 없다고 처리방침에 적혀 있습니다. 끄는 방법은 npx impeccable telemetry off, DO_NOT_TRACK=1, IMPECCABLE_NO_TELEMETRY=1 중 하나이고, 팀 전체는 .impeccable/config.json에 "telemetry": false를 적으며 npx impeccable telemetry status로 현재 상태를 봅니다. v4.6.0부터는 끈 상태에서 롤 요청에도 기록하지 말라고 서버에 알립니다. 후보 요청과 미리보기 이미지는 기능에 필요해서 꺼도 여전히 나갑니다.

라이브 모드와 이미지 생성에는 비용과 권한이 따로 붙습니다. 라이브 모드는 베타이고 로컬 개발 서버나 정적 HTML을 고치는 기능이라 배포된 운영 사이트에는 쓰지 못합니다. 카피 수정을 적용할 때 package.json의 선택 스크립트 impeccable:manual-edit-validate를 사용자 권한으로 실행하므로 낯선 저장소에서는 그 스크립트부터 읽어야 합니다. 목업 경로의 이미지 생성은 Codex나 Cursor처럼 도구에 내장된 생성기가 있으면 그것을 쓰고, 없으면 OPENAI_API_KEY를 쓰는 대체 경로가 열려 OpenAI API 프로젝트에 요금이 따로 붙습니다. 키는 채팅이나 설정 파일이 아니라 에이전트의 환경에 둡니다. 도구 자체는 무료입니다. 비용은 코딩 도구와 모델의 사용료, 그리고 이 이미지 생성에서만 생깁니다.

frontend-design에서 v4.7.1까지, 그리고 검사만 쓰는 길

이 겹겹의 구조는 한 번에 만들어지지 않았습니다. README는 출발점을 Anthropic의 frontend-design 스킬이라고 밝힙니다. 그 SKILL.md에는 색·글꼴·레이아웃을 담은 설계 계획을 먼저 쓰고, 그 계획이 어느 주제에나 나올 법한 기본값은 아닌지 검토한 뒤 코드를 쓰고, 만들면서 자기 작품을 비평하라는 흐름이 적혀 있습니다. 요즘 AI 디자인이 몰리는 모양으로 크림 배경에 세리프 제목과 테라코타 강조색, 검정 배경에 형광 한 가지 강조색, 신문 같은 줄과 단, 같은 둥근 카드와 같은 그림자의 SaaS 카드 묶음, 어떤 주제에나 붙는 대문자 라벨을 꼽아 두기도 합니다. Impeccable은 이 위에 맥락 파일과 검사기를 쌓았고, 변경 기록의 날짜(스킬 버전 기준)로는 이렇게 자랐습니다.

날짜	버전	바뀐 것
4월 8일	v2.0	스킬 이름이 frontend-design에서 impeccable로 바뀌고 평가를 기준으로 다시 쓰임
4월 9일	v2.1	명령이 21개에서 18개로 정리됨(이후 다시 늘어 지금은 24개)
6월 14일	v3.6.0	에이전트가 편집하는 도중에 돕는 프로젝트 훅(Claude·Codex·Cursor)
7월 21일	v4.0.0	디자인 방향을 모델의 첫 아이디어가 아니라 바깥 씨앗으로 뽑는 롤 방식, 당시 탐지기 규칙 58개
9월 4일	v4.2.0	Node 런타임 대신 자체 완결형 엔진 하나로 통일
10월 15일	v4.6.0	통계 전송을 끄면 롤 기록도 남기지 말라고 요청, Oh My Pi 지원
10월 20일	v4.7.0	실행 중인 데스크톱 앱 검사(--cdp), straggler·unbalanced-heading 추가
10월 23일	v4.7.1	detect --github 주석 출력과 --list-rules, 엔진 0.1.17 포함

롤 방식이 들어온 까닭은 v4.0.0 변경 기록의 측정에 있습니다. 창의적으로 만들어 달라는 요청을 열여섯 가지 말로 바꿔 물었더니 35개 답 중 30개가 같은 콘셉트로 돌아왔다는 프로젝트 자체의 측정이고, 부족한 것은 창의성이 아니라 변주라고 보아 방향을 모델 자신의 순위가 아니라 바깥의 무작위 씨앗으로 뽑게 했습니다. 직접 검토한 360개 가운데 188개가 승인된 시각 세계로 카탈로그에 들어 있고, 모델이 프로젝트에서 도출한 방향 옆에 도전자 여섯 개가 놓여 도전자가 이길 때만 빌드를 가져갑니다.

부담이 큰 순서로 보면 입구가 셋 있습니다. 가장 가벼운 입구는 설치 없이 npx impeccable detect src/만 돌려 지금 프로젝트에서 몇 건이 나오는지 보는 것입니다. 지침은 포기하는 대신 에이전트도 훅도 통신도 없고 결과는 매번 같은 방식으로 나옵니다. 그 위에는 Anthropic의 frontend-design처럼 지침 문서만 넣는 길이 있고, 가장 위에 맥락 파일과 24개 명령, 편집 때마다 도는 규칙, 훅까지 모두 얹는 Impeccable 전체 설치가 있습니다. 이 도구는 규칙과 명령이 자주 늘어나니 갱신하기 전에 변경 기록을 한 번 훑어보면 좋습니다.