Impeccable

Русское руководство по дизайн-скиллу impeccable для Claude Code и других агентных сред: как устроен конвейер, в каком порядке идут шаги, что делает каждая из команд, что ставят хуки и на чём скилл спотыкается.

Что это и зачем

impeccable — это скилл (набор инструкций плюс вспомогательные node-скрипты), который подключается к агентной среде и меняет то, как агент делает фронтенд-дизайн. Это не библиотека компонентов, не генератор макетов и не плагин к Figma. Внутри нет ни одного пикселя готового дизайна.

Он решает одну конкретную проблему: модель по умолчанию делает «безопасный» дизайн — усреднённый, узнаваемо-нейросетевой, без точки зрения. Скилл добавляет три вещи, которых у модели нет самой по себе:

• Процедуру. Сначала фиксируется правда о продукте (PRODUCT.md), потом выбирается визуальный мир, и только потом пишется код. Пропустить шаг механически нельзя — см. Порядок работы.
• Детерминированный детектор. 59 правил, которые ловят типовую машинную халтуру (градиентный текст, свечение вместо тени, «кикер над заголовком», низкий контраст, дрейф дизайн-системы) — это не мнение модели, а сканер по файлам.
• 23 именованные команды с разными сценариями: от аудита до «сделай смелее».

Чем он не является

• Не для бэкенда и не для не-UI задач. Это прямо записано в описании скилла.
• Не автопилот. На /impeccable без аргумента скилл обязан показать меню и не запускать команду сам.
• Не замена вкусу. Чистый прогон детектора в самом скилле описан как «не финиш»: «A clean detector pass is not finished».
• Live-режим и детектор — только веб. Для ios/android есть отдельные справочники, но браузерный оверлей и HTML-движок правил там не работают.

Как он попадает в работу

Три канала внутри агента, все три реальны:

1. По имени команды: /impeccable audit src/app.
2. По смыслу запроса: описание скилла в SKILL.md перечисляет десятки триггеров («сделай смелее», «поправь типографику», «проверь доступность»), и среда подхватывает скилл автоматически.
3. Через хук: после каждой правки UI-файла запускается детектор и подкидывает агенту находки — даже если про скилл никто не вспоминал.

Плюс два канала вне чата, где работает тот же детектор:

• Командная строка / CI: npx impeccable detect src/ — детерминированные правила, JSON и код возврата, которым можно валить сборку.
• Расширение для Chrome: те же проверки как оверлей на любой живой странице — стейджинг, сайт конкурента, страница, которую вы никогда не откроете в редакторе.

Где работает

Поддерживаемые среды (по сайту, 14.08.2026): Claude Code, Codex CLI, GitHub Copilot, Cursor, Gemini CLI, Grok Build, Antigravity, OpenCode, Pi. CLI принимает имена провайдеров claude, codex, copilot, cursor, gemini, agents, antigravity, grok, hermes, kiro, opencode, pi, qoder, rovo-dev, trae, trae-cn, vibe и их алиасы.

Тонкости, о которых стоит знать заранее: Cursor требует канал Nightly и включённые Agent Skills в Settings → Rules. Gemini CLI — @google/gemini-cli@preview и скиллы, включённые через /settings. Codex не показывает скиллы в обычном /-пикере: нужен /skills или $, плюс отдельное одобрение хука через /hooks. GitHub Copilot подхватывает .github/hooks/impeccable.json только после коммита в дефолтную ветку.

Источник: .claude/skills/impeccable/SKILL.md (frontmatter description, разделы Core principles, Commands, Routing), reference/routing.md; impeccable.style/designing, /faq. Снято 14.08.2026.

Установка

npm-пакет impeccable — это только CLI. Сами скиллы он не содержит: при установке он скачивает бандл с impeccable.style, собранный под вашу конкретную среду и модель, и раскладывает по папкам провайдеров.

Правильный вызов

# в папке рабочего проекта
npx impeccable@latest install --providers=claude --project -y

Точный механизм: когда дефолт становится глобальным

Функция выбора scope в CLI (defaultInstallScope) работает так:

1. Если среди выбранных провайдеров есть папка харнесса в самом проекте → project.
2. Иначе если есть глобальная папка харнесса, в которой уже лежат реальные скиллы → user, то есть глобально.
3. Иначе → project.

То есть ловушка срабатывает в конкретной конфигурации: в проекте ещё нет .claude/, а в ~/.claude/skills/ уже лежат ваши скиллы. Это ровно ситуация на машине, где глобально живут consilium, generate, skill-scout. Отсюда и вердикт: без флагов не запускать никогда, потому что заранее вы этого не проверите.

Флаг -y жёстко форсит project — это, помимо --providers, вторая страховка в рекомендованной строке.

Проверка после установки

# в проекте должен появиться скилл
ls .claude/skills/impeccable/

# глобально ничего лишнего появиться не должно
ls ~/.claude/skills

Все команды CLI

Список снят из кода пакета impeccable@3.6.0, не из README. Других подкоманд нет.

Альтернативные способы установки

• Плагин Claude Code: /plugin marketplace add pbakaus/impeccable, потом /plugin.
• Универсальный инсталлер: npx skills add pbakaus/impeccable — ставит один общий билд для всех сред вместо скомпилированного под вашу.
• ZIP с сайта: распаковать в корень проекта; создаёт .cursor/, .claude/, .gemini/, .codex/, .agents/, .github/.

Проектная установка имеет приоритет над глобальной и позволяет держать скиллы под контролем версий.

Что инсталлер кладёт в проект

Артефакты, которые появятся потом — уже в ходе работы

Обновление

npx impeccable check     # отстал ли я от последнего релиза
npx impeccable update    # обновить скиллы, убрать устаревшие файлы
npx impeccable install --force   # переустановить начисто

При обновлении PRODUCT.md и DESIGN.md не трогаются. Если установленная версия старше опубликованной, загрузчик контекста сам скажет об этом директивой UPDATE_AVAILABLE при старте сессии (запрос к impeccable.style троттлится раз в сутки, повторное уведомление о той же версии — не чаще раза в неделю).

Источник: живая установка в проекте Kupol (14.08.2026), код CLI impeccable@3.6.0 (cli/bin/cli.js, cli/bin/commands/skills.mjs) с эмпирическими прогонами в изолированных окружениях, impeccable.style/faq, reference/hooks.md, reference/init.md, reference/document.md, scripts/context.mjs.

Порядок работы

Это самая важная часть и главный источник непонимания. Общее правило: сначала бриф, потом концепция, потом код, потом ревью, потом документация системы. Порядок не декоративный — он зашит в скрипты, и часть шагов физически отказывается работать, пока предыдущие не выполнены.

Шаг 0: загрузка контекста (каждая сессия)

Первое, что скилл делает один раз за сессию — запускает загрузчик контекста:

node .claude/skills/impeccable/scripts/context.mjs
# при работе по конкретному файлу или маршруту:
node .claude/skills/impeccable/scripts/context.mjs --target src/routes/pricing.astro

Скрипт находит PRODUCT.md, DESIGN.md, бриф поверхности и — на нативных платформах — платформенный справочник, а потом печатает набор директив заглавными буквами. Агент обязан им следовать и повторно скрипт не запускать.

Вот реальный вывод на проекте без PRODUCT.md, но с готовым интерфейсом (снято 14.08.2026):

NO_PRODUCT_MD: This project has no PRODUCT.md yet, but it does have an
incumbent visual implementation...

BUILD_INIT_REQUIRED: Before shape or any new-surface/redesign flow, init must
capture PRODUCT.md with the human...

SCOPED_EXISTING_ALLOWED: Narrow refinement commands may use the incumbent
implementation as authority without blocking on context setup...

EXISTING_VISUAL_SYSTEM: For refinement or extension, code and assets are
incumbent design authority...

RESOLVED_CONTEXT: { "projectRoot": "...", "productPath": null, ... }

AUTONOMY_DIRECTIVE_CHECK / SUBAGENT_AUTHORIZATION / IMAGE_TOOLS: ...

Что означают ключевые директивы:

Источник: scripts/context.mjs + живой запуск в проекте Kupol. Снято 14.08.2026.

Файлы контекста: что где лежит и кто главнее

Кто побеждает в конфликте:

• PRODUCT.md — в долговременных продуктовых решениях и голосе: платформа, аудитория, позиционирование, ограничения, доказательства, обязательства бренда.
• DESIGN.md — в визуальных: цвет, типографика, радиус, высота, поведение компонентов, правила «делай / не делай».
• Бриф поверхности — в стратегии конкретной страницы: её режим, её работа, последовательность доказательств, выбранное направление.
• Существующий код всё равно важен. Команды читают файлы проекта перед правкой и сохраняют реальные конвенции, если те сильнее или свежее документов. Устаревший DESIGN.md — сигнал обновить документ, а не разрешение игнорировать реализацию.

Где скилл ищет файлы: сначала корень проекта, затем .agents/context/, затем docs/. В монорепо каждый воркспейс сначала разрешает свои PRODUCT.md и DESIGN.md, потом пофайлово падает на корень репозитория. Границы проектов берутся из деклараций пакетного менеджера (workspaces в package.json, pnpm-workspace.yaml, lerna.json) либо из глобов projectRoots в .impeccable/config.json:

{ "projectRoots": ["docs/design/skins/*"] }

Платформа

PRODUCT.md несёт строку ## Platform. Отсутствие поля означает web.

Нативная поддержка в статусе alpha. Live-режим, детектор и хук читают браузер или парсят HTML — на нативном проекте они не работают. Мобильный веб остаётся web, а нативная обёртка вокруг сайта не делает его язык дизайна нативным.

Источник: impeccable.style/docs/context, /docs/config; подтверждено кодом scripts/context.mjs (константа FALLBACK_DIRS = ['.agents/context', 'docs'], разрешение монорепо). Снято 14.08.2026.

Маршрут A: новая поверхность или редизайн

Именно здесь работает правило «сначала PRODUCT.md». Пять шагов, каждый со своим артефактом.

node .claude/skills/impeccable/scripts/concept-seed.mjs --scope direction --mode <mode>

Маршрут B: доработка существующего

Здесь PRODUCT.md не обязателен — и это специально.

1. Загрузка контекста печатает SCOPED_EXISTING_ALLOWED: узкие команды доработки идут без блокировки.
2. Действующая визуальная власть — это код. Токены, тема, CSS, компоненты и ассеты. Отсутствие DESIGN.md само по себе не делает проект «чистым листом».
3. Скилл читает цель и хотя бы один репрезентативный источник визуальной правды, прежде чем править.
4. Дальше — нужная команда: polish, typeset, layout, adapt, harden и т. д.
5. После работы предлагается init — не как условие, а как следующий шаг.

Без аргумента

Команда /impeccable без аргумента не запускает ничего. Скилл собирает сигналы контекста:

node .claude/skills/impeccable/scripts/context-signals.mjs

и выдаёт 2–3 обоснованные рекомендации плюс полное меню. Логика рекомендаций: есть код без DESIGN.md → document; критики ещё не было → critique; в последней критике низкий счёт или есть P0/P1 → polish; правки сосредоточены в одном месте → audit/polish с точным скоупом; запущен dev-сервер → доступен live.

Источник: SKILL.md (Setup, How to design, Routing), reference/init.md, reference/new-work.md, reference/routing.md, живые запуски context.mjs и concept-seed.mjs. Снято 14.08.2026.

Все команды

23 команды, сгруппированные по категориям. Список сверен с реально установленным скиллом: pin.mjs без аргументов печатает точно этот перечень.

Плюс три служебных подкоманды, которых нет в этой таблице: hooks, doctor и pin/unpin.

Build — создание

Evaluate — оценка

Refine — доводка

Enhance — усиление

Fix — починка

Iterate — итерации

Служебные подкоманды

Источник: SKILL.md (таблица Commands), scripts/command-metadata.json, reference/*.md по каждой команде, живой вывод pin.mjs. Снято 14.08.2026.

Хуки

Хуки — автоматический прогон детектора без участия человека. Именно они делают скилл страховочной сеткой, а не инструментом, который надо вспомнить и позвать.

Что реально ставится в проект

Инсталлер пишет в .claude/settings.local.json (файл в .gitignore, поэтому хук остаётся машинно-локальным):

{
  "description": "Impeccable design detector: immediate-tier checks after
                  Edit/Write/MultiEdit on UI files, full-rule deep pass on Stop.",
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command",
          "command": "[ ! -f \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\" ] || node \"${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs\"",
          "timeout": 5,
          "statusMessage": "Checking UI changes" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command",
          "command": "... hook.mjs",
          "timeout": 30,
          "statusMessage": "Design deep pass" }] }
    ]
  }
}

Обратите внимание на конструкцию [ ! -f ... ] || node ...: если скилл удалить, хук молча ничего не делает и не ломает сессию.

Два уровня проверок

Immediate-уровень — это то, ради чего стоит прерывать правку: механическое, однозначное и дешёвое в починке на месте.

Какие файлы попадают под хук

.tsx, .jsx, .html, .vue, .svelte, .astro, .css, .scss, .sass, .less, .ts, .js. Обычные .ts и .js сканируются, но молчат, если детектор ничего не нашёл.

Серверные шаблоны (Blade, Twig, ERB, Handlebars) в базовый список не входят — их надо объявить руками:

// .impeccable/config.json
{ "detector": { "extensions": [ { "ext": ".blade.php", "engine": "html" } ] } }

Как управлять

# самый узкий игнор — конкретное значение, с причиной
node .claude/skills/impeccable/scripts/hook-admin.mjs \
  ignore-value overused-font Inter --shared \
  --reason "User confirmed Inter is intentional"

# одно правило в одном файле
node .claude/skills/impeccable/scripts/hook-admin.mjs \
  ignore-value design-system-font-size "*" --file "src/overlay/widget.js" \
  --reason "Виджет строит свою шкалу; рампа DESIGN.md описывает сайт"

Правило триажа из справочника: реальная проблема — чинить, никогда не глушить игнором. Уверенное ложное срабатывание или санкционированное исключение — поставить самый узкий игнор и раскрыть это в ответе, с доказательством в --reason. Не уверены — оставить находку и спросить одной строкой. Самообслуживание агента заканчивается на ignore-value: ignore-file и ignore-rule глушат слишком много, их только с разрешения человека.

Есть и встроенные комментарии-игноры

<!-- impeccable-disable overused-font -- exported brand doc -->
.brand { font-family: Inter } /* impeccable-disable-line overused-font */
// impeccable-disable-next-line bounce-easing: intentional bounce

Но справочник советует по умолчанию использовать конфиг-игноры: они держат все подавления в одном просматриваемом месте. Инлайн — только когда исключение должно уехать вместе с файлом (экспортированный standalone-документ, HTML для рассылки).

Когда оставлять, когда убирать

Другие среды

Источник: reference/hooks.md, scripts/hook.mjs, scripts/hook-lib.mjs (константа IMMEDIATE_TIER_RULES и комментарии к ней), реальный .claude/settings.local.json проекта Kupol. Снято 14.08.2026.

Детектор

Детерминированный сканер по файлам и URL. Это самая «твёрдая» часть скилла: не мнение модели, а правила.

# локально установленной копией
node .claude/skills/impeccable/scripts/detect.mjs --json src/

# или через npm-пакет
npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect https://example.com

Коды возврата: 0 — находок нет · 2 — находки есть · 1 — команда упала. Это делает использование в CI прямолинейным: валить job на двойке, дальше решать, чинить или добавить узкий игнор.

Три режима работы

• HTML-файлы — статический анализ HTML/CSS, включая подключённые локальные стили. Полноценный: понимает CSS-переменные, селекторы и вычисленный контраст.
• Файлы фреймворков (CSS, JSX, TSX, Vue, Svelte, Astro, CSS-модули) — проверки по исходному тексту, сопоставление по регулярным выражениям.
• URL — полный рендер в браузере (Puppeteer), определяется автоматически по http(s):// и file://.
• stdin — если передать текст в пайп без цели, сканируется он: cat component.css | npx impeccable detect.

Управление игнорами из CLI

Тот же конфиг, что читает хук, — им можно управлять и без агента:

npx impeccable ignores list
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-value design-system-color "#ff00aa" --reason "Campaign accent"
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-rule side-tab
npx impeccable ignores remove-value design-system-color "#ff00aa"
npx impeccable ignores add-file "src/private-experiment/**" --local

Правило приоритета: предпочитайте игнор по значению. Шрифты, цвета, радиусы и параметры движения обычно надо подавлять поточечно, а не правилом целиком — так правило остаётся полезным во всех остальных местах. Игнор по значению с "*" разрешён только в связке с --file, иначе один намеренно экспериментальный файл научит весь проект, что любой недокументированный цвет допустим.

59 правил

Полный список идентификаторов на 14.08.2026 (пригодится, чтобы точечно ставить игноры):

ai-color-palette · all-caps-body · aphoristic-cadence · blinking-cursor · body-text-viewport-edge · border-accent-on-rounded · bounce-easing · broken-image · clipped-overflow-container · codex-grid-background · content-hidden-at-rest · cramped-padding · cream-palette · dark-glow · design-system-color · design-system-font · design-system-font-size · design-system-radius · edge-flush-cards · em-dash-overuse · extreme-negative-tracking · first-viewport-column-overflow · flat-type-hierarchy · gpt-thin-border-wide-shadow · gradient-text · gray-on-color · heading-rhythm · hero-eyebrow-chip · icon-tile-stack · image-hover-transform · italic-serif-display · justified-text · kicker-above-heading · layout-transition · line-length · low-contrast · marketing-buzzword · marquee · monotonous-spacing · nested-cards · numbered-section-labels · oversized-h1 · overused-font · pulsing-dot · radial-halo · radial-spotlight-glow · repeated-container-text · repeating-stripes-gradient · script-error · shape-assembled-illustration · side-tab · skipped-heading · text-occlusion · theater-slop-phrase · tight-leading · tiny-text · undersized-ui-text · wide-tracking

Названия говорят сами за себя: cream-palette и ai-color-palette ловят фирменные нейросетевые палитры, gpt-thin-border-wide-shadow и codex-grid-background — узнаваемые машинные приёмы, kicker-above-heading — «надзаголовок», который в скилле помечен как безусловный бан.

impeccable detect: DEGRADED - HTML parser modules unavailable
(htmlparser2, css-select, css-tree, domutils).
Falling back to regex matching. Custom properties, selector matching and
computed contrast are NOT evaluated; findings are an undercount, not a
clean bill of health.

Advisory-правила

Часть правил «совещательные»: детектируются и показываются отдельной секцией, но никогда не считаются провалом и не меняют код возврата, чтобы не блокировать автоматику. Хук по умолчанию пропускает их полностью — модель не должна получать нагоняй за вкусовое решение, которое человек мог принять сознательно. Вернуть: .impeccable/config.json → { "detector": { "advisoryRules": "include" } }. На 14.08.2026 в advisory один пункт: em-dash-overuse.

Источник: node detect.mjs --help, scripts/detector/registry/antipatterns.mjs, scripts/detector/engines/static-html/detect-html.mjs, scripts/hook-lib.mjs, живой прогон в проекте Kupol; impeccable.style/docs/detector, /docs/config. Снято 14.08.2026.

Практические сценарии

Сценарий 1. Аудит чужого интерфейса

Задача: пришёл клиентский сайт или чужой репозиторий, надо быстро понять, насколько там плохо, и получить список работ.

1. Ничего не инициализируем. PRODUCT.md для оценки не нужен: директива SCOPED_EXISTING_ALLOWED разрешает узкие команды без него.
2. Механика: /impeccable audit <путь или область> — пять измерений, итог из 20, находки P0–P3 с локациями и стандартами WCAG. Ничего не чинит.
3. Дизайн: /impeccable critique <путь> — эвристики Нильсена, специфичность дизайна, когнитивная нагрузка, персоны. Отчёт сохранится в .impeccable/critique/.
4. Проверьте, что критика прошла честно: в шапке отчёта должно быть Method: dual-agent. Если стоит ⚠️ DEGRADED: single-context — обе оценки крутились в одном контексте и B «заякорила» A.
5. Живой сайт вместо кода: npx impeccable detect https://example.com и второй проход мобильным вьюпортом: --viewport 390x844.
6. На выходе обе команды дают план: список команд в порядке приоритета, заканчивающийся polish.

Сценарий 2. Сделать концепцию с нуля

Задача: новый лендинг или новый продукт, дизайна ещё нет.

1. /impeccable init — интервью и PRODUCT.md. Приготовьтесь отвечать про пользователя, механизм продукта и что нельзя нарушать. Про цвета не спросят — это нормально.
2. Опционально /impeccable shape <поверхность>, если нужен согласованный бриф до кода.
3. Дальше — обычный запрос: «сделай главную страницу». Скилл сам зайдёт в new-work: выведет семь визуальных систем из мира аудитории, бросит кубик concept-seed.mjs, раздаст челленджеров.
4. Откроется страница выбора в браузере. Ваша работа — выбрать карточку. Есть «тихая дверь» (категорийный стандарт, честно сыгранный) и переброс с регистрами safer/bolder. Пользователь может перебрасывать свободно; агент — только по названной фактической причине, вкус причиной не считается.
5. Сборка. При buildPath: comp сначала генерируется картинка-эталон, потом код воспроизводит её почти попиксельно; допускаются ровно три послабления — шрифты (ближайшее доступное начертание), иконки и настоящие дефекты самой картинки (например, опечатки).
6. Финиш. Один батч скриншотов (десктоп + мобильный), одна пачка правок, максимум ещё один раунд. Потом impeccable-finish-reviewer и impeccable-documenter, который запишет DESIGN.md по факту собранного.

Сценарий 3. Довести существующий экран

Задача: экран собран, работает, но выглядит недоделанным.

1. Если есть свежая критика — polish сам подтянет её как бэклог: critique-storage.mjs latest "<target>". Если нет, начните с /impeccable critique <экран>, чтобы у доводки был список.
2. /impeccable polish <экран>. Команда попросит два уточнения: планка качества и ограничения по срокам.
3. Порядок починки задан и его стоит знать, чтобы не удивляться: сначала сломанные задачи и потеря данных, потом отсутствующие состояния (loading, empty, error, success, disabled, permission), потом поток/иерархия/адаптив/дрейф системы, потом визуал и моушн, потом чистка кода.
4. Если проблема узкая — берите точечную команду вместо polish: typeset (типографика), layout (структура и ритм), colorize (цвет), clarify (текст), adapt (мобильный), harden (реальные данные и i18n).
5. Проверка на подмену: если polish начал предлагать «а давайте вообще переделаем» — он обязан сказать это прямо и порекомендовать редизайн, а не протаскивать замену под видом доводки. Это в справочнике зафиксировано.

Сценарий 4. Сделать смелее / тише

Задача: секция выглядит пресно, либо наоборот — кричит.

1. Сначала проверьте, где вы находитесь. Если прямо сейчас открыт раунд выбора направления, слова «смелее»/«тише» означают регистр переброса, а не команду. Если поверхность уже выпущена — это команда.
2. /impeccable bolder <секция> или /impeccable quieter <секция>.
3. Назовите скоуп буквально. «Только героический блок, остальное не трогать» — это исполняемая инструкция, а не пожелание.
4. Чего ожидать от bolder: не новых эффектов, а подтягивания секции до выразительности, которую соседние блоки уже используют — в словаре существующей системы. Если системе реально не хватает средств, команда обязана остановиться и спросить, назвав конкретное добавление.
5. Чего ожидать от quieter: для Persuade/Experience — сдержаннее палитра, больше воздуха, драма уменьшается, но точка зрения остаётся. Для Operate/Read — меньше фоновых акцентов, площе карточки, меньше цвета и движения.
6. Если хочется «вау» — это не bolder, а overdrive. Но помните: overdrive обязан сначала предложить, а не сразу делать.

Сценарий 5. Итерации прямо в браузере

Задача: хочется покрутить варианты одного блока вживую, а не описывать словами.

1. Поднимите dev-сервер проекта. Если дефолтный порт занят — приложение, скорее всего, уже запущено; пробейте URL, а не поднимайте второй сервер.
2. /impeccable live. Первый раз пройдёт разовая настройка: .impeccable/live/config.json и проверка CSP.
3. Если в проекте есть CSP — скилл покажет точный диф и спросит разрешение пропатчить конфиг (патч под NODE_ENV === "development"). Откажетесь — пикер не загрузится, пока не добавите http://localhost:8400 в script-src и connect-src вручную.
4. В браузере выберите элемент, выберите действие, нажмите Go. Можно рисовать аннотации поверх элемента — тогда агент получит скриншот с ними.
5. Варианты подменяются через HMR. Принимаете один — он записывается в настоящий исходник.
6. Прервалось? Не гадайте: live-status.mjs и live-resume.mjs. Журнал в .impeccable/live/sessions/ — канонический, он переигрывает неподтверждённую работу после перезапуска.

Источник: сведение reference/audit.md, critique.md, polish.md, bolder.md, quieter.md, new-work.md, live.md, live-setup.md. Снято 14.08.2026.

Ограничения и грабли

Что скилл не умеет

• Не про бэкенд и не про не-UI задачи. Записано в описании явно.
• Live-режим и детектор — только веб. На ios/android/adaptive браузерный оверлей и HTML-движок правил не применимы; для нативных платформ у ревьюера единственным «фильтром халтуры» остаётся его собственная проверка, и в пакет ему прямо пишут, что детектор не запускался.
• audit и adapt — только веб, с отдельными нативными маршрутами.
• Не рисует в Figma и не читает макеты. Работает с кодом и браузером.
• Ревьюер не имеет браузера. Скриншоты, которые ему не передали, — это проверки, которые он не сможет провести.

Где деградирует

1. Детектор без HTML-парсеров

Главная и самая тихая проблема — подробно разобрана в разделе Детектор. Коротко: без htmlparser2, css-select, css-tree, domutils сканер молча падает на регулярки, не проверяет CSS-переменные, селекторы и вычисленный контраст, и занижает счёт. Сообщение уходит в stderr. На такой результат нельзя опираться как на полную картину.

2. Критика без субагентов

Если в среде нет инструмента субагентов, обе оценки идут в одном контексте, и детерминированные находки «якорят» дизайнерское суждение. Формально это допустимо, но отчёт обязан начинаться с баннера ⚠️ DEGRADED: single-context (<причина>). Молчаливо деградировавшая критика в справочнике названа проваленной критикой.

3. Финишное ревью без субагентов

Финиш-ревьюер должен запускаться с чистым контекстом. Ревьюер, унаследовавший переписку сборки, наследует и её рамку, и её оптимизм. Подмена на внутрипоточный проход допустима только когда субагентов нет вообще, и она должна быть раскрыта одной строкой.

4. Страница выбора направления в песочнице

serve-question.mjs поднимает локальный HTTP-сервер. Среда с песочницей шелла не сможет забиндить порт, и первая попытка сгорит впустую. Скилл советует запускать страницу через наименее ограниченный доступный путь. Если страница закрылась без ответа (exit 4), решение один раз переспрашивается структурированным вопросом; нет ответа и там — работа идёт с назначенным направлением, а сделанные допущения проговариваются.

5. Дрейф артефактов

Файлы, написанные старой версией скилла, могут содержать поля, которые уже никто не читает, или не иметь полей, которые теперь ожидаются. Диагностика — /impeccable doctor. Проверка при загрузке дешёвая и троттлится раз в неделю на проект; отключается через "stalenessCheck": false в .impeccable/config.json или IMPECCABLE_NO_STALENESS_CHECK=1.

Организационные грабли

Четыре ошибки применения — от самих авторов

На сайте есть раздел «чего избегать», и он честный:

1. Запускать impeccable вместе со скиллом frontend-design от Anthropic. Причина не в том, что второй реже обновляется. Два скилла с разными дизайн-словарями сталкиваются и взаимно гасятся. Выбрать один.
2. Закреплять все команды. Пин возвращает /audit, /polish, /critique как ярлыки. Закрепите всё — и заново взорвёте /-меню, которое консолидация версии 3.0 вычистила. Две-три ежедневные — норма.
3. Пропускать init. Команды работают и без PRODUCT.md/DESIGN.md, но сваливаются к дженерик-SaaS-паттернам. Формулировка авторов: если impeccable даёт общие советы, дизайн-контекст обычно отсутствует, слишком расплывчат или устарел.
4. Относиться к нему как к линтеру. Это не валидатор, а мнящий партнёр. Возражайте с аргументом — он пойдёт навстречу. Игнорируйте мнение без аргумента — результат станет хуже, а не лучше.

Философские ограничения, о которых стоит знать

Скилл довольно жёстко предписывает вкус, и это иногда конфликтует с брифом. Правило разрешения конфликта: бриф побеждает. Закреплённые эстетики, эпохи, материалы, шрифты и палитры соблюдаются, даже если противоречат предупреждению о «затасканном паттерне». Перенаправление внятного брифа в сторону собственного вкуса модели названо провалом.

При этом список «дефолтов, которые означают, что вы перестали искать» существует и включает популярные шрифты (Fraunces, Playfair Display, Cormorant, Space Grotesk, IBM Plex, Inter-as-display, DM Sans, Outfit, Plus Jakarta Sans и другие). Назвать один из них можно, но нужна причина, которую не удовлетворит никакой другой шрифт — и «книжному сайту нужна антиква» такой причиной не считается.

Источник: SKILL.md, reference/critique.md, new-work.md, doctor.md, audit.md, adapt.md, scripts/detector/engines/static-html/detect-html.mjs, проверка структуры проекта Kupol. Снято 14.08.2026.

Словарь терминов

skill

Скилл — папка с SKILL.md и вспомогательными файлами, которую агентная среда подгружает по имени или по смыслу запроса.

PRODUCT.md

Правда о продукте: пользователи, задача, позиционирование, ограничения, платформа. Пишется командой init. Не содержит визуальных решений.

DESIGN.md

Визуальная система: токены во frontmatter плюс проза. Пишется document или на финише новой работы. Формат совместим с Google Stitch.

surface

Поверхность — конкретный экран, маршрут или артефакт. Стратегия, относящаяся только к одной поверхности, живёт в «брифе поверхности», а не в общих файлах.

surface brief

Бриф поверхности — маленький файл со стратегией одного маршрута: скоуп, режим посетителя, аудитория, задача, доказательства, выбранное направление, нерешённые вопросы.

mode

Режим посетителя. Что означает успех на этой поверхности. Четыре: Persuade, Operate, Read, Experience. Выбирается по поверхности, а не по продукту: лендинг инструмента — всё равно Persuade, документация модного дома — всё равно Read.

Persuade

Посетитель решает и действует, дизайн — это и есть продукт. Лендинги, маркетинг, прайсинг.

Operate

Посетитель выполняет задачу. Приложения, дашборды, редакторы, админки, настройки. Сканируемость и привычные аффордансы важнее самовыражения.

Read

Посетитель что-то понимает. Документация, статьи, гайды, чейнджлоги.

Experience

Посетитель внутри самой работы. Портфолио, галереи, витрины. Интерфейс отступает.

new-work

Справочник и процедура создания новой поверхности или замены визуального мира. Ключевой файл всего конвейера.

craft floor

«Пол ремесла» — минимальная планка качества: контраст, глубина, отступы, типографика, движение, состояния, оформление браузерных поверхностей (выделение текста, каретка, скроллбары, фокусные кольца). Грузится непосредственно перед правкой UI.

refinement / redesign

Доводка сохраняет идентичность; редизайн заменяет её. Промежуточного «полирнём то, что решили выбросить» не существует.

incumbent

Действующий, унаследованный. «Incumbent visual system» — визуальная система, которая уже живёт в коде и является дизайн-властью.

direction round

Раунд направлений — момент выбора концепции. Показывается страница с карточками; пользователь фиксирует одну.

the roll

«Бросок» — concept-seed.mjs случайно назначает, какое направление собирать. Механизм против схождения всех прогонов к категорийному дефолту.

world / deck

«Мир» — полная графическая система со своими законами, отрецензированная человеком. «Колода» — каталог таких миров, на 14.08.2026 одобрено 188.

challenger

Челленджер — мир из колоды, который соревнуется с назначенным направлением. Вердикты: wins (побеждает по обеим осям и забирает сборку), competitive (держит одну ось, остаётся полноценной альтернативой), declined (проигрывает обе, но его дисциплина всё равно донорски поднимает назначенное направление).

seed key

Ключ броска. Печатается скриптом и записывается в контракт направления; воспроизводит весь бросок, включая все раунды перебросов.

standing exit

«Тихая дверь» — постоянно доступная альтернатива: категорийный стандарт, сыгранный честно, без иронии. Дверь пользователя, не агента; рекомендовать её нельзя.

re-roll

Переброс. Регистры: plain (свежая раздача), safer (привычный регистр), bolder (только чужие формы, с полной отдачей).

comp

Комп — сгенерированная картинка-эталон первого экрана. При buildPath: comp код обязан воспроизвести её почти попиксельно.

comp-led / code-led

Режим сборки: от картинки-эталона или сразу в код. Записывается как buildPath в .impeccable/config.json.

direction contract

Контракт направления — комментарий в начале артефакта из блоков THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM, FINISH. Должен пережить продакшн-сборку.

finish review

Финишное ревью субагентом impeccable-finish-reviewer со свежим контекстом.

detector

Детектор — детерминированный сканер на 59 правил.

anti-pattern

Антипаттерн — то, что ловит детектор.

immediate tier

Немедленный уровень — 14 правил, ради которых стоит прерывать правку. Остальное откладывается на глубокий проход.

deep pass

Глубокий проход — полный набор правил по всем тронутым за сессию файлам, один раз на событии Stop.

advisory

Совещательное правило: показывается отдельно, никогда не считается провалом, не меняет код возврата.

slop

Халтура, машинный шлак. В скилле — узнаваемые признаки, что интерфейс не собран, а «сложен из кусков».

drift

Дрейф. Дизайн-системный: код разошёлся с токенами. Схемы: артефакт написан старой версией. Правды: документ больше не описывает код.

P0–P3

Severity: P0 блокирует задачу — чинить немедленно; P1 серьёзно мешает — до релиза; P2 раздражает, но обходится; P3 полировка. Подсказка: «обратился бы пользователь в поддержку?» Да — минимум P1.

heuristics

10 эвристик юзабилити Нильсена, каждая 0–4. Честная оценка: большинство реальных интерфейсов набирают 20–32 из 40.

harness

Среда исполнения агента: Claude Code, Codex, Cursor, GitHub Copilot. Поведение хуков и субагентов зависит от неё.

hook

Хук — команда, которую среда запускает на событии (после правки файла, при остановке).

degraded

Деградированный режим: часть механизма недоступна, работа продолжается ослабленной. Должно быть объявлено, а не замолчано.

live mode

Live-режим — выбор элементов в браузере и генерация вариантов с горячей подменой.

pin

Закрепление — создание ярлыка /<command>, чтобы звать команду без префикса.

Источники и расхождения

Что использовалось

Где сайт разошёлся с кодом

Во всех случаях в руководстве описано поведение кода — сайт может отставать от релизов.

Что проверено живьём

• Вывод context.mjs на проекте без PRODUCT.md — директивы приведены дословно.
• Отказ concept-seed.mjs без PRODUCT.md: «the dice stay in the cup until product truth exists».
• Сообщение DEGRADED при отсутствии HTML-парсеров.
• Список 23 команд из pin.mjs — совпал с таблицей в SKILL.md.
• Список 59 правил детектора из реестра антипаттернов — совпал с числом «59 deterministic rules» на сайте.
• Содержимое .claude/settings.local.json, поставленного инсталлером.
• Следы глобальной установки в ~/.agents/skills и ~/.cursor/agents с меткой времени голого прогона инсталлера.
• Логика defaultInstallScope в коде CLI плюс прогоны установки в изолированных HOME и рабочих папках.
• Отсутствие .claude/agents/ после проектной установки — поставляемые субагенты в проект не попали.

Чего достать не удалось

• CHANGELOG.md и CONTRIBUTING.md в репозитории отсутствуют — это подтверждённое отсутствие, а не «не нашлось». Роль CONTRIBUTING выполняет docs/DEVELOP.md; чейнджлог живёт только на сайте, страницей /changelog.
• Тела release notes с GitHub не выгружались — только имена тегов.
• Интерактивные демо на главной сайта (раздача миров через roll API, переключатель вариантов) сняты в состоянии первой отрисовки; варианты, подгружаемые по клику, в текст не попали. Переводимого текста там практически нет.
• sitemap.xml сайта неполон (35 URL из 58 найденных); llms-full.txt и sitemap-index.xml не существуют — отдают catch-all вместо файла.