웹페이지를 두고 “좀 더 세련되게”라고 부탁하면 무엇을 바꿀지는 코딩 에이전트가 정한다. 버튼을 키울 수도, 색을 바꿀 수도 있다. 정작 신청 양식의 설명이 읽히지 않는 문제는 남을 수 있다. Impeccable은 이런 요청을 글자 위계, 간격, 기술적 결함처럼 구체적인 작업으로 나누는 디자인 스킬과 검사 도구다. 이미 쓰고 있는 코딩 에이전트에 작업 지침을 더하며, 독립 실행하는 검사기도 제공한다.
Impeccable 설치 방법: 프로젝트에 넣고 첫 검토 열기
Claude Code나 Cursor처럼 파일을 읽고 수정하는 코딩 도구가 준비돼 있고, 수정할 웹 프로젝트가 있다는 전제로 시작한다. 프로젝트 폴더에서 터미널을 연다. VS Code를 쓴다면 상단의 ‘터미널 → 새 터미널’을 선택하고, 명령을 입력하는 위치가 해당 프로젝트인지 확인한다. 아래의 npx는 Node.js에 포함된 패키지 실행 도구다. 공식 패키지가 요구하는 Node.js 버전은 18.19.0 이상이다.
node --version
npx impeccable install설치기가 사용할 코딩 도구와 적용 범위를 묻는다. 처음에는 현재 프로젝트 범위를 골라 다른 프로젝트에 영향을 주지 않게 한다. 지원되는 도구에서는 파일 수정 뒤 자동 검사를 붙이는 디자인 훅도 제안한다. 설치를 마치면 코딩 도구를 다시 열고, 그 도구의 대화 입력창에서 다음을 실행한다. 터미널에서 실행하는 명령과 대화창에서 부르는 스킬 명령은 구분해야 한다.
/impeccable init
/impeccable critique the pricing cardsinit은 코드를 읽고 제품의 대상과 목적, 제약 중 추론할 수 없는 부분을 물어 PRODUCT.md에 저장한다. 두 번째 줄의 가격표 카드는 실제 검토할 부분 이름으로 바꾸면 된다. Codex에서는 /skills에서 스킬을 찾거나 $impeccable init처럼 호출한다. 명령이 목록에 보이는지와 제품 맥락 파일이 생겼는지를 확인한 뒤, 한 컴포넌트의 검토 보고서를 받아 본다.
Claude Code의 플러그인 방식으로 설치하려면 아래 명령으로 마켓플레이스를 추가하고 /plugin에서 Impeccable을 설치할 수도 있다. 두 설치 방식을 모두 실행할 필요는 없다.
/plugin marketplace add pbakaus/impeccable자동 검사까지 쓸 때는 도구별 허용 절차가 남는다. 예를 들어 Codex는 /hooks에서 프로젝트 훅을 승인해야 한다. 스킬이 목록에 보인다는 사실만으로 자동 검사까지 작동한다고 판단하지 않는다.
“가격표를 고쳐 줘”를 검토와 수정으로 나누기
critique는 화면의 사용성과 정보 위계를 살펴 수정 우선순위를 제안한다. audit은 접근성, 성능, 테마, 반응형 동작 같은 기술적 품질을 검토한다. 같은 화면을 보더라도 “어느 요금제를 골라야 할지 모르겠다”는 문제와 “좁은 화면에서 버튼이 잘린다”는 문제는 해결 방식이 다르다.
처음에는 “가격표 카드만 검토하고 파일은 수정하지 말라”처럼 범위를 묶는다. 보고서에서 실제 문제를 고른 다음 typeset으로 글자 크기와 위계를, layout으로 간격을 조정하는 식으로 작업을 좁힌다. polish는 공개 전 마무리 작업에 해당한다. 명령이 파일 수정을 수반할 수 있으므로, 검토와 수정 허용을 요청문에 따로 적는 편이 낫다.
예를 들어 “모바일 가격표에서 추천 요금제와 신청 버튼이 먼저 보이게 하되, 가격·기능·링크는 그대로 두고 카드 간격만 수정해 줘”라고 요청할 수 있다. 이는 사용 예시이며 제품의 고정 명령 형식은 아니다. 기존 디자인 체계를 유지해야 한다면 /impeccable document로 DESIGN.md를 만들고, 이후 수정에서도 그 체계를 기준으로 삼는다.
공식 예시는 색보다 화면의 중심을 바꿨다
공식 README는 같은 모델과 같은 숙소 소개 과제로 만든 두 페이지를 나란히 제시한다. 미적용 예시는 왼쪽의 얇은 세리프 제목, 오른쪽의 평면 일러스트, 둥근 버튼으로 나뉜다. 아래 화면은 제작자가 공개한 웹페이지 예시로, 실제 숙소를 촬영한 사진은 아니다.
적용 예시에서는 절벽 위 집과 바다의 밤 장면이 화면을 채우고, 큰 제목과 문의 버튼이 그 안에 놓인다. 두 이미지에서 비교할 부분은 배경색만이 아니다. 숙소의 위치와 분위기를 한 장면으로 보여 주는지, 텍스트와 그림이 서로 어떤 역할을 하는지가 달라졌다. 이 한 쌍은 방향의 차이를 보여 주는 사례이며, 모든 프로젝트에서 같은 결과가 나온다는 성능 측정은 아니다.
검사기는 작은 글자를 잡지만 좋은 디자인을 판정하지는 않는다
에이전트의 디자인 검토와 별도로, 터미널에서는 detect를 실행할 수 있다. 이 검사기는 정해진 규칙을 사용하므로 별도의 언어모델 API 키가 필요하지 않다. 프로젝트의 src/ 폴더를 검사하고, 실행 중인 개발 서버가 있다면 그 주소도 검사한다. 아래 주소의 포트는 본인 개발 서버에 맞게 바꾼다.
npx impeccable detect src/
npx impeccable detect http://localhost:5173
npx impeccable detect --viewport 390x844 http://localhost:5173JSX·TSX 같은 소스 파일은 패턴 규칙 중심으로 검사한다. URL 검사는 설치된 Chrome 또는 Edge로 페이지를 렌더링해 실제 표시 상태를 확인한다. HTML 파일의 정적 검사도 색과 크기를 판독할 수 있으므로, “파일 검사에서는 대비를 전혀 못 본다”고 단순화하면 안 된다. 외부 스타일과 실행 뒤 생긴 화면까지 확인하려면 개발 서버 주소를 검사하는 경로가 필요하다.
이번 글에서는 Impeccable 4.8.0 검사기를 작은 상담 신청 HTML에 실행했다. 흰 바탕에 #bbbbbb 색상, 10px 크기로 안내 문구를 두자 HTML 파일 검사와 브라우저 렌더 검사 모두 경고 두 건을 반환했다. 출력은 대비를 1.9:1로 보고했고, 기능성 문구의 크기도 지적했다. 같은 문구의 색을 #444444, 크기를 16px로 바꾼 뒤 다시 렌더 검사하자 검출은 0건이었다. 이는 이 예제에서 수행한 검사 결과다.
검출이 있으면 종료 코드는 2, 대상에 접근하지 못하는 등의 검사 실패는 1이다. 검출이 없으면 0을 반환한다. 자동화에서는 2를 프로그램 고장으로 처리하거나, 반대로 1을 “문제없음”으로 처리하지 않아야 한다. 경고 목록과 실행 성공 여부를 함께 읽는다.
0건이 됐다고 신청 흐름이 편해졌다는 뜻은 아니다. 문의하기에 앞서 어떤 정보를 받아야 하는지, 버튼 문구가 약속하는 행동과 실제 동작이 같은지는 화면을 보고 직접 확인해야 한다. 코드 변경 내역과 좁은 화면, 키보드 이동도 마지막에 함께 확인한다.
수정 범위와 실행 권한까지 정하고 끝내기
브랜드 글꼴처럼 의도한 선택이 규칙에 걸리면 이유를 붙여 예외로 남길 수 있다. 경고를 없애기 위해 디자인 체계를 무조건 바꾸기보다, 그 규칙이 이 화면에서 무엇을 보호하는지 판단한다. 반대로 화면을 새로 꾸밀 필요가 없다면 detect만 사용해도 된다.
live는 개발 중인 페이지의 요소를 골라 변형을 비교하고 소스에 반영하는 별도 작업 흐름이다. 로컬 작업용이며 운영 사이트에 주입하지 않는다. 특히 현재 문서는 문구 변경의 Apply 작업이 연결된 채팅 세션을 찾지 못하면, 설치된 Codex 또는 Claude를 승인·샌드박스 우회 옵션으로 호출할 수 있다고 명시한다. 사용할 경우 시작 환경에서 IMPECCABLE_LIVE_COPY_AGENT=chat으로 채팅 경로를 고정하거나 off로 Apply를 끈다. 단순 검토를 위해 이 모드부터 켤 필요는 없다.
첫 작업은 페이지 전체 재설계보다 문제가 있는 컴포넌트 하나가 적당하다. 검토 보고서에서 수정할 항목을 고르고, 허용한 범위만 바꾼 뒤 같은 검사를 다시 실행한다. 마지막에는 보고서의 점수보다 실제 페이지에서 읽고 누르고 이동할 수 있는지를 확인한다.
출처: Impeccable 공식 저장소, 검사기 문서