Impeccable: słownik projektowy dla twojego agenta AI

Impeccable to darmowy skill agenta (Agent Skill) na licencji Apache-2.0, autorstwa Paula Bakausa, który daje agentowi i jego użytkownikowi jeden słownik projektowy: pojedynczy skill /impeccable z nazwanymi poleceniami, takimi jak audit, typeset czy quieter. Zawiera też deterministyczny detektor, bez LLM i bez klucza API, który wyłapuje typowe wzorce UI generowanego przez AI w hooku edycji lub w CI.

Ta strona jest dla frontend developerów, którzy budują UI z Claude Code, Codeksem albo Cursorem, oraz dla tech leadów, którzy chcą bramki jakości projektowej niezależnej od tego, czy designer przeczyta każdy pull request. Sytuacja, którą rozwiązuje: strona ustawień zbudowana przez agenta działa, ale ma gradient z fioletu w cyjan, Inter wszędzie i karty zagnieżdżone w kartach. Prosisz o „lepsze odstępy” i dostajesz zgadywankę.

Co wyniesiesz z Impeccable

• Działającą instalację w Claude Code, Codeksie albo Cursorze, razem z plikami kontekstu, które czyta każde polecenie.
• Polecenia, których warto nauczyć się najpierw, i kolejność uruchamiania ich na prawdziwym ekranie.
• Bramkę dla pull requestów opartą na npx impeccable detect, z kodami wyjścia i polityką wyjątków.
• Dwa prompty do skopiowania: pętlę „audyt, potem poprawki” i budowę nowego ekranu z kierunkiem, który zatwierdzasz.
• Pułapki: hooki działające poza promptem o uprawnienia, nieaktualne pliki kontekstu i listy wyjątków, które rosną po cichu.

Stan na 2026-09-26: pbakaus/impeccable ma 71,3 tys. gwiazdek na GitHubie (odczyt z GitHuba). skills.sh podaje 293 766 instalacji; to dane wtórne (SECONDARY) z zewnętrznego zrzutu LinklyAI/best-skills z tego samego dnia, więc przed cytowaniem sprawdź ją bezpośrednio na skills.sh. Stronę zweryfikowaliśmy względem CLI impeccable 4.1.0 z npm i źródeł skilla na gałęzi main (SKILL.md w wersji 4.4.0).

Instalacja Impeccable w Claude Code, Codeksie albo Cursorze

Zalecana droga to instalator z npm, uruchomiony w katalogu głównym projektu. Wykrywa foldery harnessów (harness to środowisko agenta: Claude Code, Codex, Cursor), których używasz, pyta, czy instalować do projektu, czy globalnie, a w Claude Code, Codeksie, Cursorze, GitHub Copilot i Grok Build instaluje też hook projektowy (zob. sekcję o hooku). Instalator pobiera samodzielną binarkę silnika; Node.js 22.18 lub nowszy jest potrzebny tylko do npx.

Claude Code

# Terminal, katalog główny projektu
npx impeccable install --providers=claude --scope=project

# Alternatywa: marketplace pluginów (skill wraz z hookami pluginu; potem uruchom init)
claude plugin marketplace add pbakaus/impeccable
claude plugin install impeccable@impeccable

Skill trafia do .claude/skills/impeccable/. Hook trafia do .claude/settings.local.json, który jest w .gitignore, więc każdy developer włącza go na własnej maszynie. Po instalacji przez npx wywołujesz go jako /impeccable. Przy instalacji przez plugin skill dostaje przestrzeń nazw (/impeccable:impeccable); po instalacji sprawdź /help.

Przy instalacji jako plugin hooki są częścią pluginu (w wersji 4.4.0: SessionStart, PostToolUse dla Edit|Write i Stop), więc zarządzasz nimi, włączając lub wyłączając plugin (claude plugin disable impeccable@impeccable), a nie edytując .claude/settings.local.json.

Codex

# Terminal, katalog główny projektu
npx impeccable install --providers=codex --scope=project

Skill trafia do .agents/skills/impeccable/, a hook do .codex/hooks.json. Otwórz /hooks w Codeksie i zatwierdź hook projektu: Codex śledzi zaufanie per definicja hooka, więc npx impeccable update, który zmienia hook, może poprosić o zgodę ponownie. Skill wywołujesz jako $impeccable albo wybierasz z /skills; Codex nie używa do tego poleceń /prompts: (sprawdzone w Codex CLI 0.157.1).

Cursor

# Terminal, katalog główny projektu
npx impeccable install --providers=cursor --scope=project

Skill trafia do .cursor/skills/impeccable/, a hook do .cursor/hooks.json. Sprawdź, czy Cursor wczytał .cursor/hooks.json (hook uruchamia się przed każdym zapisem); jeśli nie, uruchom Cursora ponownie. Ponieważ działa przed zapisem, może go zablokować. Wywołujesz skill jako /impeccable.

Uniwersalne CLI skills też znajduje ten skill (npx skills add pbakaus/impeccable --list zgłasza jeden skill, impeccable, w skills 1.7.0). Kopiuje jednak sam skill, bez hooka, więc użyj go, gdy chcesz słownika bez automatyzacji. Jak skille się ładują i jak je aktualizować, opisuje strona instalowanie i zarządzanie skillami.

Następnie, w agencie, uruchom jednorazową konfigurację:

/impeccable init

Później aktualizujesz przez npx impeccable update. Po każdym z tych poleceń przeładuj harness.

Koszt kontekstu

Impeccable to jeden skill, więc do chwili wywołania w kontekście siedzą tylko jego nazwa i opis; referencje poleceń ładują się na żądanie. Instalacja jako plugin dodaje też hook SessionStart uruchamiany w każdej sesji. Zmierz to u siebie: uruchom /context w Claude Code przed instalacją i po niej albo, przy instalacji jako plugin, claude plugin details impeccable@impeccable, które wypisuje przewidywany koszt w tokenach.

Które pliki czyta Impeccable i które commitować?

Każde polecenie czyta ten sam niewielki zestaw plików, dzięki czemu agent wie, jak ma wyglądać twój produkt, zamiast wracać do swoich domyślnych wyborów:

Plik	Zawiera	Kto go pisze	Commitować?
PRODUCT.md	Odbiorców, cel, ograniczenia, ton i dowody, które naprawdę masz	init	Tak. Edytuj go, jest twój
DESIGN.md	Kolory, typografię, komponenty i reguły systemu wizualnego	document albo koniec nowego buildu	Tak
.impeccable/design.json	Ustrukturyzowaną kopię DESIGN.md dla detektora i Live Mode	document	Tak
.impeccable/surfaces/*.md	Strategię per trasa i kontrakt kierunku nowego buildu	Powstaje w trakcie pracy	Tak
.impeccable/config.json	Ustawienia hooka, wyjątki detektora, buildPath	/impeccable hooks …, npx impeccable ignores …	Tak
.impeccable/config.local.json, zrzuty ekranu, stan Live Mode	Nadpisania per developer i pliki tymczasowe	Impeccable	Nie. Dodaj blok .gitignore z README

Dwie reguły w skillu kształtują wszystko dalej. init zapisuje tylko to, co prawdziwe, łącznie z brakami w rodzaju „nie mamy jeszcze logotypów klientów”, więc kolejne polecenia nie wymyślą ściany logo. A każdy ekran dostaje tryb wybrany według tego, po co przyszedł odwiedzający: Persuade (landing page, cennik), Operate (aplikacje, dashboardy), Read (dokumentacja, changelogi) albo Experience (portfolio, galerie). Landing page narzędzia dla developerów to Persuade, choć sam produkt to Operate, i polecenia odpowiednio zmieniają priorytety.

Których poleceń Impeccable nauczyć się najpierw?

Każde polecenie uruchamiasz jako /impeccable <polecenie> <cel> (w Codeksie $impeccable). Skill wymienia 24 pozycje: 23 działające polecenia i craft, który jest dziś przestarzałym aliasem. Zamiast niego opisz ekran (/impeccable a pricing page for enterprise buyers), a skill sam wybierze ścieżkę. Samo /impeccable pokazuje menu dopasowane do stanu projektu i nigdy niczego nie uruchamia samodzielnie.

Grupa	Polecenia	Kiedy po nie sięgnąć
Konfiguracja	init, document, extract	Start projektu albo moment, gdy ten sam przycisk żyje w 12 miejscach
Planowanie	shape	Ticket jest mglisty. Przeprowadza z tobą wywiad i zwraca brief, bez kodu
Ocena	audit, critique	Potrzebujesz ustaleń, zanim ktokolwiek cokolwiek zmieni
Naprawa	harden, clarify, adapt, optimize, onboard	Przypadki brzegowe, teksty UX, inne urządzenia, szybkość, pierwsze uruchomienie
Dostrajanie charakteru	bolder, quieter, distill, colorize, typeset, layout, animate, delight, overdrive	Ekran działa, ale jest generyczny, krzykliwy, przeładowany albo płaski
Wykończenie	polish	Ostatni przebieg przed wydaniem
Iteracja w przeglądarce	live, generate	Chcesz trzech wariantów jednego elementu na działającym serwerze deweloperskim

Na początek naucz się czterech: audit, critique, harden i polish. Pozostałe to precyzyjniejsze słowa na to, co inaczej opisałbyś akapitem. Trzy rozróżnienia oszczędzają przeróbek:

• audit dokumentuje, nie naprawia. Ocenia pięć wymiarów, każdy w skali 0–4: dostępność, wydajność, theming, responsywność oraz spójność implementacji, która obejmuje ustalenia detektora i odejścia od systemu projektowego. Każdemu ustaleniu nadaje priorytet od P0 do P3. Ustalenia kierujesz potem do harden, optimize albo polish.
• critique to warstwa oceny jakościowej. Punktuje dziesięć heurystyk Nielsena w skali 0–4, sprawdza ekran oczami person i zadaje pytania, na które interfejs sam nie odpowie. Uruchamiaj go tylko na skończonej pracy.
• quieter i distill rozwiązują różne problemy. Za głośno (neony, gradienty, sześć akcentów) to quieter. Za dużo rzeczy to distill.

/impeccable pin audit tworzy osobny skrót /audit dla polecenia, którego używasz codziennie; unpin go usuwa.

Dopracowanie istniejącego ekranu: pętla „audyt, potem poprawki”

To przepływ na większość dni: ekran zbudowany przez agenta działa, ale przed merge’em musi spełnić twój standard. Przechodzi przez planowanie, budowę, weryfikację, przegląd i wydanie, a na każdym kroku zostaje zapisany dowód.

1. Skanuj, zanim zapytasz o gust. Uruchom w terminalu npx impeccable detect src/app/settings. Nic nie kosztuje, a daje punkt odniesienia: liczbę deterministycznych ustaleń.

2. Audyt. /impeccable audit settings zwraca Audit Health Score w skali do 20 i listę P0–P3. Raport zapisz przy pull requeście, nie w czacie.

3. Poprawki według priorytetu. P0 i P1 idą do harden (przypadki brzegowe, błędy, i18n, przepełnienia) albo optimize; reszta czeka na polish. Jedno polecenie na przebieg sprawia, że każdy diff da się przejrzeć.

4. Ponowna weryfikacja tymi samymi narzędziami. Uruchom ponownie detect i audit. Liczba ustaleń i wynik zdrowia muszą pójść we właściwą stronę; jeśli jakieś P0 zostało otwarte, przebieg nie jest skończony.

5. Na końcu critique i polish. /impeccable critique settings dla przeglądu heurystycznego, potem /impeccable polish settings. Zdrowy przebieg polish wprowadza drobne poprawki. Jeśli zaczyna przepisywać layout, przerwij i uruchom layout albo critique.

Prompt do skopiowania: audyt, naprawa blokerów, dowód

/impeccable audit src/app/settings

Then, without asking me again:
1. Run `npx impeccable detect src/app/settings --json` and record the finding count.
2. Fix every P0 and P1 finding from the audit, using /impeccable harden for edge cases and
   /impeccable optimize for performance. Do not touch P2/P3 findings or files outside src/app/settings.
3. Re-run the audit and the detector.
4. Reply with a table: finding, severity, fixed (yes/no), file:line, and the before/after
   Audit Health Score and detector count. List anything you could not fix and why.
Do not add any detector ignore to make a finding disappear.

Ostatnia linia ma znaczenie. Agent pod presją „zazielenienia” sprawdzenia sięgnie po wyjątek. Wytyczne hooka Impeccable każą agentowi naprawiać prawdziwe problemy i samodzielnie dodawać tylko wąskie, uzasadnione wyjątki dla konkretnych wartości, więc powtórz to również w prompcie.

Budowa nowego ekranu z kierunkiem, który zatwierdzasz

Przy nowej stronie albo redesignie Impeccable nie pozwala modelowi zbudować pierwszego pomysłu, który mu przyjdzie do głowy. Przepływ new-work w skillu uruchamia skrypt concept-seed, który rozdaje kierunki do wyboru, więc kolejne przebiegi nie zbiegają się do domyślnego wyglądu kategorii:

1. Klasyfikacja zadania. Dodatek do istniejącej strony dziedziczy jej wygląd; redesign traktuje stary wygląd jako materiał dowodowy do zastąpienia, a nie do polerowania.
2. Rozdanie kierunków. Agent wyprowadza kilka kierunków z twojego produktu i jego odbiorców; skrypt wybiera, które z nich trafią do ciebie, i może dołożyć pretendentów z katalogu systemów wizualnych. Akceptujesz jeden, losujesz ponownie albo korygujesz jednym zdaniem („zbyt korporacyjnie”). Zwykła, standardowa dla kategorii opcja jest zawsze dostępna, jeśli jej chcesz.
3. Najpierw makieta albo najpierw kod. Gdy dostępne jest generowanie obrazów, Impeccable może wyrenderować pełną makietę i budować pod nią ("buildPath": "comp" w .impeccable/config.json); bez niego, albo gdy wolisz szybkość, buduje od razu w kodzie ("code").
4. Kontrakt, potem sprawdzenie. Przed kodem agent zapisuje krótki kontrakt kierunku w sekcji ## Direction contract briefu ekranu (.impeccable/surfaces/), nigdy w kodzie źródłowym trafiającym do wydania. Końcowy przegląd sprawdza build względem tego kontraktu, a DESIGN.md powstaje z gotowego rezultatu.

Prompt do skopiowania: nowy cennik, zatwierdzony przed kodem

/impeccable a pricing page for engineering managers comparing our Team and Enterprise plans.

Constraints: reuse our existing components in src/components/ui, keep the current brand colours
from DESIGN.md, and every price and feature must come from src/lib/plans.ts (do not invent
logos, testimonials, or numbers). Show me the directions before writing any code and wait for my
pick. After building, run `npx impeccable detect src/app/pricing` and /impeccable audit pricing,
fix every P0/P1, and report the direction contract, the detector count, and the audit score.

Gdy chcesz poprowadzić specyfikację dalej niż jedną stronę (kierunek wizualny, prototyp, kontrakt projektowy, implementacja z dowodem), użyj czteroartefaktowego pipeline’u od projektu do kodu; Impeccable pasuje do jego kroków budowy i wykończenia.

Bramka dla pull requestów z detektorem

Detektor to ta część Impeccable, którą tech lead może egzekwować. Uruchamia deterministyczne reguły bez modelu i bez klucza API, na plikach, folderach, stdin albo adresie URL:

npx impeccable detect src/                   # folder
npx impeccable detect index.html             # jeden plik
npx impeccable detect https://example.com    # wyrenderowana strona (używa zainstalowanego Chrome/Chromium/Edge)
npx impeccable detect --json src/            # format maszynowy, na stdout
npx impeccable detect --scope type src/      # jedna dziedzina projektowa (type, layout)

Kody wyjścia robią z niego sprawdzenie w CI: 0 oznacza brak głównych ustaleń, 2 oznacza ustalenia, a 1 oznacza, że któregoś celu nie dało się przeskanować. Niektóre reguły, na przykład nadużywanie pauz (—), są doradcze: pojawiają się na liście, ale nigdy nie zmieniają kodu wyjścia. Czytelne dla człowieka ustalenia trafiają na stderr, więc przekieruj je przez 2> findings.txt. README podaje 61 reguł deterministycznych. Gdy w projekcie jest DESIGN.md, część z nich wyłapuje odejścia od twojego systemu, na przykład font spoza twojego zestawu.

Minimalne zadanie GitHub Actions, z uprawnieniami tylko do odczytu i bez sekretów:

.github/workflows/design-gate.yml

name: design-gate
on: pull_request
permissions:
  contents: read
jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npx -y impeccable@4.1.0 detect src/

Przypnij wersję, żeby nowa reguła nie oblała wszystkich otwartych pull requestów w dniu wydania; podbijaj ją w osobnym pull requeście.

Kto zatwierdza. Detektor dowodzi braku znanych wzorców, a nie dobrego projektu. Samo README Impeccable nazywa czysty przebieg „dowodem, nie gwarancją”. Podziel więc odpowiedzialność: CI pilnuje reguł deterministycznych, autor dołącza do pull requesta raport audit (wynik zdrowia i listę P0–P3), a człowiek ogląda wyrenderowaną stronę w dwóch szerokościach ekranu. Nikt nie musi czytać CSS linijka po linijce. Szerszą praktykę wyłapywania śladów generowanego kodu opisuje strona o wykrywaniu slopu; dostępność wykraczającą poza detektor – testowanie dostępności.

Wyjątki są częścią polityki, a nie obejściem. Zapisuj je z uzasadnieniem:

npx impeccable ignores add-value overused-font Inter --reason "Brand font, approved by design"
npx impeccable ignores add-file "src/legacy/**"

Oba polecenia zapisują do .impeccable/config.json, który przebieg CI czyta z checkoutu samego pull requesta. Obejmij ten plik i .github/workflows/ regułą CODEOWNERS i włącz wymagane review właściciela kodu w ochronie gałęzi albo w rulesecie, żeby pull request nie mógł bez przeglądu wyciszyć reguły ani zmienić zadania, które ją egzekwuje. Przy pull_request GitHub uruchamia YAML workflow z merge refa pull requesta, więc plik workflow potrzebuje takiej samej ochrony jak konfiguracja. To samo dotyczy komentarzy impeccable-disable-next-line w kodzie; flaga --no-inline-ignores sprawia, że CI je pomija.

Uruchamiaj detektor przy każdej edycji agenta

Hook projektowy uruchamia ten sam detektor w trakcie pracy agenta, więc ustalenia docierają do agenta, zanim dotrą do ciebie. Instalator proponuje go domyślnie; /impeccable hooks on, off i status zarządzają nim per projekt.

Harness	Plik hooka	Zachowanie
Claude Code	.claude/settings.local.json	Przypomnienie po każdej edycji UI; głębszy przebieg przy Stop
Codex	.codex/hooks.json	Przypomnienie po każdej edycji UI; głębszy przebieg przy Stop; zatwierdzenie przez /hooks
Cursor	.cursor/hooks.json	Najpierw sprawdza proponowany zapis i blokuje go przy prawdziwym ustaleniu

Sprawdzenia przy każdej edycji pokazują tylko jednoznaczne problemy: zepsute obrazy, przepełnienia, błędy kontrastu, tekst z gradientem, poświatę i odejścia od DESIGN.md. Reguły dotyczące gustu czekają na jeden, zdeduplikowany przebieg na końcu sesji. Ustaw hook.perEditRules na "all" w .impeccable/config.json, jeśli chcesz wszystkich reguł przy każdej edycji.

Gdy Impeccable zawodzi: jak z tego wyjść

Pułapki Impeccable

• Hooki działają poza promptem o uprawnienia. W Claude Code zainstalowane hooki poleceń działają niezależnie od zatwierdzania narzędzi; pierwsza edycja może pobrać i zapisać w cache silnik, nawet jeśli odmówiłeś uruchomienia launchera. Przed przebiegami bez nadzoru przejrzyj .claude/settings.local.json (albo, przy instalacji jako plugin, claude plugin details impeccable@impeccable) albo przekaż --settings '{"disableAllHooks": true}'. Zob. bezpieczeństwo łańcucha dostaw skilli.
• Live Mode uruchamia skrypt z twojego repo. Stosowanie edycji tekstu uruchamia opcjonalny skrypt impeccable:manual-edit-validate z package.json z twoimi uprawnieniami. Używaj Live Mode tylko w checkoutach, którym ufasz, i nigdy na stronie produkcyjnej.
• craft jest przestarzały. Starsze tutoriale zaczynają od /impeccable craft; zamiast tego opisz ekran.

Wynik dryfuje w stronę generycznych domyślnych wyborów. Brakuje PRODUCT.md albo DESIGN.md lub są nieaktualne. Uruchom /impeccable doctor: raportuje rozjazd między twoimi plikami Impeccable a tym, co czyta zainstalowana wersja, naprawia to, co mechaniczne, a decyzje wymagające oceny kieruje do init albo document. W monorepo sprawdź, które aplikacje dziedziczą kontekst z katalogu głównego.

Hook w Codeksie nic nie robi. Nie zatwierdziłeś go w /hooks albo aktualizacja zmieniła jego definicję i trzeba zatwierdzić go ponownie. Stan pokazuje /impeccable hooks status.

Po podbiciu wersji CI świeci na czerwono w każdym pull requeście. Nowa reguła odpaliła na istniejącym kodzie. Przypnij poprzednią wersję, uruchom detect na main i napraw albo zapisz wyjątki w jednym pull requeście, zanim podbijesz wersję ponownie.

Lista wyjątków ciągle rośnie. Agent wycisza zamiast naprawiać. Przeglądaj .impeccable/config.json jak kod, odrzucaj nowe wpisy detector.ignoreFiles i detector.ignoreRules, o które nikt nie prosił, i zostaw w promptach linię „bez nowych wyjątków”.

bolder sprawia, że dashboard krzyczy. Śmiałość pasuje do ekranów Persuade. Uruchom quieter na wyniku i sprawdź, czy ekran ma tryb Operate.

Natywny kod iOS albo Androida nie dostaje żadnych ustaleń detektora. Detektor, Live Mode i hook czytają HTML i CSS. W projektach natywnych audit i adapt ładują natywne referencje, więc polegaj na nich i na testach platformowych.

Impeccable a inne skille projektowe

• Taste Skill ogranicza generowanie z góry jednym, wyselekcjonowanym zestawem reguł. Impeccable wyprowadza kierunki z twojego produktu, każe ci wybrać i dokłada słownik audytu i dopracowania na wszystko, co dzieje się potem. Wybierz jeden na projekt; dwa skille projektowe odpalone przy jednym żądaniu dają dwie sprzeczne procedury.
• shadcn/improve audytuje architekturę komponentów, a nie projekt wizualny. Te dwa skille się uzupełniają.
• frontend-design od Anthropic to punkt wyjścia Impeccable, jak podaje jego README. Przegląd skilli frontendowych porównuje go z innymi opcjami.

Dokąd dalej z Impeccable

Czteroartefaktowy pipeline od projektu do kodu Bramkowany przepływ kierunek → prototyp → kontrakt → kod, do którego pasują kroki budowy i wykończenia Impeccable.

Wykrywanie slopu Wyłapuj ślady generowanego kodu i UI w przeglądzie i w CI, nie tylko jednym detektorem.

Najlepsze skille frontendowe Połącz Impeccable ze skillami frameworków, żeby agent pisał aktualny React, Vue albo Svelte.

Grill Me i Grill With Docs Impeccable decyduje, jak to wygląda; grillowanie decyduje, co budujesz, zanim powstanie kod.

Bezpieczeństwo łańcucha dostaw skilli Przejrzyj hooki i dołączone skrypty, zanim skill uruchomi się w twoim repo.