Impeccable：给 AI 编码代理补设计规则

用 Claude Code、Cursor 这类工具搭前端界面，出来的页面往往长得很像：同一套 SaaS 模板的配色，Inter 字体铺满全站，卡片里套着卡片，彩色背景上压一层灰字，标题上方顶着一个圆角方块图标。模型训练时见过大量同类模板，不给约束就会把这些痕迹一路带进新项目。Impeccable 插手的正是这一步，把一套设计判断塞进编码代理的工作流里。

Impeccable 给 AI 编码代理补上前端设计规则，由 JavaScript 与 Rust 写成，装进 Claude Code、Cursor 等工具后，产出 PRODUCT.md 与 DESIGN.md，并驱动浏览器里的实时改版。

它在仓库里的形态是一个 skill 加一个自包含 engine 二进制。skill 负责给你和 AI 一套共同的设计词汇，engine 负责跑检测规则，不需要 LLM，也不需要 API key。README 开头的表述是：1 skill、24 commands、live browser iteration、61 deterministic detector rules。仓库地址是 github.com/pbakaus/impeccable，许可证 Apache-2.0，主要语言 JavaScript，仓库里还有约 25% 的 Rust。

五分钟先跑通

skill 本身不带运行时。每份 skill 副本里带一个小启动器（scripts/impeccable，Windows 上另有 impeccable.cmd），它去调 engine——一个自包含二进制，要么和启动器放在一起，要么首次运行时下载到 ~/.impeccable/bin/。Node 只在用 npx impeccable 安装器时才涉及，它只是同一个二进制外面的壳。

推荐的方式是从项目根目录跑 CLI 安装器：

npx impeccable install

它会列出检测到的 harness 目录或已安装 CLI（例如 ~/.claude、~/.codex、~/.grok、~/.hermes、~/.veto，或项目内的 .cursor），让你保留检测结果或自己挑 provider，再问你装到当前项目还是全局。想在脚本里跳过这两步，用 --providers=claude,codex,cursor,grok,hermes,veto 和 --scope=project|global。装完记得重载你的 AI 工具。

装完之后，在你的 AI 编码工具里初始化：

/impeccable init

已有安装要刷新，跑 npx impeccable update。Codex 用户在装完或更新后打开 /hooks，在提示时批准项目 hook——Codex 按 hook 定义跟踪信任，更新动了 .codex/hooks.json 就可能需要重新批准。Grok Build 用户需要先给项目文件夹信任（/hooks-trust，或用 --trust 启动），.grok/hooks/ 下的脚本才会跑。

不用 npx 也能装。想通过 Git 管理版本、把 skill vendoring 进仓库的团队，可以把仓库加成 submodule：

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
git add .gitmodules .impeccable .claude .cursor
git commit -m "Add Impeccable skills"

provider 按项目需要选，可选值包括 claude、cursor、gemini、codex、github、grok、hermes、opencode、pi、qoder、trae、trae-cn、rovo-dev、vibe、veto。这条命令从 .impeccable/dist/universal/ 里链接各个 skill 目录，已经存在的真实 skill 目录不动，除非加 --force。之后更新用：

git submodule update --remote .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

在 VS Code 里用 GitHub Copilot 的话，还有插件方式：

code --install-extension renaissance-geek.impeccable

要求 VS Code 1.109.3 以上、有 Copilot Chat 访问权限、工作区可信。这是 skill-only 扩展，不装自动 hook。

跑通之后你会得到什么

• 项目根目录多一份 PRODUCT.md。/impeccable init 会检查项目，只问产品事实里真正缺的部分，然后写下受众、目的、运行环境、约束、语气与证据。
• 项目根目录多一份 DESIGN.md。/impeccable document 能从已有代码生成它；访客模式和视觉方向留到每个面（surface）单独决定，既有的和新建的视觉系统分开记录。
• ~/.impeccable/bin/ 下多一份 engine 二进制缓存。
• 在 Claude Code、Cursor、Codex、GitHub Copilot、Grok Build 上，还会往当前项目写一份 provider 原生的 hook manifest。
• Veto 走的是另一条路：它拿到 ~/.veto/skills/ 下的打包 skill，不跑 Impeccable 的原生编辑 hook。

接下来就能对着具体页面下命令了。README 里给的例子：

/impeccable audit blog           # 审计 blog 首页 + 文章页
/impeccable critique landing     # UX 设计评审
/impeccable polish settings      # 上线前最后一轮
/impeccable harden checkout      # 补错误处理与边界情况

也可以直接用描述：/impeccable redo this hero section。

主要功能

一次性初始化。 /impeccable init 检查项目，只问产品事实里真正缺的部分，把受众、目的、运行环境、约束、语气与证据写进 PRODUCT.md。这一步让后续命令知道这些事实，而不把它们和表层视觉方向混在一起。

24 个命令。 全部通过 /impeccable 访问，是一套你和 AI 共用的设计词汇。列表包括 craft、init、document、extract、shape、critique、audit、polish、bolder、quieter、distill、harden、onboard、animate、colorize、typeset、layout、delight、overdrive、clarify、adapt、optimize、live、generate。分工上，shape 在写代码前做 UX/UI 规划，critique 做层级、清晰度、情感共鸣层面的评审，audit 跑无障碍、性能、响应式这类技术检查，polish 是上线前的最后一轮。bolder 和 quieter 是一对，一个放大偏沉闷的设计，一个收敛过头的设计。

61 条确定性检测规则。 CLI 和浏览器扩展跑这些规则，不需要 LLM，也不需要 API key。规则之外还有只走 LLM 的 critique 检查。

live 模式与 generate。 /impeccable live 进入视觉变体模式，在浏览器里对元素逐个迭代；/impeccable generate 不用手动挑元素，直接给目标元素生成变体。4.2.3 版本加了 monorepo 支持，post-edit、before-edit、Stop 检查会按目标 app 的 DESIGN.md 走，找不到才回退到仓库级配置，不会串到兄弟目录。

pin 快捷方式。 /impeccable pin <command> 把命令拆成独立快捷方式，比如 pin audit 会创建 /audit。

反模式清单。 skill 里写明了要避开什么：不用 Arial、Inter、系统默认这类被过度使用的字体；不在彩色背景上放灰字；不用纯黑或纯灰，一律带色调；不把什么内容都包进卡片，也不在卡片里套卡片；不用 bounce 或 elastic 缓动。

透明背景插图。 skill-v4.3.0 起，Impeccable 能生成真正透明背景的插图和物件，可以直接压在你自己的颜色与纹理上；照片和整幅画面保留原背景。同版本接入 GPT Image 2.5。

Git submodule 管理。 适合不想每次手动跑命令或下 zip 的团队，把仓库 vendoring 进项目，用 Git 更新。

常用参数与配置

安装器主要吃两个开关。--providers= 指定装给哪些工具，可用值有 claude、codex、cursor、gemini、github、grok、hermes、opencode、pi、qoder、trae、trae-cn、rovo-dev、vibe、veto；--scope=project|global 决定装进当前项目还是全局。

npx impeccable link 走的是另一套参数：--source= 指向 vendoring 进来的仓库目录（例如 .impeccable），--providers= 同上，--force 才会覆盖已存在的真实 skill 目录。

检测单个页面用 impeccable detect <url>。

配置文件方面，README 明确提到的有两份 Markdown：PRODUCT.md 记产品事实，DESIGN.md 记视觉系统，后者可以按 app 分开，monorepo 里就靠这个区分。仓库里没有说明这两份文件的字段级 schema，具体写什么由命令生成。

结果在哪里看

三处。

• 项目根目录的 PRODUCT.md 与 DESIGN.md，都是 Markdown，可以直接读和改。
• ~/.impeccable/bin/ 下的 engine 二进制缓存，以及安装时写入的 hook manifest 文件（Claude Code、Cursor、Codex、GitHub Copilot、Grok Build 走这条）。
• 终端输出：安装器列出检测到的 harness、provider 选择结果和安装范围；impeccable detect <url> 把检测结果打在终端。

live 模式的结果在浏览器里看，改的是当前页面元素。仓库里没有说明是否导出改动记录或报告文件。

实际使用中的坑

仓库开放着 59 个 Issue，下面几条是评论数较多的。

Windows cmd.exe 下带 & 的 URL 会挂。 跑 impeccable detect https://example.com?foo=1&bar=2，cmd.exe 会把 & 当命令分隔符，报「not recognized as an internal or external command」。这条已经解决。

安装包被多家杀软报毒。 ESET NOD32 持续把 Impeccable 的 Windows 可执行文件报成 Win64/Agent.BYG 木马变种，这条已经解决。另一条还开着：Windows Defender 把 C:\Users\<用户名>\.impeccable\bin\0.1.0\impeccable.exe 报成 Trojan:Win32/Wacatac.B!ml。

全新机器上安装报 invalid zip data。 npx impeccable install 在干净环境下失败，提示 Download failed: invalid zip data。根因是 downloadFile 只跟随一次重定向。这条已经解决。另外 skill bundle 解压前的完整性校验也是社区提出来后才补上的——npx impeccable install / update 会从 impeccable.style 下 zip 解压，并把 skill 脚本和 harness hook manifest 写进你的项目，早期没有校验步骤。

装上了但后面不跑。 有一条还开着的 Issue 描述：4.2.1 版本能激活，但激活之后没有东西真正运行——35 个引用文件读了 0 个，55 次 launcher 调用全被拒。发帖人说 #738 已经完整修好了 #736，这条是针对 4.2.1 的后续反馈。目前未解决。

同类项目对比

Impeccable 的覆盖面只到前端设计。如果你真正缺的是多个编码智能体之间的调度与协同，或者需要在不同设备上接续同一个任务，Impeccable 帮不上忙，ECC 与 Paseo 面向的是这一层，放在这里只是给同类选型的读者一个参照。反过来，如果团队已经有成熟的设计规范，Impeccable 的 61 条规则里有一部分会跟你们自己的约定冲突，这时它的价值主要集中在前端那几个通用反模式上。

合规边界

impeccable detect <url> 会去访问目标页面并跑检测，Issue 里也提到过它会弹出可见浏览器窗口或黑窗口。用的时候只对自有资产或已获明确授权的目标跑。拿它去扫描不归你管的线上站点，可能违反对方的服务条款，也可能带来法律层面的风险。live 模式同理，它直接改动浏览器里的页面元素。

什么情况下别用它

不写前端、只做后端服务、脚本或数据处理的仓库，装了也用不上，那 24 个命令全部围绕界面。

团队里没有人用 AI 编码工具，界面靠手写 CSS 和设计稿落地，这套 skill 没有落点。

不想让项目里多出 PRODUCT.md、DESIGN.md，也不想让安装器往 .claude、.cursor、.codex 这类目录写 hook manifest，那就别装——这些文件是安装的一部分。

在 Windows 上同时对杀软误报零容忍，得等 Windows Defender 那条 Issue 收掉，或者先接受把它加进白名单。

只想要一份静态的设计规范文档、不打算让 AI 参与改页面的，用 Impeccable 属于杀鸡用牛刀。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。