Impeccable: 디자인 지침과
검사 엔진을 함께 읽기

분석 기준: 저장소 ID 1097346685의 5e745ace7e151feb2a93d360d0281fe39448b857에서 README·package.json·Hermes 플러그인과 Rust의 플러그인 활성 판정을 대조했습니다. 아래 엔진 설명은 이전 8409a564d1baee90b2dde4f7a8f06288838e3921 분석을 이어가며, 이번에는 Hermes 설치·신뢰·오류 처리 경계를 보완했습니다. 외부 프로젝트 실행·설치·모델 호출은 하지 않았습니다.

1프로젝트 한줄 요약

Impeccable은 AI 코딩 에이전트에 디자인 지침과 작업 명령을 설치하고, 별도의 결정론적 엔진으로 UI 결함을 찾는 프로젝트입니다. 스킬의 판단·수정은 사용 중인 하니스의 모델이 맡고, detect는 LLM·API 키 없이 실행됩니다. 둘을 같은 검사로 취급하면 비용·재현성·검사 범위를 잘못 이해하게 됩니다.

현재 README와 스킬 라우팅 표는 스킬 1개·명령 24개를 설명합니다. 추적된 crates/live/assets/antipatterns.json에는 고유 규칙 62개가 있고, slop과 quality가 각각 31개입니다. 이는 관측 커밋의 수치이며 완전한 디자인 품질 보증 수치가 아닙니다.

2왜 주목받는가

2026-10-26 09:00 KST Daily 수집에서 6위였습니다. 이 순위는 모멘텀 관측이며 특정 기능이 상승 원인이라는 증거는 아닙니다. 기술적으로는 디자인 지침, 사람이 요청하는 작업 어휘, 반복 가능한 검사 코드를 하나의 저장소에서 연결한다는 점을 볼 만합니다.

README는 Anthropic의 frontend-design에서 출발했다고 밝힙니다. 현재는 init이 지속적인 제품 사실을 PRODUCT.md에 담고, 시각 체계는 DESIGN.md로 구분합니다. 스킬 원본의 모드는 Persuade·Operate·Read·Experience로 나뉩니다. 앱의 조작 화면과 랜딩 페이지에 같은 표현 규칙을 기계적으로 적용하지 않으려는 설계입니다.

일반적인 문법 린터와 비교하면 검사 대상이 글자 위계·레이아웃·대비·시각적 반복으로 넓어집니다. 다만 취향에 관한 권고와 접근성 결함은 같은 무게가 아니며, 규칙이 프로젝트의 의도와 충돌할 수 있습니다. DESIGN.md 맥락과 예외 설정, 실제 렌더 검토가 필요한 이유입니다.

3기술 스택 전체 지도

고정 소스의 package.json은 4.8.0, ENGINE_VERSION과 플랫폼 선택 의존성은 0.1.18입니다. 설치 패키지 버전·엔진 버전·스킬 릴리스를 구분해야 합니다.

4아키텍처 심화 분석

1. npm은 엔진을 찾는 얇은 진입점입니다

cli/bin/cli.js는 환경 지정 바이너리 → 플랫폼별 선택 의존성 → 버전별 사용자 캐시 → 공개 release 다운로드 순으로 엔진을 찾습니다. 다운로드는 패키지에 포함된 engine-checksums.txt의 해시가 맞은 뒤 임시 파일을 최종 캐시에 옮깁니다. 이어받은 인수와 표준 입출력을 엔진에 전달합니다. 예전 Node 파서가 현재 검사 전체를 실행한다고 설명하면 잘못입니다.

2. 검사 결과와 검사 실패를 분리합니다

crates/detect/src/cli.rs의 계약은 0=주요 finding 없음, 1=대상 하나 이상 검사 불가, 2=검사 완료 후 주요 finding 있음입니다. advisory는 별도 권고이며 실패 개수·종료 코드를 바꾸지 않습니다. 여러 대상을 검사할 때 일부 대상이 실패하면 운영 오류가 우선합니다. 빈 JSON만 보고 통과를 판단하지 말고 종료 코드와 stderr도 확인해야 합니다.

# 독자가 별도 시험 프로젝트에서 실행할 예시
npx impeccable detect index.html --json > findings.json
# 종료 0: 주요 finding 없음 / 1: 검사 불가 / 2: 주요 finding 있음

3. URL 검사와 열린 창 부착은 다릅니다

crates/browser/src/lib.rs는 Puppeteer 대신 설치된 Chromium을 찾고 CDP로 제어합니다. 페이지에서 스냅샷을 수집한 뒤 네이티브 규칙 코어로 평가합니다. CLI 도움말 일부에는 과거 Puppeteer 표현이 남아 있어 실제 런타임 소스와 대조해야 합니다. 봇 챌린지·오류 페이지·동의 벽만 있는 페이지는 깨끗한 디자인으로 처리하지 않고 거부합니다.

--cdp는 이미 실행 중인 Chromium 기반 앱의 페이지를 검사합니다. --target은 여러 창 중 URL·제목의 부분 문자열로 고릅니다. 계약상 창을 탐색·리사이즈·종료하지 않으며, 파일/URL 대상이나 viewport 옵션을 함께 넘기는 잘못된 조합은 거부합니다.

4. 같은 규칙을 여러 실행 환경에서 재사용합니다

브라우저용 번들은 crates/wasm과 browser-bundle/을 조립합니다. 네이티브 URL CLI 경로가 모든 규칙을 페이지 안의 WASM으로 실행한다는 뜻은 아닙니다. RulePack은 기본 규칙 뒤에 추가 텍스트·요소·페이지 검사를 붙이는 Rust 확장점입니다. 등록 ID는 충돌할 수 없고 process lifetime 동안 유지됩니다.

// crates/foundation/src/rule_pack.rs의 인터페이스 발췌
pub trait RulePack: Send + Sync + std::fmt::Debug {
    fn registry(&self) -> &'static [Antipattern];
    // check_text / check_element_dom / check_page_dom은 기본 빈 결과
}

4.8.0의 CLI 출력과 설치 검증

detect --github는 finding을 GitHub Actions annotation으로 출력합니다. --json·--list-rules와 함께 사용할 수 없습니다. --list-rules는 대상을 스캔하지 않고 규칙 목록을 출력하며 JSON 형식도 고를 수 있습니다. --scope와 --no-advisory는 검사 결과의 범위를 조절합니다.

npx impeccable detect --github src/
npx impeccable detect --list-rules --json

cli/bin/cli.js는 버전별 캐시나 내려받은 엔진을 패키지에 들어 있는 engine-checksums.txt의 SHA-256과 대조합니다. 해당 버전·플랫폼의 해시가 없으면 내려받기 전에 거부하고 불일치 바이트를 캐시에 확정하지 않습니다. 환경 변수로 직접 지정한 바이너리나 설치된 플랫폼 패키지까지 이 다운로드 검증 경로와 같다고 일반화하지 않습니다.

README의 설치 대상에는 Devin과 Replit Agent가 추가됐습니다. 도구별 설치 위치·네이티브 편집 훅 지원은 서로 다르므로 provider 이름과 프로젝트/전역 범위를 확인합니다. 위 명령은 소스로 확인한 실습 예시이며 이 분석에서 실행하지 않았습니다.

Hermes: 편집 검사와 종료 검사를 연결하는 플러그인

skill/hermes-plugin/__init__.py는 Hermes의 write_file·patch 결과를 공통 엔진이 이해하는 PostToolUse 이벤트로 바꿉니다. JSON 도구 결과에는 impeccable 키로 findings를 넣어 Hermes가 편집 기록을 계속 읽을 수 있게 합니다. 종료 직전 pre_verify는 Stop 이벤트를 보내 추가 검사가 필요하면 턴을 이어가게 합니다.

실행할 launcher는 편집 파일 위쪽의 가장 가까운 신뢰된 프로젝트 스킬에서 찾고, 없으면 Hermes home 설치를 찾습니다. 편집 검사 제한은 5초, 종료 검사는 30초이며 오류·시간 초과·launcher 부재는 원래 편집을 막지 않습니다. 따라서 hook 오류를 디자인 검사 통과로 해석하면 안 됩니다. 프로젝트와 전역 설치 모두 플러그인은 Hermes home의 plugins/impeccable-design-hook/에 두며, crates/context/src/hermes.rs는 파일 존재와 config의 enabled/disabled 목록을 함께 확인합니다. 설정을 확실히 읽을 수 없으면 자동 hook이 활성화됐다고 간주하지 않습니다.

모노레포의 상대 경로와 surface brief

2026-10-30에 대조한 02523aec3e4c4580102d996d1b6a71fbe062e03f의 crates/context/src/surface_briefs.rs는 사용자가 입력한 상대 파일 경로를 호출 위치(cwd)에서 해석한 뒤 대상 프로젝트 기준 경로로 정규화합니다. 예를 들어 모노레포 루트에서 apps/a/src/App.tsx를 넘기면 앱의 brief에는 src/App.tsx로 대응됩니다. 프로젝트 바깥 경로나 프로젝트 루트 자체는 유효한 파일 대상이 아닙니다.

과거 workspace 접두가 중복 저장된 brief는 정상 대상 매핑을 먼저 찾고, 없을 때 실제 파일이 존재하지 않는 이전 표기를 보조 매핑으로 읽습니다. 같은 파일을 어느 디렉터리에서 지정했느냐에 따라 맥락을 잃는 문제를 줄이지만, 실제 존재하는 다른 경로까지 무조건 같은 대상으로 합치지는 않습니다.

캐시 검증 stamp와 오래된 번들 엔진

같은 날 후속 커밋 df3a4ab에서는 .verified 파일이 있다는 이유만으로 캐시를 실행하던 조건을 바꿨습니다. manifest에서 허용한 digest, 바이너리 바이트 수, 바이너리가 stamp보다 새롭지 않은지를 함께 검사합니다. 조건이 달라지면 SHA-256을 다시 계산하고, 불일치하면 해당 캐시를 사용하지 않습니다. 이 빠른 경로는 매번 전체 바이트를 해싱하는 방식은 아닙니다.

스킬 옆에 남은 번들 엔진은 engine-probe가 반환한 버전을 스킬의 VERSION과 비교합니다. 업그레이드 때 남은 구형 바이너리는 건너뛰며, 명시적인 IMPECCABLE_BIN 지정은 운영자가 선택한 별도 경로입니다. Windows ARM의 x64 대체 자산도 허용 manifest와 대조합니다. 설치 문제가 생기면 스킬 파일만이 아니라 실제 실행 엔진·캐시 버전을 함께 확인하는 이유입니다.

5디렉토리 구조 해부

impeccable/
├─ skill/SKILL.src.md        명령·모드·라우팅 원본
│  ├─ reference/            작업별 상세 문서
│  └─ scripts/impeccable    엔진 launcher
├─ cli/bin/cli.js           npm shim
├─ Cargo.toml               Rust workspace
├─ crates/
│  ├─ cli/                  verb·종료 코드·엔진 결합
│  ├─ detect/ html/ browser/ 입력별 검사 경로
│  ├─ foundation/ core/     규칙 registry·계산·확장 trait
│  ├─ wasm/ bundle/         브라우저용 배포 자산
│  └─ skills/ hook/ live/   설치·편집 후 검사·반복 UI
├─ browser-bundle/          페이지 측 스냅샷·overlay 코드
├─ scripts/build.js         하니스별 변환·수치 정합성
├─ tests/oracle/            관측 가능한 동작의 회귀 기준
└─ docs/ENGINE.md           엔진 구조·개발·배포 설명

scripts/build.js는 명령 표의 실제 행 수를 세고, 추적된 규칙 JSON에서 고유 ID 수를 읽어 README 등과 대조합니다. 62라는 숫자를 문서마다 임의로 유지하기보다 원본 구조에서 계산해 배포 문서와 맞추는 방식입니다. dist/와 하니스용 파일은 스킬 원본·생성기를 함께 봐야 이해할 수 있습니다.

6학습 포인트

• 입력별 분석 정밀도: TSX 텍스트 패턴과 정적 HTML의 DOM·CSS, 렌더 스냅샷이 확인할 수 있는 사실이 어떻게 다른지 비교합니다. 소스에서 찾지 못한 동적 상태를 자동으로 깨끗하다고 판단할 수는 없습니다.
• 관측과 정책 분리: registry의 ID·분류·severity·지침 연결과 core의 판정 코드를 구분해 읽습니다. rule pack이 기본 검사 뒤·예외 적용 전에 들어가는 이유도 추적합니다.
• 맥락 파일의 역할: PRODUCT.md의 지속적 사실과 DESIGN.md의 시각 체계를 분리하는 방식은 디자인 외의 도메인 에이전트에도 적용할 수 있습니다.
• 행동 호환성: Rust로 옮겨도 출력·종료 코드·순서가 바뀌지 않게 oracle로 고정하는 구조를 봅니다. 테스트 파일이 있다는 사실과 이 글에서 테스트를 실행했다는 주장은 구분합니다.

7시스템 요구사항·설치

# 별도 프로젝트에서 독자가 선택할 설치 예시
npx impeccable install --providers=codex --scope=project
# 설치 후 하니스 안에서
$impeccable init
# 기존 설치 갱신
npx impeccable update

설치는 스킬과 하니스별 hook을 기록할 수 있습니다. README는 Codex의 프로젝트 hook 승인 절차를 별도로 설명합니다. 수동 ZIP/Git 경로는 Node 없이 사용할 수 있지만 엔진과 브라우저 조건까지 사라지는 것은 아닙니다. 이 분석에서는 설치·설정 변경을 하지 않았습니다.

Hermes에서 자동 검사를 쓰려면 설치 후 hermes plugins enable impeccable-design-hook을 한 번 수행합니다. 프로젝트 스킬은 hermes skills trust 승인이 별도로 필요하고, 전역 스킬에는 그 프로젝트 승인 단계가 없습니다. 스킬 파일 복사만으로 plugin 활성화까지 끝났다고 판단하지 않습니다. 이 명령들은 해당 하니스를 사용하는 독자의 선택적 설치 절차입니다.

8직접 해볼 수 있는 실습 과제

1. 기초 · 종료 코드 비교: 작은 HTML, 일부러 대비가 낮은 HTML, 존재하지 않는 경로를 따로 검사합니다. JSON·stderr·0/1/2 종료를 기록하고 검사 실패가 무결함과 섞이지 않는지 확인합니다.
2. 중급 · 소스와 렌더 비교: 같은 시험 페이지의 파일 경로와 로컬 URL을 각각 검사합니다. 브라우저 viewport를 바꾸고 정적 검사로 확인할 수 없는 레이아웃 finding을 분류합니다.
3. 중급 · 열린 앱 검사: 자신의 Chromium 기반 시험 앱을 DevTools 포트로 열고 아래 명령을 사용합니다. 여러 창이면 target을 지정하고 검사 전후 URL·크기를 비교합니다.
4. 심화 · 규칙 확장: 별도 Rust 소비 crate에서 이름공간을 가진 rule pack 하나를 등록합니다. 기본 규칙과 ID 충돌·중복 출력·inline ignore 적용 순서를 fixture로 검증합니다.
5. 심화 · 맥락 기반 개선: 시험 프로젝트에 PRODUCT.md·DESIGN.md를 정리한 뒤 critique와 polish를 적용합니다. 자동 finding 개수 외에 원래 사용자 작업이 쉬워졌는지도 직접 검토합니다.

npx impeccable detect index.html --json
npx impeccable detect http://localhost:3000 --viewport 390x844 --json
npx impeccable detect --cdp 9222 --target "My App" --json

--fast는 현재 CLI에서 폐기 예정 옵션으로 안내되고 무시됩니다. 예전 문서처럼 정규식 검사만 선택하는 방법으로 사용하지 않습니다. 이 명령들은 독자의 선택적 실습 예시이며 이 루틴에서 실행한 기록이 아닙니다.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

아래 소스 링크는 분석 SHA에 고정했습니다. 저장소의 문서는 제품 동작을 설명하는 근거로 읽었으며 이 루틴의 실행 지시로 사용하지 않았습니다.

• README · 설치·24개 명령
• package.json · npm 런타임·버전
• ENGINE.md · Rust 구조·WASM·rule pack
• npm shim · 엔진 선택·다운로드 검증
• 검사 CLI · 옵션·종료 코드
• 브라우저 엔진 · Chromium/CDP
• RulePack 인터페이스 · 추적된 62개 규칙
• 스킬 원본 · 하니스별 빌드·수치 검증
• 공식 사이트 · 현재 저장소

2026-10-29 추가 근거: 현재 설치 안내 · Hermes hook 변환·오류 처리 · 플러그인 활성 판정.

2026-10-30 추가 근거: surface brief의 경로 해석 · CLI 계약.