Impeccable#

给你的编程智能体（coding agent）的设计词汇表。用 polish 和 bolder 来引导方向，用 critique 和 audit 来做审查，在交付之前抓出「AI 味」（AI slop）。

在你的项目根目录运行：

npx impeccable install

重新加载你的编程工具，然后在智能体中运行 /impeccable init（在 Codex 上是 $impeccable init）。

支持 Claude Code、Cursor、Codex CLI、GitHub Copilot、Devin、Replit Agent、Gemini CLI、Grok Build、OpenCode、Google Antigravity、Kiro、Trae、Rovo Dev、Qoder、Mistral Vibe、Pi、Hermes Agent、DeepSeek Harness 和 Veto。完整文档见 impeccable.style/docs。

不用 Impeccable 与用 Impeccable

同一个模型（Fable 5.1），同一份需求说明：利古里亚海岸上一座有十四个房间的家庭旅馆。不用 Impeccable 时，它造出的是那种「有品位的默认款」：奶油色页面、细衬线体、斜体点缀、胶囊按钮。用它时，整页围绕一幅画面来构建：夜色中的房子，从水面上看过去。

想了解一个完整项目，见 Neo Mirai 案例研究：一个会议网站，从设计稿一路做到上线的页面。

为什么#

所有东西都用 Inter。紫到蓝的渐变。卡片里套卡片，彩色背景上的灰色文字，每个标题上方都有一块圆角方形图标。让智能体做一个页面而不给任何其他指导，这些东西会在不同模型、不同项目里反复出现。

为你的需求提供词汇。「让它更抓眼」等于让智能体去猜。/impeccable bolder the pricing cards 会加载一份专为这一个动作写的攻略，并把目标对准一个具体对象。

一个审阅者。critique 依据可用性准则为设计打分，并排出先修什么。audit 检查无障碍、性能、主题化和响应式行为，发现的按 P0（阻断）到 P3（打磨）排序。

一个「AI 味」探测器。62 条确定性规则会标记上面那些套路，以及拥挤的内边距、跳级标题之类质量问题。不用 LLM，不需要 API key。

Impeccable 在已存在的界面上最强：把指向一个页面或组件，然后迭代。它也能建新页面；参见「构建新东西」了解如何把这个更难的模式用到极致。开始的时候，先挑一个组件：

/impeccable critique the pricing cards

工作原理#

每个项目运行一次 /impeccable init。它会读取你的代码，只问它无法推断的东西（产品面向谁、需要做什么、有哪些约束），然后写出 PRODUCT.md。之后的每条命令都会读它。运行 /impeccable document 可以把现有的视觉体系记录进 DESIGN.md，让改动保持在品牌上。更多关于上下文文件的内容见后面的说明。

然后，说出一个命令和一个目标：

/impeccable critique the onboarding flow
/impeccable quieter the landing page
/impeccable polish settings
/impeccable harden checkout

或者直接描述你想要什么：/impeccable redo this hero section。目标越窄，结果越好；仔细审查一个区块，胜过粗略浏览整个页面。常用命令可以用 /impeccable pin audit 固定下来，这样就有 /audit 作为独立快捷方式。

24 条命令#

引导（Steer）

• bolder 放大过于保守的设计 · quieter 收敛过于张扬的设计 · distill 去除页面不需要的东西 · colorize 给灰色的界面带来色彩 · typeset 修正字体、层级和字号 · layout 修正间距与节奏 · animate 添加转场与交互反馈 · delight 添加个性 · overdrive 追求着色器、弹簧物理和滚动驱动的效果

审查（Review）

• critique 是带评分的 UX 审查 · audit 是技术质量报告

收尾（Finish）

• polish 是交付前的最后一轮 · harden 覆盖错误、国际化、溢出和边界情况 · clarify 重写不清楚的文案 · adapt 处理屏幕尺寸和设备 · optimize 修正加载与渲染性能 · onboard 设计首次运行流程和空状态

实时迭代（Iterate live）

• live 让你在浏览器里选中一个元素并在变体之间循环 · generate 为指定元素生成变体，无需手动挑选

规划与设置（Plan and set up）

• shape 在写代码之前规划 UX · init 写出 PRODUCT.md · document 写出 DESIGN.md · extract 把重复出现的模式抽取进你的设计系统

第 24 条命令 craft，是普通构建请求的已弃用别名。在智能体中只输入 /impeccable 即可查看列表。每条命令都有自己的页面：impeccable.style/docs。

在 Codex 上，打开 /skills 或输入 $impeccable，而不是斜杠命令。

实时模式（Live mode）#

/impeccable live 会带着一个浮层打开你正在运行的开发服务器。选中一个元素，选一个方向，Impeccable 就会就地热替换变体。接受某个变体后，它会被写回你的源码。它支持 Vite、Next、SvelteKit、Astro、Nuxt 和纯 HTML。就在浏览器里迭代。

实时模式只编辑本地检出；不要把它注入到已部署的站点，也不要为了让它工作而削弱生产环境的 CSP。应用文案编辑时，会用你的权限运行 package.json 里可选的 impeccable:manual-edit-validate 脚本，所以在不熟悉的仓库使用实时模式之前请先审查它。

三种运行探测器的方式#

在你的智能体里。 设计钩子会扫描智能体编辑的每一个 UI 文件，并在智能体宣布完工之前把发现反馈回去。大多数「AI 味」都是在这里被抓住的：没有这个钩子，探测器只会在有人记得运行它的时候才运行。它可用于 Claude Code、Cursor、Codex、GitHub Copilot、Grok Build 和 Hermes Agent，安装器会自动配置好。请选择「是」。自动化的设计检查。

在 CI 或你的终端里。 CLI 不需要智能体：

npx impeccable detect src/ # scan a directory
npx impeccable detect https://example.com # scan a rendered page (uses your installed Chrome or Edge)
npx impeccable detect --json . # machine-readable output
npx impeccable detect --github src/ # GitHub Actions annotations
npx impeccable detect --list-rules # every rule with its id and description

像 JSX 和 TSX 这样的源文件只会应用模式规则。需要渲染页面才能判断的规则（比如对比度过低和文字过小）会在你扫描 URL 时运行，所以也把 CLI 指向你的开发服务器：npx impeccable detect http://localhost:5173。

退出码 2 表示有发现，1 表示某个目标无法扫描。要在全站允许你的品牌字体，运行 npx impeccable ignores add-value overused-font Inter --reason "Brand font"。要为某个文件关闭一条规则，添加注释：<!-- impeccable-disable overused-font: exported brand doc -->。见「运行探测器扫描」与「配置与忽略」。

在你的浏览器里。 Chrome 扩展会把同样的发现叠加显示在任何实时页面上，你的或别人的都行。用可视化浮层来审查。

安装#

npx impeccable install

安装器会检测你的编程工具，询问是为当前项目安装还是全局安装，并在你的工具支持时提供设计钩子。请接受这个钩子。之后重新加载你的工具。npx impeccable update 会刷新已有安装。用于脚本时，请传入 --providers=claude,codex,cursor 和 --scope=project|global。

有三个工具在钩子运行前还需要多一步。在 Codex 中，打开 /hooks 并批准项目钩子（在会改变它的更新之后需要再次批准）。在 Grok Build 中，运行 /hooks-trust 或以 --trust 启动。在 Hermes Agent 中，钩子是一个插件：运行一次 hermes plugins enable impeccable-design-hook。在你的宿主中允许该钩子。

Node 仅用于 npx。技能本身运行一个自包含的引擎二进制文件，它要么随技能一起提供，要么一次性下载到 ~/.impeccable/bin/。

Claude Code、Copilot 和 Grok 插件#

• Claude Code：/plugin marketplace add pbakaus/impeccable，然后打开 /plugin 并安装 Impeccable。
• VS Code 中的 GitHub Copilot：从 Visual Studio Marketplace 安装 Impeccable，或运行 code --install-extension renaissance-geek.impeccable。需要 VS Code 1.109.3+、Copilot Chat 和受信任的工作区。它安装技能但不含钩子。详见文档。
• Grok Build：grok plugin install pbakaus/impeccable#plugin --trust 安装技能、智能体和钩子。

Git 子模块（为整个团队固定版本）#

git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor

提交 .gitmodules、子模块以及生成的链接。队友运行 git submodule update --init --recursive。要升级，运行 git submodule update --remote vendor/impeccable，重新运行 link 命令，然后提交。链接只安装技能，不安装钩子。已有的技能文件夹会保持原位，除非你传入 --force。

手动复制，无需 Node#

从 impeccable.style 下载适合你工具的 ZIP，或者克隆本仓库：每个工具的构建产物都提交在仓库根目录。把下面文件夹中的 skills/impeccable 复制到你项目中的同一位置，或者复制到全局文件夹。

例如：

mkdir -p your-project/.claude/skills && cp -r .claude/skills/impeccable your-project/.claude/skills/.

注意事项：

• 手动复制会跳过设计钩子和子智能体。运行 npx impeccable install 来获取它们；它会写入每个工具的钩子，指向正确的技能路径。
• OpenCode 还需要把 .opencode/commands/impeccable.md 复制到你项目的 .opencode/commands/ 中，以提供 /impeccable。
• Hermes 会要求你信任项目本地技能一次：从项目根目录运行 hermes skills trust。全局安装无需信任步骤。
• Cursor 和 Gemini CLI 可能需要在设置中启用 Agent Skills。参见 Cursor 与 Gemini CLI 的技能文档。
• 复制后请重启 Trae。
• 只有当 DSH_HOME 位于你的用户主目录之内时，impeccable install 和 update 才会管理 DeepSeek Harness 的全局副本。

项目文件与 git#

Impeccable 把工作文件写在 .impeccable/ 下。其中有少数是共享的项目产物，应当纳入仓库：config.json、live/config.json、design.json、surfaces/*.md 和 critique/*.md。PRODUCT.md 和 DESIGN.md 也应保留在仓库中。其余的是截图、缓存和运行时状态。

复制这些 .gitignore 条目：

# impeccable-ignore-start
# Ephemeral output, runtime state, and per-dev overrides.
# The **/ prefix covers .impeccable at the repo root or in a nested workspace.
# Shared artifacts stay tracked: config.json, live/config.json,
# design.json, surfaces/*.md, critique/*.md.
**/.impeccable/config.local.json
**/.impeccable/hook.cache.json
**/.impeccable/hook.pending.json
**/.impeccable/*.png
**/.impeccable/review/
**/.impeccable/questions/
**/.impeccable/live/server.json
**/.impeccable/live/sessions/
**/.impeccable/live/previews/
**/.impeccable/live/annotations/
**/.impeccable/live/cache/
**/.impeccable/live/manual-edit-apply-transaction.json
**/.impeccable/live/manual-edit-events.jsonl
**/.impeccable/live/manual-edit-evidence/
**/.impeccable/live/pending-manual-edits.json
**/.impeccable/live/deferred-svelte-component-accepts.json
**/.impeccable/live/*.png
# impeccable-ignore-end

保存决策轮次状态的文件夹（.impeccable/questions/、.impeccable/mocks/worlds/）也会忽略自身。.gitignore 无法取消跟踪 git 已经跟踪的文件；如果你之前提交过，请运行 git rm --cached <path>。

值得了解#

构建路径。 对于新的落地页和展示型界面，Impeccable 可以先产出一份完整保真的设计稿，再照着它构建（效果更好，但更慢），也可以直接在代码里构建（更精简、更快）。应用界面和文档始终在代码里构建。init 会询问一次并把答案保存为 .impeccable/config.json 中的 buildPath；决策页面允许你为单次会话覆盖它。只有你的宿主能够生成图片时，这个选项才会出现。见「图片生成」与「配置」。

钩子在模型批准之外运行。 在 Claude Code 中，已安装的命令钩子即使在你拒绝模型自己的命令时也会运行，所以第一次编辑就可能下载引擎。在无人值守运行之前审查已安装的钩子，或者传入 --settings '{"disableAllHooks": true}' 在单次运行中关闭它们。安装器不会动不是它添加的钩子条目。

出问题了？ /impeccable doctor 会找出过期的上下文文件、未使用的设置和损坏的钩子。见「修复设置问题」。

遥测。 当一个新的设计开始时，技能会从 impeccable.style 的目录中获取一组视觉方向。关闭遥测并不会停止这个请求；它停止的是那条匿名记录——记录了展示了哪些方向、你选了哪一个，目录正是靠它了解什么有效。你的项目名、文件、代码和 PRODUCT.md 从不会被发送。可以用 npx impeccable telemetry off、DO_NOT_TRACK=1，或在 .impeccable/config.json 中设置 "telemetry": false 来为整个项目禁用遥测。完整的发送内容清单见隐私页面。

社区#

缺陷、问题和想法请走 Issues。外部贡献从 issue 开始；参见 DEVELOP.md。

已发布内容的变更记录见 Changelog。

关注 @pbakaus 获取发布说明和新规则。

许可证#

Apache 2.0。见 LICENSE。Impeccable 起始于 Anthropic 的 frontend-design 技能。

由 Paul Bakaus 创建。