Impeccable 设计检测钩子实战指南在 Claude Code、Cursor、Codex 等 AI 编码工具中自动拦截 UI 质量缺陷【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本文是 Impeccable 设计语言PRODUCT.md中design detector hook设计检测钩子的完整技术指南。它讲解如何让 AI 编码工具Claude Code、Cursor、Codex、GitHub Copilot、Grok Build在每次编辑 UI 文件后自动运行设计检测器、把发现问题注入 Agent 上下文并通过/impeccable hooks命令完成开关、状态查看与精细化豁免管理。读完本文你将掌握钩子的两级规则调度机制、配置文件结构、六个管理动作的用法以及一套先修、再豁免、后询问的发现结果分诊方法论。钩子是什么项目级的自动设计质检设计检测钩子是 Impeccable 提供给当前项目的自动质检通道每当 AI 直接编辑到与设计相关的文件时钩子便运行 impeccable design detector设计检测器并把结果以短小的系统提醒推回 Agent 上下文。钩子扫描的文件类型由内置扩展名列表决定见 crates/hook/src/hook_lib.rs 中的ALLOWED_EXTS.tsx .jsx .html .htm .vue .svelte .astro .css .scss .sass .less .ts .js其中.ts、.js属于始终扫描但保持安静的类型检测器仍然运行但除非真的发现问题否则不输出任何提醒其余 UI 强相关扩展ACK_EXTS在扫描干净时会产生一个简短的确认信息ack。各工具的行为差异同一份钩子在不同 AI 编码工具中的触发机制不同理解这点是正确使用的前提工具触发方式行为Claude CodePostToolUse钩子匹配Edit\|Write编辑后推送简短提醒发现问题给修正提示待处理问题再次轻推干净文件给简短确认除非hook.quietCodexPostToolUse钩子与 Claude Code 相同的提醒机制GitHub CopilotpostToolUse钩子匹配edit\|create\|apply_patch与 Claude Code 相同的提醒机制CursorpreToolUse钩子在坏写入落地之前拦截检测器发现真实问题时拒绝该次 Write/Edit拒绝消息以工具错误的形式对 Agent 可见让 Agent 有机会重新考虑Grok BuildPostToolUse扫描 Stop事件扫描标记被改动的文件在 Stop 的additionalContext上呈现结果不要期待逐编辑提醒——Grok 会丢弃该 stdout这套钩子命令的识别与安装标记在 crates/context/src/hook_markers.rs 中实现is_impeccable_hook_command同时识别JS 时代的node .../hook.mjs旧形式与launcher 时代的.../impeccable hook新形式保证旧安装能被on动作修复而不是重复安装。两级规则体系即时层与深层扫描检测器规则分两层运行钩子默认只暴露即时层immediate tier即时层机械的、无歧义的、值得为它打断一次编辑的问题——坏图片、溢出或被裁剪的内容、对比度与可读性失败、渐变文字、发光阴影、设计系统漂移等。深层扫描deep pass其余一切文案节奏、调色板与字体品味、布局韵律推迟到Stop钩子事件触发时对会话中接触过的每个 UI 文件运行完整规则集只呈现一次并与逐编辑阶段已报告的发现去重。从源码看即时层规则清单由impeccable_core::registry::IMMEDIATE_TIER_RULES提供crates/hook/src/hook_lib.rssplit_findings_by_tier依据规则 id 是否命中该清单决定发现进入即时还是推迟队列。各工具的深层扫描支持情况Claude Code、Codex、Grok Build支持原生Stop钩子事件默认启用两级调度Cursor不提供 Stop 深层扫描其 stop 钩子不能稳定分发由 pre-write 闸门覆盖因此不会推迟非即时规则GitHub Copilot其 stop 类事件无法把上下文反馈给模型因此每次编辑都运行完整检测器。关键的恢复开关是配置项hook.perEditRules设为all可让每次编辑都运行完整规则集代码中per_edit_tiering_activecrates/hook/src/hook_lib.rs正是按此逻辑判断——对 Cursor 和 GitHub 返回false不启用分档其余工具仅在perEditRules ! all时分档。此外Grok Build 在end_turn之后还会触发一个仅观察的 Stop 事件reason: shutdown钩子应跳过该事件只扫描end_turn。没有钩子时的兜底每个钩子都是机械检查扫描器抓不到的反射动作reflexes记录在 craft-floor.md 中skill 会在编辑 UI 前加载它因此无论钩子是否接线这些质量底线都生效。如果某次会话没有任何自动钩子impeccable context会给出一次MANUAL_DETECTOR_REQUIRED指令要求在会话结束时手动运行一次检测器。配置文件项目级开关与开发者级覆盖钩子按项目管理配置写入统一配置文件.impeccable/config.json钩子运行时设置位于其hook键下检测器的共享忽略规则位于detector键下开发者级覆盖包括 CLI 记录的安装同意决定hook.consent写在 gitignored 的.impeccable/config.local.json中。read_configcrates/hook/src/hook_lib.rs按先共享、后本地的顺序合并两个文件后者的值覆盖前者。hook 键参数参数默认值说明hook.enabledtrue设为false关闭自动钩子仅控制自动执行不影响手动 CLI 扫描hook.quietfalse设为true静默干净文件/待处理问题的确认信息hook.auditLog无指向一个 NDJSON 日志文件的路径开启审计日志hook.perEditRulesimmediate设为all恢复每次编辑都运行完整规则集hook.consent无本地安装同意记录由 CLI 在on时写入config.local.jsonhook.limits.maxFindings5单次呈现的发现数量上限hook.limits.maxChars8000提醒文本的字符预算上限hook.limits.maxFileBytes131072参与扫描的文件字节数上限这些默认值在HookConfig::default()中定义crates/hook/src/hook_lib.rsmaxFindings/maxChars低于 1 时回退到默认值且渲染时maxChars至少取 500。遗留环境变量兼容旧版环境变量仍然生效且设置时覆盖配置文件IMPECCABLE_HOOK_DISABLED如1——一次性关闭钩子跟随当前 shellIMPECCABLE_HOOK_QUIET——静默确认信息IMPECCABLE_HOOK_LOG——审计日志路径。status动作会在报告末尾显示IMPECCABLE_HOOK_DISABLED的当前状态...1或unset。detector 键与模板引擎扩展detector键承载检测器的共享忽略配置detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues、detector.designSystem.enabled默认开启。手动npx impeccable detect扫描默认使用同一套项目过滤配置hook.enabled只管自动钩子不影响手动扫描。当项目使用Blade、Twig、ERB 或 Handlebars等服务端模板时需在detector.extensions中声明扩展名否则钩子会跳过这些文件它们不在内置列表内。每项一条engine选择分析器标记模板用html类 JS/TS/CSS 文件用text默认html匹配按文件名末尾进行因此.blade.php、.html.erb这类双扩展名也能工作{ detector: { extensions: [ { ext: .blade.php, engine: html }, { ext: .html.erb, engine: html } ] } }注意配置只会新增扩展内置列表始终生效。配置项解析与匹配逻辑见 crates/hook/src/hook_lib.rsnormalize_extension_entries、match_configured_extension。detector.extensions是唯一没有管理动作的字段如需覆盖模板栈只能直接编辑.impeccable/config.json中的该字段。命令路由六个管理动作/impeccable hooks的第一个参数是动作默认status。后台实现位于 crates/hook/src/admin.rs 的admin::run动作表与源码中ACTIONS常量一致动作作用status打印当前状态共享/本地配置路径、被忽略的规则/文件/值、环境变量覆盖on在.impeccable/config.json写入enabled: true在本地配置记录钩子同意为 accepted并在 skill 已安装时为各工具安装/修复钩子 manifestoff在.impeccable/config.json写入enabled: falseignore-rule id把id追加到detector.ignoreRules对overused-font必须加--all-values。在整个项目范围内压制该规则ignore-file glob把glob追加到detector.ignoreFiles对匹配文件压制所有规则ignore-value id value [--shared] [--reason ...]向共享.impeccable/config.json追加规则/值压制ignore-value id value --local [--reason ...]向.impeccable/config.local.json追加私有规则/值压制ignore-value id * --file glob [--file glob...]只在匹配文件中关闭某一条规则其余文件仍然生效。可重复--file或使用--fileglob/--filesglob。裸*不带--file会被拒绝——真要项目级压制就用ignore-rule idreset删除项目配置、去重缓存和 Cursor 待处理队列并从on安装过的每个 provider manifest 中移除钩子条目包括已提交的 Copilot 文件团队共享的settings.json从不被on写入因此也不被动从源码看on动作会做三件事crates/hook/src/admin.rs写共享配置的enabled: true、写本地配置的consent: accepted、调用repair_hook_manifests修复各工具的 manifestreset必须把这三件事全部撤销源码注释明确引用了 issue #512 的教训残留的 manifest 条目会在配置删除后继续调用钩子。ignore-value解析支持--reason空格或两种写法、--file/--files三种变体且拒绝规则根本提取不出该值的死条目synthetic_ignore_value为空时报错。执行流程从用户参数中解析动作未给动作时默认status。调用管理脚本把用户输出原样透传.trae/skills/impeccable/scripts/impeccable hooks action [args...]动作为off时追加一行说明Done. New edits will not trigger the design hook in this project until you run/impeccable hooks on.动作为on时追加Done. The design hook will fire after the next Edit/Write on a UI file.动作为ignore-value、ignore-file或ignore-rule时直接打印脚本输出。默认作用域是共享的.impeccable/config.json仅当用户明确要求私有豁免时才加--local。动作为status时直接打印脚本输出除非用户追问否则不加评论。脚本路径在不同工具下解析为 skill 目录内的 launcherWindows 上用impeccable.cmd。status报告的样例结构源码status_report生成大致为状态、共享/本地文件路径损坏文件标注(malformed; ignored)、ignoreRules/ignoreFiles/ignoreValues列表、maxFindings/maxChars、环境变量覆盖、缓存文件路径。发现结果的分诊Triage钩子本身从不写忽略配置一切豁免都走impeccable hooks。每个发现归入三类结果真实设计问题修复它。绝不用忽略来跳过修复或放行被拦截的写入。确信的误报或认可的例外自行持久化最窄的忽略并在回复中披露。依据必须是你点得出的证据有意的演示或 fixture、对坏设计的文档化、字面或领域合适的动效比如弹跳的球或用户已确认的选择。把证据写进--reason格式为who decided: evidence只有用户真的确认过才写 user confirmed。不确定保留发现用一行向用户提问。只问一次——一行问题比钩子在之后每次编辑上重复触发要便宜得多。自助操作止于ignore-valueignore-file和ignore-rule压制面太大不能凭自己的判断添加先问用户。豁免阶梯从最窄到最宽优先使用最窄的例外发现行给出了ignore-value rule value对时直接透传给impeccable hooks ignore-value并带--reason默认写入共享配置。值型发现如overused-font、bounce-easing用ignore-value针对具体值不要用ignore-rule overused-font去豁免某个具体字体。发现没有值型命令时如side-tab把该规则限定到文件ignore-value id * --file path。先跑npx impeccable detect path看实际触发什么。仅当整个文件都不在设计评审范围内fixture、生成产物、刻意做的 slop 演示才用ignore-file path——它会永久压制该文件所有规则包括尚未写出的规则。真实 UI 表面只有一个规则吵闹时用上面的文件级值豁免。仅当用户要求项目级压制整条规则时才用ignore-rule id对overused-font的广泛压制只有用户要求整体忽略过度使用字体时才用ignore-rule overused-font --all-values。优先用配置忽略上述命令让压制集中在一个可评审的地方。只有豁免必须随单个文件离开仓库时生成/导出的独立文档、邮件发送的 HTML才用内联注释。受支持的标记为impeccable-disable rule整文件或impeccable-disable-line/impeccable-disable-next-line单行任意注释语法均可可在:或--后加可选理由。检测器默认遵循它--no-inline-ignores或--no-config会绕过。内联忽略的解析实现位于 crates/foundation/src/inline_ignores.rs。实操示例值型例外共享配置.trae/skills/impeccable/scripts/impeccable hooks ignore-value overused-font Inter --shared --reason User confirmed Inter is intentional自助例外证据具名.trae/skills/impeccable/scripts/impeccable hooks ignore-value bounce-easing bounce-ball --shared --reason Agent: literal ball-bounce animation, bounce easing is the subject整条规则的字体例外.trae/skills/impeccable/scripts/impeccable hooks ignore-rule overused-font --all-values --reason User asked to ignore overused fonts generally单规则单文件例外文件其余内容仍值得评审.trae/skills/impeccable/scripts/impeccable hooks ignore-value design-system-font-size * --file src/overlay/widget.js --reason Injected widget builds its own type scale; DESIGN.mds ramp describes the site整文件例外文件完全超出范围.trae/skills/impeccable/scripts/impeccable hooks ignore-file src/legacy/Card.tsx支持的 harness 与安装位置钩子随 Impeccable skill 打包通过项目本地 manifest 安装工具Manifest 路径说明Claude Code.claude/settings.local.jsongitignored钩子保持机器本地移入共享settings.json也会被就地生效Codex.codex/hooks.json首次需用户通过/hooks批准Cursor.cursor/hooks.json需在 Settings - Hooks 确认钩子已启用Grok Build.grok/hooks/impeccable.json需要/hooks-trust或--trustGitHub Copilot.github/hooks/impeccable.json团队共享的已提交文件CLI 与云端 Agent 都会读取CLI 在文件提交到默认分支后触发仓库级钩子Manifest 的目标与命令模板定义在 crates/hook/src/admin.rs 的HOOK_MANIFEST_TARGETS中Claude/Codex 用 launcher 命令.../impeccable hookCursor 用hook-before-editCopilot 用仓库根锚定的$(git rev-parse --show-toplevel)/.github/skills/impeccable/scripts/impeccable hookCodex 的 Windows 变体还带commandWindows指向.cmdshim。on在写入时对已有 manifest 做合并保留非 Impeccable 的钩子条目见merge_hook_manifests损坏的 manifest 会先备份为.bak。约束不要从本命令手工修改.impeccable/config.json或.impeccable/config.local.json一律通过impeccable hooks写入保证写入经过校验、文件形状保持一致。唯一例外detector.extensions没有管理动作用户要求覆盖模板栈时直接编辑该字段其余部分不动。不要从该流程编辑impeccable hook和impeccable hook-before-edit背后的 launcher 或二进制——那是 skill 管道。Cursor 能在检测器发现真实问题时拦截提议的写入Claude Code、Codex 和 GitHub Copilot 不拦截编辑而是发出编辑后提醒。关闭钩子会同时停止拦截与提醒。失败模式若.impeccable/config.json或.impeccable/config.local.json不可读或格式损坏钩子忽略该文件使用其余有效配置/默认值impeccable hooks status会把损坏文件显示为malformed; ignored。对应实现见read_raw_config_filecrates/hook/src/admin.rs。用户要求全局禁用钩子时先用/impeccable hooks off对本项目持久化写入hook.enabled: false。遗留环境变量IMPECCABLE_HOOK_DISABLED1也可作为跟随 shell 的一次性覆盖。小结设计检测钩子把每次编辑后做一次机械设计质检从手工流程变成了多工具通用的自动化机制两级规则调度保证编辑不被高频噪音打断、深层问题又能在 Stop 时一次性补全统一的.impeccable/config.json让开关、静默、审计、忽略与模板扩展都在一处管理impeccable hooks的六个动作配合最窄豁免阶梯让误报处理既有据可查又不越权。无论你的主力工具是 Claude Code、Cursor、Codex、GitHub Copilot 还是 Grok Build这套机制都能让设计质量防线与你的日常编辑流程无缝贴合。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考