用 Impeccable 给编码 Agent 装一套设计词汇与 61 条检测器：产品上下文、命令流与 CI 化审查实操

在项目根目录跑安装器，它会探测你机器上已有的 Agent 目录（如 ~/.claude、~/.codex、~/.grok，或项目内的 .cursor），让你选装哪些以及装到项目还是全局，然后写入对应工具的钩子清单。要写进脚本或 CI 就用非交互参数，把工具与作用域一次给全。

# 交互安装（在项目根目录执行）
npx impeccable install

# 非交互：指定工具与作用域，跳过询问
npx impeccable install --providers=claude,cursor,codex --scope=project -y

# 只装技能，不装编辑钩子
npx impeccable install --providers=claude --scope=project --no-hooks -y

装完记得重载编码工具。以 Claude Code 的项目级安装为例，它会写出 .claude/skills/impeccable/、.claude/agents/ 下的四个辅助子 Agent，以及 .claude/settings.local.json 里的 PostToolUse 与 Stop 钩子。其它路线也各有入口：Claude Code 可以走插件市场，VS Code + Copilot 可以装扩展（只有技能、没有钩子），ZIP 包则要把隐藏文件夹一起拷到项目根，和 package.json、src 并列，而不是再套一层目录。

验收只需要三步：查有没有新版本、需要就更新、然后在 Agent 对话里直接敲主命令。所有设计命令都挂在这个主技能上，不需要为 audit、polish、critique 分别安装。命令前缀随工具变：多数工具用 /impeccable，Codex 里用 $impeccable 或走 /skills 列表。

# 有没有新版本
npx impeccable check

# 更新技能与钩子清单（不会动 PRODUCT.md / DESIGN.md）
npx impeccable update

# 在 Agent 对话里（Codex 用 $impeccable）
/impeccable

没出现时按这个顺序排查：确认安装时选的是你正在用的那个工具；项目级安装必须在你当前打开的那个项目里；如果是拷贝 ZIP 装的，隐藏文件夹也要一起拷（Codex 的项目安装会带 .agents/skills/impeccable/SKILL.md，macOS 下用 Command–Shift–. 显示隐藏文件）；然后重载工具或开一个新会话。仍然不行，就去查工具的技能发现列表与权限设置。

init 会先读一遍项目，再只问它还缺的部分。你要描述的是这个产品给谁用、这些人要完成什么事、以及有哪些必须保留的东西（既有产品名、无障碍要求等），颜色与字体可以留给设计环节；它把商定的上下文写进 PRODUCT.md。这一步之后一定要读一遍文件、改正它理解错的地方——后续所有命令都按它来。已经有视觉体系的项目再跑 document，它会从代码里的 token 与组件反推出 DESIGN.md。

在 Agent 对话里执行（不是终端）

/impeccable init
  → 写 PRODUCT.md：受众、目的、约束、语气

/impeccable document
  → 写 DESIGN.md：既有的颜色、字体、组件规则

新起步的脚手架可以跳过 document

这两份文件的价值在于把「每次都要重讲一遍的项目背景」变成仓库里的资产。团队里换人、换 Agent、换模型，读的都是同一份上下文，产出的一致性会明显变好。

所有命令都走同一个技能，后面接一句大白话即可。常见的顺序是：先用 shape 只出方案不动代码；确认后用默认命令（直接说要建什么）开建；再用 critique 做 UX 复盘、audit 做技术体检、typeset 与 layout 修排版和间距、harden 补错误态与边界；最后 polish 收尾。语气类命令（bolder、quieter、distill、colorize、animate、delight、overdrive）调强度，adapt 适配其它设备、optimize 管性能、clarify 改文案、onboard 管空状态与引导、extract 把可复用组件与 token 抽回设计系统。

/impeccable shape 新人引导清单      # 先出方案，不动代码
/impeccable build 定价页             # 常规新建，不需要子命令
/impeccable critique 落地页          # 层级、清晰度、共鸣
/impeccable audit 页面头部           # 无障碍、性能、响应式
/impeccable typeset 博客模板         # 字体、层级、字号
/impeccable layout 设置页            # 间距与视觉节奏
/impeccable harden 结算流程          # 错误、多语言、文本溢出、边界
/impeccable polish 设置页            # 上线前的收尾

常用命令可以钉成快捷方式：
/impeccable pin audit
/impeccable unpin audit

钉快捷方式的好处是：它只是把请求转发给主技能，所以主技能升级后快捷方式自动跟着变，不需要重新钉一遍。删掉快捷方式也不会影响主命令。

技能之外还有一个独立的检测器引擎，跑的就是那 61 条规则：侧边标签的强调边框、紫蓝渐变、卡片套卡片、灰字压彩色底、对比度不足、字体层级扁平、跳过标题层级、滥用字体（Arial、Inter、系统默认）、弹性缓动等。因为不依赖模型，它可以放在三处：终端、CI、以及作为钩子在每次改 UI 文件后自动检查。终端用法是给一个路径或一个地址，加 --json 拿结构化输出便于在 CI 里判定；误报用 ignores 管理例外。

# 扫本地目录
npx impeccable detect src/

# 扫线上地址
npx impeccable detect https://example.com

# CI 里要结构化输出
npx impeccable detect src/ --json

# 管理例外
npx impeccable ignores add-value

还有配套的浏览器扩展，跑的是同一套规则，适合在看线上页面时随手扫一遍。把它接进 CI 最实际的价值是：AI 味的观感问题从「靠人眼在评审时抓」变成「流水线里的一条红线」。

想让整个团队用同一版本，把它作为 git submodule 加进项目再 link 到各自的工具：好处是版本写进仓库，谁拉到的都一样。队友用 git submodule update 取用记录的版本；升级就是更新 submodule 后重新 link，评审并提交新的引用。注意 link 只装技能，不装设计钩子，自动检查的钩子还要单独按各工具的信任要求配置。

git submodule add https://github.com/pbakaus/impeccable vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor

# 队友取用记录的版本
git submodule update --init --recursive

# 升级：更新 submodule → 重新 link → 评审并提交新引用
git submodule update --remote vendor/impeccable
npx impeccable link --source=vendor/impeccable --providers=claude,cursor

# 提交：.gitmodules、submodule 引用、生成的 link
# 已有技能目录不会被覆盖，除非显式加 --force

最后提醒一次更新与覆盖的边界：update 会替换它自己装的文件，但不会动你的 PRODUCT.md 与 DESIGN.md；install --force 只在确实要替换已有安装时使用。