AI 编码智能体的设计指南。1 个 Skill、24 条命令、实时浏览器迭代，以及 61 条确定性检测规则，用于检测 AI 生成的前端设计效果。

快速上手：在项目根目录运行 npx impeccable install，然后在 AI 编码工具中运行 /impeccable init。完整文档：impeccable.style。

Anthropic 的 frontend-design 是首个被广泛使用的 Claude 设计 Skill。Impeccable 由此发展而来。

所有模型都在相同的 SaaS 模板上训练。如果缺乏设计指导，每个项目都会出现相同的几个特征：所有地方都用 Inter 字体、紫到蓝的渐变色、卡片里嵌套卡片、彩色背景上的灰色文字、每个标题上方都是圆角方形图标瓦片。

一次设置流程。/impeccable init 将持久的产品真相记录到 PRODUCT.md 中，后续命令就知道受众、目的、运行环境、约束条件、语气风格，以及证据，而不会将这些事实与表面视觉方向混淆。

24 条命令。与 AI 共享一套设计词汇：polish、audit、critique、distill、animate、bolder、quieter 等等。

61 条确定性检测规则加上仅限 LLM 的批判性检查。CLI 和浏览器扩展以无 LLM、无 API key 的方式运行确定性规则。

The Skill: impeccable

该 skill 以一条命令安装：

/impeccable <command> <target>

每个新项目都以以下命令开始：

/impeccable init

init 检查项目，仅就持久产品真相中的实质性缺口提问，然后写入 PRODUCT.md。访客模式和视觉方向稍后为每个界面单独选择；已有的或新构建的视觉系统单独记录在 DESIGN.md 中。

所有命令均通过 /impeccable 访问：

使用 /impeccable pin <command> 创建独立快捷方式（例如 pin audit 创建 /audit）。

/impeccable audit blog           # 审计博客中心 + 文章页面
/impeccable critique landing     # UX 设计评审
/impeccable polish settings      # 发布前的最终检查
/impeccable harden checkout      # 添加错误处理 + 边界情况

或直接用描述性语言使用 /impeccable：

/impeccable redo this hero section

该 skill 包含明确的避坑指南：

不要使用滥用的字体（Arial、Inter、系统默认字体）

不要在彩色背景上使用灰色文字

不要使用纯黑/灰色（始终加色调）

不要把所有东西都包在卡片里或让卡片嵌套卡片

不要使用弹跳/弹性缓动（感觉过时）

访问 Neo Mirai 案例研究，查看一个真实项目使用 Impeccable 命令改造的前后对比。

该 skill 无需自己的运行时。每个 skill 副本都附带一个小型启动器（scripts/impeccable，外加 Windows 的 impeccable.cmd），运行 Impeccable 引擎——一个自包含的二进制文件，既可以放在启动器旁边，也可以在首次运行时下载到 ~/.impeccable/bin/。只有在使用 npx impeccable 安装器时才会涉及 Node；下面的手动方式和 Git 方式无需它。

Option 1: CLI 安装器（推荐）

在项目根目录运行：

npx impeccable install

这会显示检测到的 harness 文件夹或已安装的 CLI（例如 ~/.claude、~/.codex、~/.grok、~/.hermes、~/.veto，或项目本地的 .cursor），你可以保留检测到的集合或自定义提供商，然后询问是安装到当前项目还是全局安装。使用 --providers=claude,codex,cursor,grok,hermes,veto 和 --scope=project|global 可在脚本中跳过这些选择。在 Claude Code、Cursor、Codex、GitHub Copilot 和 Grok Build 上，它还会为当前项目安装提供商原生的 hook 清单。Veto 将打包的 skill 放在 ~/.veto/skills/ 下，不运行原生 Impeccable 编辑 hook。支持 Cursor、Claude Code、Gemini CLI、Codex CLI、Grok Build、Hermes Agent、Veto，以及所有其他支持的工具。之后请重新加载你的 harness。

刷新现有安装：

npx impeccable update

Codex 用户应在安装或更新后打开 /hooks，并在出现提示时批准项目 hook。Codex 按 hook 定义追踪信任，因此更新更改了 .codex/hooks.json 可能需要重新审批。Grok Build 用户在 .grok/hooks/ 脚本运行之前需要项目文件夹信任（/hooks-trust 或以 --trust 启动）。

参阅 Allow the hook in your harness 获取各 harness 特定的信任和验证步骤。

Option 2: Git 子模块

对于希望通过 Git 管理 Impeccable 依赖并更新的团队，将其作为子模块添加，并将编译好的提供商构建链接到 harness 文件夹：

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"

使用你项目需要的提供商，例如 claude、cursor、gemini、codex、github、grok、hermes、opencode、pi、qoder、trae、trae-cn、rovo-dev、vibe 或 veto。该命令从 .impeccable/dist/universal/ 链接各个 skill 文件夹，除非你传入 --force，否则不会影响现有的真实 skill 目录。

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

Option 3: 插件安装

GitHub Copilot in VS Code：

从 Visual Studio Marketplace 安装 Impeccable，或运行：

code --install-extension renaissance-geek.impeccable

需要 VS Code 1.109.3+、Copilot Chat 访问权限，以及可信的本地工作区。在 Agent 模式下打开 Chat 并尝试 /impeccable polish。此纯 skill 扩展不会安装自动 hook；避免在同一工作区/配置文件中重复 Impeccable skill。参阅 VS Code 分发详情。

/plugin marketplace add pbakaus/impeccable

仅限 Claude Code。添加 marketplace 后，打开 /plugin 并从列表中安装 Impeccable。

grok plugin install pbakaus/impeccable#plugin --trust

仅限 Grok Build。#plugin 后缀安装精简插件包（skills、agents 和 hooks）而非完整 monorepo。然后在 Grok 会话中运行 /impeccable init。通过 npx impeccable install --providers=grok 的项目级安装同样有效，会写入 .grok/skills/ 和 .grok/hooks/impeccable.json。

Option 4: 从网站下载

访问 impeccable.style，下载你工具对应的 ZIP 包，解压到项目中。

Option 5: 从仓库复制

cp -r dist/cursor/.cursor your-project/

注意：Cursor skills 需要设置：

在 Cursor Settings → Beta 中切换到 Nightly 频道

在 Cursor Settings → Rules 中启用 Agent Skills

了解更多关于 Cursor skills 的信息

# 项目特定
cp -r dist/claude-code/.claude your-project/

# 或全局（适用于所有项目）
cp -r dist/claude-code/.claude/* ~/.claude/

cp -r dist/opencode/.opencode your-project/

# 项目本地
cp -r dist/dsh/.dsh your-project/

# 或全局（适用于所有项目）
mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills"
cp -r dist/dsh/.dsh/skills/* "${DSH_HOME:-$HOME/.dsh}/skills/"

CLI 仅在解析结果位于主目录内（或主目录本身）时遵循 DSH_HOME；否则使用 ~/.dsh。主目录外部的手动复制不受 impeccable install/update 管理。

# 全局（适用于所有项目；使用活动 profile，或默认为 ~/.hermes）
cp -r dist/hermes/.hermes/skills/* "${HERMES_HOME:-$HOME/.hermes}/skills/"

# 或项目特定
cp -r dist/hermes/.hermes your-project/

注意：Hermes 将项目本地 skills 置于每仓库信任决策之后（它们是过程文档，因此从任何克隆的仓库自动加载被视为提示注入向量）。项目级安装后，从项目根目录运行一次 hermes skills trust。全局安装到活动 $HERMES_HOME/skills/（或未设置时的 ~/.hermes/skills/）无需信任步骤即可加载。之后 /impeccable <command> 通过 skill 的 Commands 表路由；设计 hook 不会安装在 Hermes 上（无 hook 暴露）。

了解更多关于 Hermes skills 的信息

cp -r dist/pi/.pi your-project/

cp -r dist/gemini/.gemini your-project/

注意：Gemini CLI skills 需要设置：

安装预览版本：npm i -g @google/gemini-cli@preview

运行 /settings 并启用 "Skills"

运行 /skills list 验证安装

了解更多关于 Gemini CLI skills 的信息

# 项目本地
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

# 或用户级安装 skill。将 .codex/hooks.json 复制到每个希望设计 hook 运行的项目
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

资产生成子代理随 skill 自己的 agents/ 文件夹一起发布，Codex 会自动发现。无需单独的 .codex/agents/ 副本。hook 是项目本地的，因为 Codex 从可信项目配置旁边的 .codex/hooks.json 发现 hook。

cp -r dist/github/.github your-project/

Trae China（国内版）

cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/

Trae International

cp -r dist/trae/.trae/skills/* ~/.trae/skills/

注意：Trae 有两个版本，配置目录不同：

Trae China: ~/.trae-cn/skills/

Trae International: ~/.trae/skills/

复制完成后，重启 Trae IDE 以激活 skills。

# 项目级
cp -r dist/rovo-dev/.rovodev your-project/

# 或全局（应用于所有项目）
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

# 项目级
cp -r dist/qoder/.qoder your-project/

# 或全局（应用于所有项目）
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

# 项目级
cp -r dist/vibe/.vibe your-project/

# 或全局（应用于所有项目）
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/

# 项目级
cp -r dist/grok/.grok your-project/

# 或全局（应用于所有项目）
cp -r dist/grok/.grok/skills/* ~/.grok/skills/

推荐使用 npx impeccable install --providers=grok 或 grok plugin install pbakaus/impeccable#plugin --trust，以便设计 hook 也能安装。项目级 hook 需要每个文件夹执行一次 /hooks-trust（或 --trust）。

# 项目级
cp -r dist/antigravity/.agent your-project/

# 或全局（应用于所有项目）
mkdir -p ~/.gemini/config/skills
cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/

安装完成后，所有命令都通过单一的 /impeccable skill 运行：

/impeccable audit        # 查找问题
/impeccable polish       # 最终清理
/impeccable distill      # 移除复杂性
/impeccable critique     # 完整设计审查

单独输入 /impeccable 可查看完整命令列表。

大多数命令接受一个可选参数，用于聚焦特定区域：

/impeccable audit the header
/impeccable polish the checkout form

如果某个命令使用频繁，可以用 /impeccable pin audit 将其固定为独立快捷方式 /audit。

注意：Codex 在这里使用的是 skills，而非 /prompts: commands。请打开 /skills 或输入 $impeccable。仓库级安装位于 .agents/skills/；用户级安装位于 ~/.agents/skills/。GitHub Copilot 使用 .github/skills/。如果新安装的 skill 没有出现，请重启工具。

将 .impeccable 排除在 git 之外

运行命令时，Impeccable 会在 .impeccable/ 下写入工作文件：critique 和 polish 的截图、实时模式会话和预览状态、运行时缓存，以及每个开发者的配置。其中大部分是临时的，不应提交，而少数文件是共享的项目产物，应该保留在仓库中。将以下内容添加到项目的 .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-ignore-start / # impeccable-ignore-end 标记包裹，便于以后识别和刷新。**/ 前缀使每个模式都能匹配，无论活动项目的 .impeccable/ 目录是在仓库根目录还是在 apps/web/ 等嵌套工作区路径下。

保留这些文件的跟踪（它们是共享的项目产物，不要将它们添加到 .gitignore）：

.impeccable/config.json（统一共享配置）

.impeccable/live/config.json（实时模式框架接线）

.impeccable/design.json（共享设计规范）

.impeccable/surfaces/*.md（路由或产物特定策略和方向契约）

.impeccable/critique/*.md（审查报告）

如果某个临时文件（如截图、config.local.json）在添加此块之前已被提交，.gitignore 不会自动取消跟踪它。运行 git rm --cached <path> 可以停止跟踪而不删除本地副本。

关于 Hook

在 Claude Code、GitHub Copilot、Codex、Cursor 和 Grok Build 上，npx impeccable install 和 npx impeccable update 会随 skill 载荷一起安装provider 原生的 hook 清单。Hook 在直接编辑 UI 文件时运行 Impeccable 设计检测器，并将发现结果反馈到 agent 流程中。Claude Code、GitHub Copilot 和 Codex 在编辑后展示发现结果（并在支持的平台上于 Stop 时运行更深入的传递）。Grok Build 在编辑后扫描以预热 Stop，然后在 Stop 时展示结果；PostToolUse stdout 永远不会到达模型。Cursor 在不良编辑提议落地之前将其阻止。

已安装 hook 的展示平台：

Claude Code: .claude/settings.local.json（被 gitignore，机器本地）运行 ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook。如果将 hook 移入共享的 settings.json，则会在该位置被启用。

GitHub Copilot: .github/hooks/impeccable.json（已提交，由 Copilot CLI 和云 agent 共享）运行 .github/skills/impeccable/scripts/impeccable hook。一旦文件在仓库的默认分支上且文件夹受信任，Copilot CLI 就会激活它。

Cursor: .cursor/hooks.json 运行 .cursor/skills/impeccable/scripts/impeccable hook-before-edit。

Codex: .codex/hooks.json 运行 .agents/skills/impeccable/scripts/impeccable hook，同时有一个 commandWindows 同类文件调用 impeccable.cmd 用于 cmd.exe。

Grok Build: .grok/hooks/impeccable.json 运行 .grok/skills/impeccable/scripts/impeccable hook。需要 /hooks-trust 或 --trust。结果在 Stop 时到达模型，而非每次编辑后。

每个命令都通过 skill scripts/ 目录中附带的启动器运行（impeccable，或 Windows 上的 impeccable.cmd），启动器受保护以确保缺少启动器时为静默无操作。启动器运行与之一起发布的引擎二进制文件，或一次性下载固定版本到 ~/.impeccable/bin/。Hook 和 skill 都不需要 Node 或其他运行时。

在 Claude Code 中，已安装的命令 hook 独立于模型-工具批准运行。因此，第一次编辑或 Stop 事件可以在会话拒绝模型的启动器命令时下载并缓存引擎。在无人值守运行之前审查已安装的 hook；要禁用某个运行的所有 Claude Code hook，请传递 --settings '{"disableAllHooks": true}'。参见 Claude Code 的 hook 安全指南。

安装程序保留无关的 hook 条目和设置。如果 hook 清单格式不正确，安装/更新默认中止；使用 --force 重新运行可将格式错误的文件备份为 .bak 并替换它。

在交互式安装/更新时，Impeccable 会解释 hook 并提供安装选项（默认同意）。你的选择会按开发者在被 gitignore 的 .impeccable/config.local.json 中记住，因此不会再被询问；--no-hooks 跳过该次运行而不记录任何内容。Hook 生命周期设置位于 .impeccable/config.json 的 hook 键下；detector.ignores live 位于 detector 下，由 /impeccable hooks 和 npx impeccable detect 共享。

要进行调试，请在 .impeccable/config.json 中将 hook.auditLog 设置为某个路径（或使用旧版 IMPECCABLE_HOOK_LOG 环境变量）以写入每个 hook 调用的一条 NDJSON 行。正常使用时保持未设置。

构建路径：comp-first 或 code-first

当设计一个新 surface 时，Impeccable 要么先生成完全保真的 comp，然后构建以匹配它，要么直接在代码中构建，并将野心写入 surface 简报中的开发时方向契约，在结束时进行检查。Comp-first 组合更大胆但耗时更长；code-first 更精简快速。/impeccable init 询问一次并将答案记录为 .impeccable/config.json 中的 buildPath：

{ "buildPath": "comp" }

值为 comp 和 code，不会读取其他内容。在 .impeccable/config.local.json（被 gitignore）中设置它可以覆盖团队在某台机器上提交的值为本地值，当你的测试工具没有图像生成能力时这正是你需要的。在 monorepo 中，在仓库根目录提交一次，任何想要不同设置的工作区都可以设置自己的。只有在有图像生成能力的地方才会显示这个选择，因为没有图像生成就无法进行 comp。

你不需要在一个早于该设置的项目上重新运行 init，也不需要手动编辑配置文件。记录下来的只是默认值而非锁定：每个决策页面底部都有一个开关，切换它只会绑定当前会话。如果在一个没有任何记录的项目上切换它，Impeccable 会在这一轮结束后询问一次是否保留该设置，然后将你的回答写入配置文件。这就是现有项目的完整迁移路径：当默认值不符合需求时使用开关，并回答后续的问题。

Codex 需要一个 Impeccable 无法安全跳过的平台步骤：安装或更新后打开 /hooks 并批准项目钩子。这里没有 Codex marketplace/plugin 的安装流程来处理这个钩子。

完整的钩子文档：impeccable.style/docs/hooks。

Stop 阶段会在存在已验证的编辑前基线时（目前是文本扫描的 Claude Edit/Write 结果）抑制已确认的预先存在的问题。其他问题会被标记为新增或归属未知；未知状态并不意味着你的会话导致了该问题。显式的 detect 扫描保持不变。

手动复制命令是备用/调试指令。正常流程是：

npx impeccable install
npx impeccable update

实时模式和正式站点

实时模式通过开发服务器或本地静态 HTML 编辑本地代码库。不支持将其 localhost HTTP 辅助脚本注入已部署的正式站点（包括 HTTPS 站点）。不要为了使其工作而禁用浏览器安全或削弱正式环境的 CSP。

仅在信任的本地项目中使用的实时模式。应用复制编辑会自动运行 package.json 中的可选脚本 scripts["impeccable:manual-edit-validate"]，使用你的用户权限运行；在不熟悉的代码库中使用实时模式前，请先检查该脚本。

对于正式环境检查，使用 npx impeccable detect https://example.com 或浏览器扩展。这些工具会检查渲染后的页面，但不提供实时变体编辑或写入源代码的更改。

Impeccable 包含一个独立的 CLI，用于在不需要 AI 智能体的情况下检测反面模式。npx impeccable 是一个小型垫片程序，运行与 skill 相同的引擎二进制文件（作为平台特定的 optional 依赖安装，或一次性获取到 ~/.impeccable/bin/）；Node 仅用于 npx 本身，你也可以直接下载二进制文件并放到你的 PATH 中。

npx impeccable detect src/                   # 扫描一个目录
npx impeccable detect index.html             # 扫描一个 HTML 文件
npx impeccable detect https://example.com    # 扫描一个 URL（使用已安装的 Chrome、Chromium 或 Edge）
npx impeccable detect --json .               # CI 友好的 JSON 输出
npx impeccable detect --no-config src/       # 原始扫描，忽略项目配置/上下文
npx impeccable ignores list                  # 显示检测器的忽略项
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

检测器能够捕捉 61 个确定性问题，涵盖 AI 劣质内容（侧边栏边框、紫色渐变、弹跳缓动、黑色光晕）和通用设计质量（行长度、拥挤的内边距、过小的触摸目标、跳过的标题层级等）。

人类可读的结果是写入 stderr 的诊断信息，因此可以使用 2> findings.txt 进行重定向。使用 --json 在 stdout 上输出机器可读的结果。退出码 0 表示扫描完成且没有主要发现，退出码 2 表示扫描完成且有主要发现，退出码 1 表示至少有一个请求的目标无法扫描；操作失败在多目标部分扫描中优先。URL 扫描会检查渲染后的 DOM、计算的布局和可访问的链接样式表；浏览器安全机制仍会阻止在没有 CORS 的情况下读取跨域 CSS。检测器的干净运行是证据，但不是视觉或可访问性质量的证明：它不能替代在相关视口上检查渲染后的体验。

默认情况下，detect 遵循与设计钩子相同的 .impeccable/config.json 和 .impeccable/config.local.json 检测器配置：detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues 和 detector.designSystem.enabled。钩子生命周期设置（如 hook.enabled）仅影响自动钩子执行。

对于应该随单个文件一起传递而不是随仓库配置一起传递的豁免，在文件中添加内联注释：<!-- impeccable-disable overused-font: exported brand doc -->。该标记适用于任何注释语法，作用域为整个文件（或使用 impeccable-disable-line / impeccable-disable-next-line 作用于单行），并可通过 --no-inline-ignores 或 --no-config 绕过。

完整的检测器文档：impeccable.style/docs/detector。

社区与生态系统

加入社区和生态系统讨论：

GitHub Discussions：提交 bug、功能请求，并帮助新手。

Impeccable on npm：获取 CLI、关注版本发布，并为项目加星。

在 Twitter 上关注 @pbakaus 获取版本说明、示例 lint 报告和新规则的视频演示。

有关贡献者指南和构建说明，请参阅 DEVELOP.md。

采用 Apache 2.0 许可证。详见 LICENSE。

由 Paul Bakaus 创建