Impeccable が AI プログラミングツールでフロントエンドを監査できるようにする方法: /impeccable の監査、設計コンテキスト、受け入れ

AI 能很快写出可运行的前端，却经常留下难以在单元测试中发现的问题：触控目标太小、层级跳跃、窄屏溢出、灰字压在彩色背景上，或每个区块都套进卡片。Impeccable 的定位不是替你再生成一套页面，而是给 AI 编程工具加上一套设计上下文、审计命令和可重复执行的检测规则，让“看起来还行”变成可以验收的前端质量检查。Impeccable 官方仓库

本文只讨论审计与验收：如何初始化设计上下文、使用 /impeccable audit、检查可访问性和响应式，以及把结果接入 Codex/Claude Code 的日常改动流程。

它与 Taste、Astryx 的分工不同

这些工具都能改善 AI 生成的界面，但切入点不同：

工具	更适合解决什么	本文不重复的部分
Taste	给生成过程加审美约束和前端风格方向	不展开安装与设计示例
Astryx	将设计系统、React 组件与主题约束交给 Agent	不展开组件库接入
Impeccable	记录设计上下文，审计已生成界面，并给出可复查问题	聚焦 audit、检测规则和发布验收

若你需要先建立风格方向，可阅读 Taste Skill 的安装与调用方法；若项目已有组件与主题体系，参考 Astryx 的设计系统接入流程。Impeccable 更适合作为它们之后的质量闸门。

安装到 AI 编程工具

在项目根目录运行官方推荐的安装命令：

1

npx impeccable install

安装器会检测可用的 harness 目录，例如 ~/.claude、~/.codex 或项目内 .cursor；你可选择项目级或全局安装。脚本化安装可显式指定 provider 和范围：

1

npx impeccable install --providers=claude,codex,cursor --scope=project

更新已存在的安装：

1

npx impeccable update

对 Codex 有两个容易漏掉的步骤：安装后重载工具，并打开 /hooks 批准项目 hook。Impeccable 会把 Codex hook 写入项目的 .codex/hooks.json，更新导致 hook 定义变化时，Codex 可能要求再次批准。

注意命令入口的差异：README 中展示的 /impeccable audit 适用于支持斜杠命令的界面；在 Codex 中它作为 Skill 使用，应通过 /skills 或 $impeccable 找到并调用，而不是假设存在 /prompts: 命令。

先初始化设计上下文，而不是立刻审计

从新项目开始时执行：

1

/impeccable init

init 会区分当前界面是品牌/营销页面还是产品/仪表盘，并写入 PRODUCT.md；可选的 DESIGN.md 会记录受众、产品定位、语气、反例、颜色、字体和组件约定。后续的 audit、polish、critique 才有判断依据，不会把每个项目都套进同一套“通用 SaaS 审美”。

既有项目则可先让它从代码生成根目录设计上下文：

1

/impeccable document

初始化后应人工检查两个文件：其中的品牌、受众、禁止项是否真实；设计令牌、组件和现有约束是否被正确识别。错误的上下文会让后续审计持续给出不适合项目的建议。

用 /impeccable audit 做技术质量审计

/impeccable audit 面向技术质量检查，覆盖可访问性、性能和响应式问题。它可以审计整个区域，也可以限定目标：

1
2
3


/impeccable audit
/impeccable audit the header
/impeccable audit blog

一次审计不要同时让 Agent 重构所有页面。更可靠的提示是要求它按严重程度输出问题、证据、受影响文件和最小修复方案，例如：

1
2
3
4


Use Impeccable to audit the checkout page.
Check keyboard navigation, form labels, error states, touch target size, narrow-screen overflow,
color contrast, and loading/empty states. Return findings grouped by blocker, major, and minor.
For each finding, cite the component and propose the smallest safe fix. Do not edit code yet.

先得到可审查报告，再批准改动。修复后再次运行 audit，确认问题消失且没有引入新的响应式或可访问性回归。

46 条确定性规则如何用于验收

Impeccable 除了基于 LLM 的设计评审，还提供 46 条无需 API key 的确定性 detector 规则。它们会检测常见 AI 前端模式与一般设计质量问题，例如过度使用的字体、紫色渐变、bounce easing、过小触控目标、拥挤内边距和跳过的标题层级。

不依赖 AI 编程工具时，也可以直接运行 CLI：

1
2
3


npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect --json .

--json 很适合 CI：把结果保存为构建工件，或在新增高严重度问题时使检查失败。不要把 detector 当成绝对审美裁判；它能稳定发现已知反模式，但无法替代真实用户、设计师或产品目标的判断。

把可访问性和响应式变成发布门槛

每次较大的 UI 改动可以采用这套顺序：

用 init/document 确认设计上下文仍有效。
让 /impeccable audit 只审计本次改动的页面或组件。
先修 blocker：键盘无法操作、表单标签缺失、内容溢出、错误信息不可见等。
在至少一个窄视口和一个宽视口人工查看；交互组件再做键盘和焦点检查。
运行 npx impeccable detect --json .，将新增问题与已有豁免分开。
修复后复跑 audit，并把报告或关键结论放进 PR 描述。

这种流程的目标不是追求检测结果为零，而是让每一项保留的规则命中都有理由、有记录，避免 AI 修改把已解决的设计问题重新带回来。

哪些 .impeccable 文件该提交，哪些不该提交

执行命令后，Impeccable 会在 .impeccable/ 下写入截图、缓存、会话状态、每位开发者配置和共享设计产物。不要把所有内容一并提交。

官方建议保持跟踪的共享文件包括：

1
2
3
4


.impeccable/config.json
.impeccable/live/config.json
.impeccable/design.json
.impeccable/critique/*.md

而 config.local.json、hook 缓存、截图、live 会话和预览文件一般应写入 .gitignore。如果截图曾被提交，单纯加入 .gitignore 不会停止追踪；需要用 git rm --cached <path> 将其从索引移除，同时保留本地文件。

常见问题

audit 报了很多“审美问题”，是否要全部改？

不必。先按 blocker、major、minor 分类，结合设计上下文和产品目标评估。品牌字体、历史页面或有意的视觉选择可以保留，但应在项目配置或文件注释中写明豁免原因，而不是每次忽略同一项。

检测规则和现有设计系统冲突怎么办？

不要修改代码去迎合默认规则。先检查 PRODUCT.md、DESIGN.md 和 .impeccable/config.json，将经过确认的组件、字体或设计令牌作为项目上下文或 ignore。规则应服务于系统一致性，而不是覆盖既有设计系统。

hook 会阻止所有 UI 修改吗？

不同工具的行为不同。Impeccable 的 README 说明：Claude Code、GitHub Copilot 和 Codex 在编辑后反馈检测发现；Cursor 则可在不佳的提议写入前阻止。对 Codex，记得在 /hooks 审核项目 hook 的内容和权限。

小结

Impeccable 的价值在于让 AI 前端修改有一条可验证的审计链：先建立 PRODUCT.md/DESIGN.md，再用 audit 限定范围检查可访问性、性能和响应式，最后用确定性 detector 与复跑结果作为验收依据。它与 Taste、Astryx 可以共存，但更适合放在生成和设计系统接入之后，承担前端质量检查这一环。