第34章 Agent 时代缺失的设计词汇:Impeccable 配置与例外规则详解
配置与忽略规则:设定共享的默认值,让检查保持有效。本页共 7 个小节。大多数 agent 使用 /impeccable;在 Codex 中请使用 $impeccable。
通过 config 可以保存构建流程、记录有意的检测例外,并调整检查的运行方式。你可以用自然语言让 Impeccable 修改流程默认值;检测例外则可通过 CLI 管理。
所有设置都存放在 .impeccable/ 目录下。产品定位放在 PRODUCT.md,视觉决策放在 DESIGN.md,详见 Context files。
选择构建流程
把 buildPath 设为 comp 表示先做原型(comp-led),设为 code 表示直接写代码(code-led):
{ "buildPath": "comp" }
把这个设置合并进你现有的 .impeccable/config.json,保留其他设置。团队默认值的个人覆盖可放在 .impeccable/config.local.json。
也可以用自然语言让 Impeccable 直接修改默认值。选择器中的切换只对当前会话生效。如果没有保存偏好,在可用图像生成时默认走"先做原型";不可用时,无论保存了什么偏好,Impeccable 都走 code-led。
两种流程的对比或图像生成的启用方法见相应章节。API key 应放在 agent 的环境变量中,绝不要写进这些配置文件。
记录一个具体例外
假设 Inter 是你确认的品牌字体。忽略这个值,同时让字体规则对其他内容继续生效:
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
查看当前例外,或之后移除这个例外:
npx impeccable ignores list npx impeccable ignores remove-value overused-font Inter
手动扫描和 hooks 使用同一套 ignores。遇到真实问题就去修复;只有当报告的选择是有意为之时才用例外。
限制作用范围
如果只想对某条规则、某个文件生效,可以使用文件级值忽略:
npx impeccable ignores add-value design-system-color "*" --file "src/demo.css" --reason "Palette comparison demo"
这里 "*" 表示允许该文件使用任意颜色。其他检查照常运行,其他位置的颜色仍会被检查。通配符值必须搭配文件范围使用。
排除整个文件或整条规则
如果整个文件都不属于设计审查范围(比如刻意保留的坏设计测试样例),可以用文件排除:
npx impeccable ignores add-file "tests/fixtures/bad-design/"
这会抑制匹配文件上的所有规则,包括未来新增的规则。如果只想在整个项目中抑制某条规则:
npx impeccable ignores add-rule side-tab
对于 overused-font,整条规则抑制还需要 --all-values。如果只需要针对某个字体,优先用具体字体的例外方式。
用 remove-file 或 remove-rule 加同样的参数即可撤销这些设置。ignores clear 会清除所选配置中的全部忽略项。
共享决策还是仅本地生效
默认共享:命令写入 .impeccable/config.json。提交这个文件以分享团队决策,比如品牌例外。
用 --local 则仅本地生效:命令写入 .impeccable/config.local.json。Impeccable 会把这个文件排除在 git 之外。
npx impeccable ignores add-file "src/private-experiment/" --local
移除例外时使用同样的作用范围。在 remove 或 clear 命令上加 --all 可以同时作用于共享和本地配置。
行内忽略注释
如果某个例外需要随文件一起带到仓库之外,可以写在注释里:
共有三种形式:
标记 | 作用范围 impeccable-disable | 整个文件 impeccable-disable-line | 当前行 impeccable-disable-next-line | 下一行
静态 HTML 的检测结果没有行号,所以对它们要用整文件形式。行级范围适用于带行号的检测结果,比如 CSS 和 JSX 的源码检查。
注释语法与绕过行内忽略
标记要写在文件本身使用的注释语法中:HTML、CSS、JavaScript、JSX 或其他受支持的源码格式。标记后面跟一个规则 ID 或逗号分隔的多个 ID。省略 ID 或使用 * 会抑制该范围内的所有规则。
: 或 -- 之后的理由有助于审查代码的人理解,但扫描器会丢弃这个理由。
/* impeccable-disable-next-line overused-font: brand font */ .brand { font-family: Inter; }
detect --no-inline-ignores 会绕过这些注释,但仍保留配置中的 ignores。detect --no-config 则两者都绕过,同时也不加载项目设置和本地 design-system 上下文。
服务端模板
如果你的 UI 使用 Blade、ERB、Twig 或其他模板格式,需要添加扩展名配置:
{ "detector": { "extensions": [ { "ext": ".blade.php", "engine": "html" }, { "ext": ".html.erb", "engine": "html" } ] } }
把这些合并进 .impeccable/config.json。扩展名按文件名结尾匹配,包括双重扩展名。html 是默认分析器;类似 JS、TS 或 CSS 的源码请用 text。自定义条目会追加到 detector 和 hooks 使用的内置类型之后。
项目边界
Impeccable 可以通过 package.json workspaces、pnpm-workspace.yaml 或 lerna.json 发现嵌套项目。如果你的设计边界不同,可以用 projectRoots 声明:
{ "projectRoots": ["docs/design/skins/*"] }
每个匹配的文件夹可以有自己的 PRODUCT.md 和 DESIGN.md,并出现在应用的 picker 中。缺少上下文时按文件逐一回退到仓库根目录。
模式优先级与私有根目录
模式相对于仓库根目录,支持 *、 和 ! 排除。本地的 projectRoots 条目会扩展共享列表。
对于被配置模式(包括排除模式)匹配的路径,projectRoots 优先于 package workspaces;其余路径由 package 声明决定。比如 !apps/internal 可以把包管理器包含的某个 app 排除掉;但包声明中的排除无法移除 Impeccable 配置中明确包含的根目录。
检查你的配置
如果某个设置似乎没生效,可以运行 doctor:
/impeccable doctor
它会检查未知键、过时的规则 ID,以及匹配不到任何内容的 project-root 模式。这些错误否则会让预期设置被静默忽略。
配置结构与 hook 设置
一个最小示例:
{ "detector": { "designSystem": { "enabled": true } }, "hook": { "enabled": true, "quiet": false } }
detector 保存手动扫描和 hooks 共用的设置,包括 ignoreRules、ignoreFiles 和 ignoreValues。ignore 命令会帮你维护这些字段。
hook 控制自动检查。安静模式会抑制"无问题"和"待处理"的提示,但保留新发现的问题。激活方式、逐次编辑检查、日志和环境变量覆盖详见 Design hooks。
顶层的 "stalenessCheck": false 可以关闭会话开始时关于上下文过期的提示。
关闭 design-system 检查
如果记录的设计系统已过时,请用 document 更新它。如果它本来就不作为权威依据,可以把 detector.designSystem.enabled 设为 false。
想只在某次扫描中跳过这些检查而不改配置:
npx impeccable detect --no-design-system src/
这会保留其他项目设置和 ignores。想在没有这些设置和本地 design-system 上下文的情况下扫描,用 --no-config。