Impeccable¶

面向 AI 编码代理的设计指南。1 个技能、24 个命令、实时浏览器迭代，以及 62 条针对 AI 生成前端设计的确定性检测器规则。

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

为什么选择 Impeccable？¶

Anthropic 的 frontend-design 是第一个被广泛使用的 Claude 设计技能。Impeccable 正是从它出发。

每个模型都在相同的 SaaS 模板上训练。跳过这些指导，你会在每个项目中看到同样那一小撮典型痕迹：所有地方都用 Inter、紫到蓝的渐变、卡片里套卡片、彩色背景上的灰色文字、每个标题上方都有的圆角方形图标块。

Impeccable 增加了：

• 一套设置流程。 /impeccable init 将持久的产品真相记录在 PRODUCT.md 中，让后续命令了解受众、目的、运行环境、约束、声音和证据，而不会把这些事实与浅层的视觉方向混为一谈。
• 24 个命令。 一套与你的 AI 共享的设计词汇：polish、audit、critique、distill、animate、bolder、quieter 等。
• 62 条确定性检测器规则，外加仅限 LLM 的评审检查。CLI 和浏览器扩展在无需 LLM、无需 API 密钥的情况下运行这些确定性规则。

包含内容¶

技能：impeccable¶

该技能以一个命令的方式安装：

/impeccable <command> <target>

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

/impeccable init

init 会检查项目，只针对持久产品真相中的实质性缺口进行提问，并写入 PRODUCT.md。访客模式与视觉方向会在之后针对每个界面分别选择；已有或新建的视觉系统则单独记录在 DESIGN.md 中。

24 个命令¶

所有命令都通过 /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

反模式¶

该技能包含关于应避免之事的明确指导：

• 不要使用过度使用的字体（Arial、Inter、系统默认字体）
• 不要在彩色背景上使用灰色文字
• 不要使用纯黑/纯灰（始终加入色调）
• 不要把所有内容都放进卡片，也不要在卡片里嵌套卡片
• 不要使用弹跳/弹性缓动（会显得过时）

查看实际效果¶

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

安装¶

该技能不需要自己的运行时。每份技能副本都会附带一个小型启动器（scripts/impeccable，以及面向 Windows 的 impeccable.cmd），用于运行 Impeccable 引擎。这是一个自包含二进制文件，要么位于启动器旁边，要么在首次运行时一次性下载到 ~/.impeccable/bin/。只有在使用 npx impeccable 安装器时才会涉及 Node，而该安装器只是同一个二进制的包装层；下面提到的手动和 Git 选项都不需要它。

选项 1：CLI 安装器（推荐）¶

在项目根目录运行：

npx impeccable install

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

要刷新现有安装，请运行：

npx impeccable update

Codex 用户在安装或更新后应打开 /hooks，并在提示时批准项目钩子。Codex 按钩子定义跟踪信任，因此更改 .codex/hooks.json 的更新可能会要求再次批准。Grok Build 用户需要先授予项目文件夹信任（/hooks-trust 或以 --trust 启动），.grok/hooks/ 中的脚本才会运行。

有关各工具环境特定的信任与验证步骤，请参阅在你的工具环境中允许该钩子。

选项 2：Git 子模块¶

对于希望将 Impeccable 随项目内置并通过 Git 更新的团队，可将此仓库添加为子模块，并将编译后的提供程序构建链接到你的工具环境文件夹中：

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/ 中的各个技能文件夹，并且除非传入 --force，否则不会改动现有的真实技能目录。

以后更新：

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

选项 3：插件安装¶

VS Code 中的 GitHub Copilot：

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

code --install-extension renaissance-geek.impeccable

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

Claude Code：

/plugin marketplace add pbakaus/impeccable

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

Grok Build：

grok plugin install pbakaus/impeccable#plugin --trust

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

选项 4：从网站下载¶

访问 impeccable.style，下载适用于你的工具的 ZIP 文件，并解压到你的项目中。

选项 5：从仓库复制¶

Cursor：

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

注意： Cursor 技能需要设置： 1. 在 Cursor Settings → Beta 中切换到 Nightly 频道 2. 在 Cursor Settings → Rules 中启用 Agent Skills

了解关于 Cursor 技能的更多信息

Claude Code：

# Project-specific
cp -r dist/claude-code/.claude your-project/

# Or global (applies to all projects)
cp -r dist/claude-code/.claude/* ~/.claude/

OpenCode：

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

DeepSeek 工具环境：

# Project-specific
cp -r dist/dsh/.dsh your-project/

# Or global (applies to all projects)
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 管理。

Hermes Agent：

# Global (applies to all projects; uses the active profile, or ~/.hermes by default)
cp -r dist/hermes/.hermes/skills/* "${HERMES_HOME:-$HOME/.hermes}/skills/"

# Or project-specific
cp -r dist/hermes/.hermes your-project/

注意： Hermes 将项目级技能限定在逐仓库信任决策之后 （它们是过程文档，因此从任意克隆仓库自动加载它们会被 视为提示注入向量）。进行项目级安装后，请从项目根目录 运行一次 hermes skills trust。安装到活动 $HERMES_HOME/skills/（未设置时使用 ~/.hermes/skills/）的全局 安装无需信任步骤即可加载。之后 /impeccable <command> 会 通过该技能的 Commands 表进行路由；设计钩子不会 安装在 Hermes 上（因为没有钩子机制）。

了解关于 Hermes 技能的更多信息

Pi：

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

Gemini CLI：

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

注意： Gemini CLI 技能需要设置： 1. 安装预览版本：npm i -g @google/gemini-cli@preview 2. 运行 /settings 并启用 "Skills" 3. 运行 /skills list 以验证安装

了解关于 Gemini CLI 技能的更多信息

Codex CLI：

# Project-local
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json

# Or install the skill user-wide. Copy .codex/hooks.json into each project
# where you want the design hook to run.
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

资产生成子代理随技能自带的 agents/ 文件夹一起嵌套分发，Codex 会自动发现它。无需单独复制 .codex/agents/。钩子是项目级的，因为 Codex 从受信任项目配置旁边的 .codex/hooks.json 中发现钩子。

GitHub Copilot：

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

Trae：

# Trae China (domestic version)
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 以启用这些技能。

Rovo Dev:

# Project-specific
cp -r dist/rovo-dev/.rovodev your-project/

# Or global (applies to all projects)
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

Qoder:

# Project-specific
cp -r dist/qoder/.qoder your-project/

# Or global (applies to all projects)
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

Mistral Vibe:

# Project-specific
cp -r dist/vibe/.vibe your-project/

# Or global (applies to all projects)
cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/

Grok Build:

# Project-specific
cp -r dist/grok/.grok your-project/

# Or global (applies to all projects)
cp -r dist/grok/.grok/skills/* ~/.grok/skills/

建议使用 npx impeccable install --providers=grok 或 grok plugin install pbakaus/impeccable#plugin --trust，这样设计钩子也会被安装。项目钩子需要在每个文件夹中执行一次 /hooks-trust（或 --trust）。

Google Antigravity:

# Project-specific
cp -r dist/antigravity/.agent your-project/

# Or global (applies to all projects)
mkdir -p ~/.gemini/config/skills
cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/

使用方式¶

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

/impeccable audit        # Find issues
/impeccable polish       # Final cleanup
/impeccable distill      # Remove complexity
/impeccable critique     # Full design review

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

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

/impeccable audit the header
/impeccable polish the checkout form

如果你经常使用某个命令，可以用 /impeccable pin audit 将其固定，这样 /audit 就会成为一个独立的快捷命令。

注意： Codex 在这里使用的是技能（skills），而不是 /prompts: 命令。打开 /skills 或输入 $impeccable。仓库本地安装位于 .agents/skills/；用户全局安装位于 ~/.agents/skills/。GitHub Copilot 使用 .github/skills/。如果新安装的技能没有出现，请重启该工具。

让 .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（审查报告）

Impeccable 还会在保存决策轮次状态的文件夹中放置自己的 .gitignore：.impeccable/questions/ 和 .impeccable/mocks/worlds/ 会忽略其中的所有内容，.impeccable/build/ 会忽略 state.json。即使项目中没有上面的代码块，这也能让新的运行时文件不进入提交。不过，.gitignore 无法取消跟踪 git 已经跟踪的文件：当其中一个文件先前已被提交时，下一次 roll 会打印一条一次性通知，其中包含修复命令 git rm -r --cached .impeccable/questions（以及它提到的任何其他文件夹），并且在那之前，它会把 roll 记录写入一个未跟踪的文件。

如果你在添加该代码块之前已经提交了某个临时文件（如截图、config.local.json），.gitignore 不会自动取消跟踪它。请运行 git rm --cached <path> 来停止跟踪它，同时不会删除你的本地副本。

遥测¶

当一个新的设计开始时，该技能会向 impeccable.style 的 roll API 发起请求，从目录中发一组视觉世界。这个请求就是功能本身，因此它总是会发生。除非你选择退出，否则它还会提交一条匿名记录，记录展示了哪一组（hand）以及哪张卡片（card）胜出，这正是目录了解什么有效的方式。

在 roll 请求以及随后的选择中，会发送以下内容：

• roll 键（每个决策轮次的随机值）、范围（direction 或 surface）、访客模式，以及 re-roll 轮次
• hand 所来自的目录修订版本，以及在选择时获胜卡片的类型（assigned、pick、challenger、canon 或 re-roll）、当某个目录世界获胜时它的目录 ID，以及它在页面上的位置
• 客户端版本、该选择是来自决策页面还是 agent，以及该选择的随机 ID，以便同一份报告被发送两次时也只会被计算一次

绝不会发送：你的项目名称、文件、代码、PRODUCT.md，或你的 agent 所编写的方向名称。已提交的文件（如 surface 简报）只会记录一个 seed 引用，也就是 roll 键在随机盐下的哈希值，该盐保存在 ~/.impeccable/seed-salt 中，而绝不会记录 roll 键本身。如果某台机器无法保存盐，该简报将完全不记录 seed，而不是记录一个较弱的哈希。roll 键是 128 位随机数。如果你通过 --from 传入自己的短键，其引用很容易被猜到，因此不要依赖它来保证该键的私密性。

要关闭它，请运行 npx impeccable telemetry off（存储在 ~/.impeccable/config.json 中），或设置 DO_NOT_TRACK=1 或 IMPECCABLE_NO_TELEMETRY=1。项目可以通过在 .impeccable/config.json 中设置 "telemetry": false 来让所有人选择退出。npx impeccable telemetry status 显示当前状态。退出后，roll 仍然有效，API 会被告知不记录它。详情：https://impeccable.style/privacy

设计钩子¶

在 Claude Code、GitHub Copilot、Codex、Cursor 和 Grok Build 上，npx impeccable install 和 npx impeccable update 会安装一个提供商原生的钩子清单以及技能载荷。该钩子会在直接编辑 UI 文件时运行 Impeccable 设计检测器，并将发现结果反馈到 Agent 流程中。Claude Code、GitHub Copilot、Codex 和 Cursor 会在编辑后呈现发现结果（并在支持的情况下于 Stop 时执行更深入的检查）。Grok Build 会在编辑后扫描以预热 Stop，然后在 Stop 时呈现；PostToolUse 的 stdout 永远不会到达模型。

已安装钩子的呈现方式：

• Claude Code：.claude/settings.local.json（已被 Git 忽略，仅本机）运行 ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook。移到共享 settings.json 中的钩子会就地生效。
• GitHub Copilot：.github/hooks/impeccable.json（已提交，由 Copilot CLI 和云代理共享）运行 .github/skills/impeccable/scripts/impeccable hook。一旦该文件位于仓库的默认分支且文件夹受信任，Copilot CLI 就会激活它。
• Cursor：.cursor/hooks.json 会在文件写入时于 postToolUse 上运行 .cursor/skills/impeccable/scripts/impeccable hook。使用较旧的 preToolUse 写入门控配置的项目仍然可以工作；npx impeccable update 会将它们迁移到编辑后钩子。
• Codex：.codex/hooks.json 运行 .agents/skills/impeccable/scripts/impeccable hook，并有一个 commandWindows 同级条目，为 cmd.exe 调用 impeccable.cmd。
• Grok Build：.grok/hooks/impeccable.json 运行 .grok/skills/impeccable/scripts/impeccable hook。需要 /hooks-trust 或 --trust。发现结果会在 Stop 时到达模型，而不是每次编辑后。

所有命令都通过技能 scripts/ 目录中附带的启动器（impeccable，Windows 上为 impeccable.cmd）执行，并带有守卫：如果启动器缺失，则静默无操作。启动器会运行其旁边附带的引擎二进制文件，或将固定版本一次性下载到 ~/.impeccable/bin/。钩子和技能都不需要 Node 或其他运行时。

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

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

在交互式 install/update 中，Impeccable 会解释该钩子并提供安装选项（默认是）。你的选择会按开发者记录在已被 Git 忽略的 .impeccable/config.local.json 中，因此不会再次询问；--no-hooks 会在该次运行中跳过它，且不记录任何内容。钩子生命周期设置位于 .impeccable/config.json 的 hook 键下；检测器的忽略项位于 detector 下，由 /impeccable hooks 和 npx impeccable detect 共享。

如需调试，请在 .impeccable/config.json 中将 hook.auditLog 设置为一个路径（或使用旧版 IMPECCABLE_HOOK_LOG 环境变量），以便每次钩子调用写入一行 NDJSON。正常使用时请保持不设置。

构建路径：comp优先还是code优先¶

当设计新界面时，Impeccable 要么首先生成高保真 comp，然后构建以匹配它；要么直接在代码中构建，同时把目标写进界面简报中仅供开发使用的方向契约，并在完成时检查。Comp-first 方式构图更大胆，但耗时更长；code-first 方式更精简、速度更快。该选择适用于落地页和展示型界面。应用界面和文档无论如何都采用 code-first 构建，因为直接构建出来的效果比预先画出来的更好。/impeccable init 会询问一次，并将答案以 buildPath 记录在 .impeccable/config.json 中：

{ "buildPath": "comp" }

取值只有 comp 和 code，其他值均不会被读取。把它设置在已被 Git 忽略的 .impeccable/config.local.json 中，可以在单台机器上覆盖团队已提交的值；当你的环境没有图像生成能力时，这正是你需要的。在 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。

仅在您信任可在本地运行的项目中使用实时模式。应用文案编辑时，会自动在 shell 中以您的用户权限执行 package.json 中的可选 scripts["impeccable:manual-edit-validate"] 命令；在不熟悉的检出副本中使用实时模式之前，请先查看该脚本。

生产环境检查请使用 npx impeccable detect https://example.com 或浏览器扩展。这些方式只检查渲染后的页面，不提供实时变体编辑，也不会将更改写回您的源码。

CLI¶

Impeccable 包含一个独立的 CLI，无需 AI 集成框架即可检测反模式。npx impeccable 是一个小型壳程序，运行与技能所用相同的引擎二进制文件（以平台相关的可选依赖安装，或一次性拉取到 ~/.impeccable/bin/）；仅 npx 本身需要 Node，您也可以直接下载二进制文件并将其放入 PATH。

npx impeccable detect src/                   # scan a directory
npx impeccable detect index.html             # scan an HTML file
npx impeccable detect https://example.com    # scan a URL (uses an installed Chrome, Chromium, or Edge)
npx impeccable detect --json .               # CI-friendly JSON output
npx impeccable detect --github src/          # GitHub Actions annotations on stdout
npx impeccable detect --list-rules           # catalog of detector rule ids, names, and descriptions
npx impeccable detect --no-config src/       # raw scan, ignoring project config/context
npx impeccable ignores list                  # show detector ignores
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

该检测器可捕获 62 个确定性问题，涵盖 AI 味（侧边标签页边框、紫色渐变、回弹缓动、暗色光晕）和通用设计质量（行宽、过于局促的内边距、过小的触摸目标、跳过的标题层级等）。

人类可读的发现是写入 stderr 的诊断信息，因此请使用 2> findings.txt 进行重定向。需要机器可读结果时，请使用 --json 输出到 stdout，或使用 --github 生成 GitHub Actions 注释（每个发现对应一条工作流命令）。GitHub 每个步骤最多显示每种类型的 10 条注释，每个作业最多显示 50 条，其余保留在日志中；HTML 引擎产生的发现可能不包含行号，因此会标注到文件级别。--list-rules 会将检测器目录打印到 stdout，且不执行扫描。退出码 0 表示扫描完成且无主要发现，退出码 2 表示扫描完成且存在主要发现，退出码 1 表示至少有一个请求的目标无法扫描；多目标扫描部分失败时，以运行失败状态为准。URL 扫描会检查渲染后的 DOM、计算后的布局以及可访问的关联样式表；浏览器安全机制仍会阻止在没有 CORS 的情况下读取跨源 CSS。一次干净的检测运行是证据，而非视觉或无障碍质量的证明：它不能替代在相关视口下检查渲染后的体验。

默认情况下，detect 与 design hook 一样遵循 .impeccable/config.json 和 .impeccable/config.local.json 中的检测器配置：detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues 和 detector.designSystem.enabled。hook.enabled 等 hook 生命周期设置仅影响自动 hook 执行。

如果豁免需要跟随单个文件（而非仓库配置）生效，请在文件中添加内联注释：<!-- impeccable-disable overused-font: exported brand doc -->。该标记适用于任何注释语法，作用范围为整个文件（或使用 impeccable-disable-line / impeccable-disable-next-line 作用于单行），并会被 --no-inline-ignores 或 --no-config 绕过。

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

支持的工具¶

• Cursor
• Claude Code
• GitHub Copilot
• DeepSeek Harness
• Gemini CLI
• Codex CLI
• Grok Build
• Hermes Agent
• OpenCode
• Pi
• Kiro
• Trae
• Rovo Dev
• Qoder
• Mistral Vibe
• Veto
• Google Antigravity

社区与生态系统¶

加入社区与生态系统的讨论：

• GitHub Discussions：提交 Bug、请求新功能，并帮助新手。
• npm 上的 Impeccable：获取 CLI、关注版本发布，并为该包加星标。
• 在 Twitter 上关注 @pbakaus，获取版本说明、示例 lint 报告和新规则亮点视频。

贡献指南¶

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

许可证¶

Apache 2.0。请参阅 LICENSE。

由 Paul Bakaus 创建