왜 AI에게 맡긴 화면은 매번 비슷해 보이는가
모델은 대체로 같은 자료를 보고 배웠다. 공개된 웹에 널린 SaaS 랜딩 페이지와 대시보드 템플릿이 그 자료다. 그래서 별다른 지시 없이 화면을 만들라고 하면, 서로 다른 모델과 서로 다른 프로젝트에서 같은 선택이 반복된다. 본문은 Inter, 히어로 배경은 보라에서 파랑으로 흐르는 그라디언트, 제목에는 다시 그라디언트, 카드 안에 또 카드, 카드 왼쪽에는 굵은 색 띠, 제목 위에는 작은 대문자 라벨.
이걸 프롬프트로 매번 교정하려면 같은 말을 계속 반복해야 한다. "좀 더 세련되게", "덜 AI 같게" 같은 지시는 기준이 없어서 결과가 대화마다 흔들린다. Impeccable이 택한 방법은 그 반대다. 무엇이 문제인지 이름을 붙여 규칙으로 만들고, 그 규칙을 에이전트가 읽는 자리에 파일로 놓아 둔다.
출발점은 Anthropic이 공개했던 frontend-design 스킬이다. Impeccable은 거기서 시작해 명령 어휘를 23개로 늘리고, LLM 없이 돌아가는 검출 규칙 60개와 편집 시점에 개입하는 훅을 붙였다. 저장소 설명에 그 계보가 그대로 적혀 있다.
설치는 어떻게 하는가
가장 쉬운 길은 CLI 설치 프로그램이다. 프로젝트 루트에서 아래 한 줄을 돌린다. npx는 Node.js에 함께 오는 명령으로, 패키지를 따로 설치하지 않고 그 자리에서 실행해 준다. Node.js가 없다면 nodejs.org에서 LTS 버전을 먼저 설치한다.
실행하면 이 컴퓨터에 깔린 AI 코딩 도구를 스스로 찾아 목록으로 보여준다. 클로드 코드, 코덱스 CLI, 커서, 제미나이 CLI 같은 것들이다. 감지된 것만 쓸지 직접 고를지 묻고, 이어서 이 프로젝트에만 넣을지 컴퓨터 전체에 넣을지 묻는다. 대답을 마치면 스킬을 내려받아 해당 도구의 설정 폴더에 넣고, 지원되는 도구에는 훅까지 함께 설치한 뒤 다음에 무엇을 하라고 알려준다.
질문 없이 돌리고 싶으면 --providers=claude,codex,cursor 와 --scope=project 같은 플래그로 미리 답을 넘긴다. 스크립트나 팀 온보딩 문서에 넣기 좋다. 이미 설치한 다음 최신으로 올릴 때는 npx impeccable update를 쓴다.
설치 경로는 이것 말고도 있다. 클로드 코드에서는 /plugin marketplace add pbakaus/impeccable로 플러그인 마켓플레이스를 등록해 설치할 수 있고, 팀이 버전을 저장소에 묶어 두고 싶으면 git 서브모듈로 넣은 뒤 npx impeccable link로 각 도구 폴더에 연결한다. 웹사이트에서 도구별 ZIP을 받아 푸는 방법, 저장소의 dist 폴더를 직접 복사하는 방법도 문서에 있다. 처음이라면 첫 번째 방법 하나만 알면 된다.
npx impeccable install
# 질문 없이 돌리려면
npx impeccable install --providers=claude,cursor --scope=project
# 나중에 최신으로
npx impeccable update/impeccable init은 무엇을 만드는가
설치가 끝나면 AI 도구 안에서 /impeccable init을 한 번 실행한다. 이건 파일을 고치는 명령이 아니라 맥락을 정하는 대화다. 먼저 만들 화면이 브랜드 쪽인지 제품 쪽인지 묻는다. 브랜드는 마케팅 페이지, 랜딩, 포트폴리오처럼 인상을 남기는 화면이고, 제품은 앱 UI, 대시보드, 도구처럼 매일 쓰는 화면이다. 같은 규칙을 두 곳에 똑같이 적용하면 한쪽은 밋밋해지고 다른 쪽은 산만해지므로, 이 갈래를 먼저 정한다.
대화가 끝나면 PRODUCT.md와 DESIGN.md가 만들어진다. PRODUCT.md에는 누가 쓰는 화면인지, 어떤 인상을 주고 싶은지, 피하고 싶은 레퍼런스는 무엇인지가 담기고, DESIGN.md에는 색·활자·컴포넌트 같은 시각 규칙이 담긴다. 이후 실행하는 모든 명령이 이 두 파일을 먼저 읽으므로, 매번 브랜드를 다시 설명할 필요가 없어진다.
이미 만들어 둔 화면이 있다면 /impeccable document로 기존 코드에서 DESIGN.md를 역으로 뽑아낼 수도 있다. 백지에서 시작하는 것보다 이미 쓰고 있는 색과 간격을 문서로 굳히는 편이 빠른 경우가 많다.
명령 23개는 언제 무엇을 쓰나
명령은 전부 /impeccable 뒤에 이름을 붙여 부른다. 뒤에 대상까지 적으면 범위가 좁아진다. 예를 들어 /impeccable audit blog는 블로그 화면만, /impeccable polish settings는 설정 화면만 본다. 이름 없이 /impeccable만 치면 전체 목록이 나오고, 설명을 그냥 붙여도 된다.
자주 쓰는 것만 추리면 아래 표 정도다. 매일 쓰는 명령이 생기면 /impeccable pin audit처럼 고정해 /audit 단축을 만들 수 있다.
쓰다 보면 순서가 생긴다. 만들기 전에는 shape로 계획을 잡고, 만든 뒤에는 critique로 사람이 볼 관점을 점검하고, audit으로 기계가 볼 항목을 점검한 다음, polish로 마감한다. 결과가 밋밋하면 bolder, 과하면 quieter, 요소가 많으면 distill로 조정한다.
| 명령 | 언제 쓰나 |
|---|---|
| shape | 코드를 쓰기 전에 화면 구성과 흐름을 먼저 잡는다 |
| craft | 구성부터 구현까지 한 번에 간다 |
| critique | 위계·가독성·인상 같은 사람의 관점으로 리뷰받는다 |
| audit | 접근성·성능·반응형 같은 기술 항목을 점검한다 |
| polish | 출시 전 마감과 디자인 시스템 정합을 본다 |
| bolder / quieter | 결과가 밋밋하거나 반대로 과할 때 강도를 조절한다 |
| distill | 요소가 많아 초점이 흐려졌을 때 덜어낸다 |
| harden | 오류 상태·긴 문구·다국어처럼 깨지기 쉬운 경우를 채운다 |
| clarify | 버튼 문구, 오류 메시지처럼 읽고 헷갈리는 글을 고친다 |
| adapt | 모바일 등 다른 화면 크기에 맞춘다 |
에이전트 없이 검사만 돌리는 법
Impeccable에는 AI 없이 도는 검사기가 따로 들어 있다. npx impeccable detect에 파일이나 폴더, 또는 주소를 주면 규칙에 걸리는 항목을 이름과 함께 알려준다. LLM을 호출하지 않으므로 API 키가 필요 없고 결과가 매번 같다.
검사 방식은 대상에 따라 갈린다. HTML은 연결된 CSS까지 묶어 정적 분석하고, JSX나 CSS 같은 나머지 파일은 패턴 매칭이며, 주소를 주면 실제 브라우저로 띄워 렌더된 화면을 본다. 그래서 소스 스캔이 깨끗해도 주소 스캔에서 걸리는 항목이 따로 있을 수 있다.
확인 삼아 AI가 흔히 내놓는 형태를 그대로 흉내 낸 HTML 한 장을 만들어 돌려 봤다. 결과는 17건이었고 종료코드는 2였다. 지적받은 항목만 고치고 레이아웃 구조는 그대로 둔 채 다시 돌리니 0건, 종료코드 0이 됐다. 종료코드가 0이 아니라는 점이 중요한데, 이것만으로 CI에서 빌드를 막을 수 있기 때문이다.
특정 항목을 끄고 싶으면 파일 안에 impeccable-disable 주석을 넣어 그 자리만 면제하거나, npx impeccable ignores add-value 명령으로 저장소 설정에 예외를 기록한다. 어느 쪽이든 이유를 적게 되므로 판단이 기록으로 남는다.
npx impeccable detect src/ # 폴더 검사
npx impeccable detect index.html # 파일 검사
npx impeccable detect https://example.com # 주소 검사(실제 브라우저)
npx impeccable detect --json . # CI용 출력
# 지적 있으면 종료코드 2, 없으면 0설치 뒤에 한 번 정리할 것
명령을 쓰기 시작하면 프로젝트에 .impeccable 폴더가 생기고 그 안에 작업 파일이 쌓인다. 리뷰 스크린샷, 실행 상태, 캐시, 사람마다 다른 개인 설정 같은 것들이라 대부분은 저장소에 넣을 필요가 없다. 저장소의 README에 그대로 복사해 붙일 .gitignore 블록이 준비돼 있으니 처음 한 번 넣어 두면 된다.
다만 전부 무시하면 안 된다. 공유해야 하는 파일이 몇 개 있다. 프로젝트 공통 설정, 디자인 명세, 리뷰 리포트가 그것이고 이들은 저장소에 남겨 팀이 같은 기준을 보게 한다. 이미 무시 규칙 없이 스크린샷을 커밋해 버렸다면 규칙만 추가해서는 추적이 끊기지 않으므로 git rm --cached로 추적만 해제한다.
지원되는 도구에서는 훅도 함께 설치된다. UI 파일을 고치는 순간 검사기가 돌아 결과를 에이전트 쪽으로 돌려주는 장치다. 커서는 잘못된 수정이 반영되기 전에 막고, 나머지는 수정 뒤에 알려주는 방식이다. 설치 과정에서 훅을 넣을지 물어보므로 원치 않으면 그때 빼면 된다.